feat(ansi): rename writeAnsi/createAnsiWriter to printAnsi/createAnsiPrinter

AGENTS.md

@@ -152,20 +152,20 @@ Located at `packages/comark-ansi/`. ANSI terminal renderer.
 ### Usage
 
 ```typescript
-import { createAnsiRenderer, createAnsiWriter, renderAnsi, renderAnsiFromDocument, writeAnsi } from '@comark/ansi'
+import { createAnsiRenderer, createAnsiPrinter, printAnsi, renderAnsi, renderAnsiFromDocument } from '@comark/ansi'
 import shiki from '@comark/ansi/plugins/shiki'
 import math, { Math } from '@comark/ansi/plugins/math'
 
 // Flat options — ParserOptions & AnsiRendererOptions merged at top level
-const writeAnsi = createAnsiWriter({
+const printAnsi = createAnsiPrinter({
   plugins: [shiki(), math()],
   components: { Math },
   width: 120,                      // terminal width
   colors: true,                    // emit ANSI escape codes
   writer: (output) => process.stderr.write(output),
 })
 
-await writeAnsi(markdownString)
+await printAnsi(markdownString)
 ```
 
 ---
@@ -382,7 +382,7 @@ import { parseMarkdown, autoCloseMarkdown } from 'comark'
 import { createHtmlRenderer, renderHtml, renderHtmlFromDocument } from '@comark/html'
 
 // ANSI terminal rendering
-import { createAnsiRenderer, createAnsiWriter, renderAnsi, renderAnsiFromDocument, writeAnsi } from '@comark/ansi'
+import { createAnsiRenderer, createAnsiPrinter, printAnsi, renderAnsi, renderAnsiFromDocument } from '@comark/ansi'
 
 // Markdown string rendering (AST → markdown)
 import { renderMarkdown } from 'comark/render'
@@ -425,7 +425,7 @@ import math, { Math } from '@comark/html/plugins/math'
 import mermaid, { Mermaid } from '@comark/html/plugins/mermaid'
 
 // ANSI terminal rendering — parse + render to styled terminal string
-import { createAnsiRenderer, createAnsiWriter, renderAnsi, renderAnsiFromDocument, writeAnsi } from '@comark/ansi'
+import { createAnsiRenderer, createAnsiPrinter, printAnsi, renderAnsi, renderAnsiFromDocument } from '@comark/ansi'
 import shiki from '@comark/ansi/plugins/shiki'
 import math from '@comark/ansi/plugins/math'
 

benchmarks/plugin-punctuation.ts

@@ -3,7 +3,7 @@ import MarkdownExit from 'markdown-exit'
 import { markdownItComponents } from 'comark/plugins/components'
 import { markdownItAttributes } from 'comark/plugins/attributes'
 import { createMarkdownParser } from 'comark'
-import { writeAnsi } from '@comark/ansi'
+import { printAnsi } from '@comark/ansi'
 import punctuation from '../packages/comark/src/plugins/punctuation'
 
 // ── Test content (exercises ALL features: quotes, dashes, ellipsis, symbols, normalization) ──
@@ -146,7 +146,7 @@ console.log('comark punctuation:     ', JSON.stringify(flattenText(comarkTree.no
 console.log('\n🏃 Running benchmarks...\n')
 await run()
 
-await writeAnsi(`> [!NOTE]
+await printAnsi(`> [!NOTE]
 > The goal of this benchmark is to compare the additional time each parser takes when
 > using punctuation plugins.
 >

docs/content/3.rendering/8.ansi.md

@@ -172,16 +172,20 @@ Same as [`renderAnsi()`](#renderansi-options).
 
 ---
 
-## `writeAnsi()`
+## `printAnsi()`
 
 Parse and print markdown directly to `stdout` in one call.
 
+::note
+`printAnsi()` replaces `writeAnsi()`, which is deprecated and will be removed in the next major version.
+::
+
 ### Usage
 
 ```ts
-import { writeAnsi } from '@comark/ansi'
+import { printAnsi } from '@comark/ansi'
 
-await writeAnsi(`
+await printAnsi(`
 # Hello World
 
 This is **bold**, _italic_, and \`inline code\`.
@@ -196,10 +200,10 @@ This is **bold**, _italic_, and \`inline code\`.
 Pass options to configure the parser, renderer, or output destination using `writer`:
 
 ```ts
-import { writeAnsi } from '@comark/ansi'
+import { printAnsi } from '@comark/ansi'
 import math, { Math } from '@comark/ansi/plugins/math'
 
-await writeAnsi('Inline $E = mc^2$', {
+await printAnsi('Inline $E = mc^2$', {
   plugins: [math()],
   components: { Math },
   width: 100,
@@ -209,31 +213,35 @@ await writeAnsi('Inline $E = mc^2$', {
 
 They are the same options as [`renderAnsi()`](#renderansi-options) plus the `writer?: (string: string) => void` option.
 
-### `createAnsiWriter()`
+### `createAnsiPrinter()`
 
-Creates a reusable writer with pre-configured options. The underlying parser is initialized once and reused on every call, which is more efficient when writing many documents.
+Creates a reusable printer with pre-configured options. The underlying parser is initialized once and reused on every call, which is more efficient when printing many documents.
+
+::note
+`createAnsiPrinter()` replaces `createAnsiWriter()`, which is deprecated and will be removed in the next major version.
+::
 
 #### Usage
 
 ```ts
-import { createAnsiWriter } from '@comark/ansi'
+import { createAnsiPrinter } from '@comark/ansi'
 import math, { Math } from '@comark/ansi/plugins/math'
 import shiki from '@comark/ansi/plugins/shiki'
 
-const write = createAnsiWriter({
+const print = createAnsiPrinter({
   plugins: [math(), shiki()],
   components: { Math },
   width: 120,
 })
 
-// Reuse the same configured parser & writer
-await write('# Document 1\n\n...')
-await write('# Document 2\n\n...')
+// Reuse the same configured parser & printer
+await print('# Document 1\n\n...')
+await print('# Document 2\n\n...')
 ```
 
 #### Options
 
-Same as [`writeAnsi()`](#writeansi-options).
+Same as [`printAnsi()`](#printansi-options).
 
 ---
 
@@ -329,12 +337,12 @@ Each type has its own color: NOTE → blue, TIP → green, IMPORTANT → magenta
 Code blocks show the language and filename in a header line. When the `shiki` plugin is used, tokens are rendered with true-color ANSI (`\x1b[38;2;R;G;Bm`) derived from Shiki's dark theme:
 
 ```typescript
-import { createAnsiWriter } from '@comark/ansi'
+import { createAnsiPrinter } from '@comark/ansi'
 import shiki from '@comark/ansi/plugins/shiki'
 
-const writeAnsi = createAnsiWriter({ plugins: [shiki()] })
+const printAnsi = createAnsiPrinter({ plugins: [shiki()] })
 
-await writeAnsi('```typescript [app.ts]\nconsole.log("hello")\n```')
+await printAnsi('```typescript [app.ts]\nconsole.log("hello")\n```')
 // typescript  app.ts
 // console.log("hello")   ← syntax highlighted
 ```
@@ -344,12 +352,12 @@ await writeAnsi('```typescript [app.ts]\nconsole.log("hello")\n```')
 Math expressions from the `math` plugin render as colored LaTeX source: inline in yellow, block in magenta:
 
 ```typescript
-import { createAnsiWriter } from '@comark/ansi'
+import { createAnsiPrinter } from '@comark/ansi'
 import math, { Math } from '@comark/ansi/plugins/math'
 
-const writeAnsi = createAnsiWriter({ plugins: [math()], components: { Math } })
+const printAnsi = createAnsiPrinter({ plugins: [math()], components: { Math } })
 
-await writeAnsi('Inline $E = mc^2$ and block:\n\n$$\n\\frac{a}{b}\n$$')
+await printAnsi('Inline $E = mc^2$ and block:\n\n$$\n\\frac{a}{b}\n$$')
 ```
 
 ### Tables

docs/content/5.reference/3.reference.md

@@ -160,28 +160,28 @@ const output = await renderAnsiFromDocument(document)
 process.stdout.write(output)
 ```
 
-#### `writeAnsi(markdown, options?)`
+#### `printAnsi(markdown, options?)`
 
-Parse and render markdown directly to stdout.
+Parse and render markdown directly to stdout. Replaces the deprecated `writeAnsi` alias.
 
 ```typescript
-import { writeAnsi } from '@comark/ansi'
+import { printAnsi } from '@comark/ansi'
 
-await writeAnsi('# Hello\n\nThis is **bold**.')
+await printAnsi('# Hello\n\nThis is **bold**.')
 ```
 
-#### `createAnsiWriter(options?)`
+#### `createAnsiPrinter(options?)`
 
-Create a reusable Markdown writer. Pass `writer` to target something other than `process.stdout`.
+Create a reusable Markdown printer. Pass `writer` to target something other than `process.stdout`. Replaces the deprecated `createAnsiWriter` alias.
 
 ```typescript
-import { createAnsiWriter } from '@comark/ansi'
+import { createAnsiPrinter } from '@comark/ansi'
 
-const writeAnsi = createAnsiWriter({
+const printAnsi = createAnsiPrinter({
   writer: (output) => process.stderr.write(output),
 })
 
-await writeAnsi('# Hello')
+await printAnsi('# Hello')
 ```
 
 ---
@@ -353,8 +353,8 @@ import {
   renderAnsi,
   renderAnsiFromDocument,
   createAnsiRenderer,
-  writeAnsi,
-  createAnsiWriter,
+  printAnsi,
+  createAnsiPrinter,
 } from '@comark/ansi'
 
 // Vue

docs/skills/comark/AGENTS.md

@@ -177,18 +177,18 @@ export class ChatComponent {
 Use `@comark/ansi` to render LLM markdown output in terminal-based agents:
 
 ```typescript
-import { writeAnsi } from '@comark/ansi'
+import { printAnsi } from '@comark/ansi'
 
 // Print a complete LLM response to stdout with ANSI styling
-await writeAnsi(llmResponse)
+await printAnsi(llmResponse)
 ```
 
-For repeated terminal output, use `createAnsiWriter` with a custom `writer` function:
+For repeated terminal output, use `createAnsiPrinter` with a custom `writer` function:
 
 ```typescript
-import { createAnsiWriter } from '@comark/ansi'
+import { createAnsiPrinter } from '@comark/ansi'
 
-const writeMarkdown = createAnsiWriter({
+const writeMarkdown = createAnsiPrinter({
   writer: (output) => process.stdout.write(output),
 })
 

examples/3.cli/ansi/render.ts

@@ -1,10 +1,10 @@
 import { readFile } from 'node:fs/promises'
-import { writeAnsi } from '@comark/ansi'
+import { printAnsi } from '@comark/ansi'
 import shiki from '@comark/ansi/plugins/shiki'
 import math, { Math } from '@comark/ansi/plugins/math'
 
 const md = await readFile('source.md', 'utf-8')
-await writeAnsi(md, {
+await printAnsi(md, {
   plugins: [shiki(), math()],
   components: { Math },
 })

packages/comark-ansi/README.md

@@ -71,18 +71,18 @@ const output = await renderAnsi('```ts\nconsole.log("hi")\n```', {
 - `renderAnsi(markdown, options?)` parses and renders Markdown to an ANSI string.
 - `createAnsiRenderer(options?)` creates a reusable parse-and-render function.
 - `renderAnsiFromDocument(document, options?)` renders a pre-parsed `MarkdownDocument`.
-- `writeAnsi(markdown, options?)` parses and writes Markdown to `process.stdout` or a custom `writer`.
-- `createAnsiWriter(options?)` creates a reusable writer.
+- `printAnsi(markdown, options?)` parses and writes Markdown to `process.stdout` or a custom `writer`. (`writeAnsi` is a deprecated alias.)
+- `createAnsiPrinter(options?)` creates a reusable printer. (`createAnsiWriter` is a deprecated alias.)
 
 ```ts
-import { createAnsiWriter } from '@comark/ansi'
+import { createAnsiPrinter } from '@comark/ansi'
 
-const writeAnsi = createAnsiWriter({
+const printAnsi = createAnsiPrinter({
   colors: false,
   writer: (output) => process.stderr.write(output),
 })
 
-await writeAnsi('# Build complete')
+await printAnsi('# Build complete')
 ```
 
 ## Documentation

packages/comark-ansi/src/index.ts

@@ -13,34 +13,41 @@ function defaultWriter(string: string) {
 }
 
 /**
- * Options for creating an ANSI writer.
+ * Options for creating an ANSI printer.
  */
-export interface AnsiWriterOptions extends AnsiRendererOptions, ParserOptions {
+export interface AnsiPrinterOptions extends AnsiRendererOptions, ParserOptions {
   writer?: (string: string) => void
 }
 
 /**
- * Creates a reusable writer with pre-configured parse and render options.
+ * Options for creating an ANSI printer.
+ *
+ * @deprecated Use {@link AnsiPrinterOptions} instead. Will be removed in the next major version.
+ */
+export type AnsiWriterOptions = AnsiPrinterOptions
+
+/**
+ * Creates a reusable printer with pre-configured parse and render options.
  *
  * @param options - Comark parse and render options (plugins, autoClose, etc.)
  * @returns An async function `(markdown) => Promise<void>` that prints to stdout
  *
  * @example
  * ```typescript
- * import { createAnsiWriter } from '@comark/ansi'
+ * import { createAnsiPrinter } from '@comark/ansi'
  * import math, { Math } from '@comark/ansi/plugins/math'
  *
- * const writeAnsi = createAnsiWriter({
+ * const printAnsi = createAnsiPrinter({
  *   plugins: [math()],
  *   components: { Math },
  *   width: 120,
  *   writer: (s) => process.stderr.write(s)
  * })
  *
- * await writeAnsi('# Hello\n\nThis is **bold**.')
+ * await printAnsi('# Hello\n\nThis is **bold**.')
  * ```
  */
-export function createAnsiWriter(options?: AnsiWriterOptions): (markdown: string) => Promise<void> {
+export function createAnsiPrinter(options?: AnsiPrinterOptions): (markdown: string) => Promise<void> {
   const renderAnsi = createAnsiRenderer(options as AnsiRendererOptions)
   const write = options?.writer ?? defaultWriter
   return async (markdown: string) => {
@@ -49,6 +56,13 @@ export function createAnsiWriter(options?: AnsiWriterOptions): (markdown: string
   }
 }
 
+/**
+ * Creates a reusable printer with pre-configured parse and render options.
+ *
+ * @deprecated Use {@link createAnsiPrinter} instead. Will be removed in the next major version.
+ */
+export const createAnsiWriter = createAnsiPrinter
+
 /**
  * Parse markdown and print it as ANSI-styled output to stdout.
  *
@@ -57,15 +71,22 @@ export function createAnsiWriter(options?: AnsiWriterOptions): (markdown: string
  *
  * @example
  * ```typescript
- * import { writeAnsi } from '@comark/ansi'
+ * import { printAnsi } from '@comark/ansi'
  *
- * await writeAnsi('# Hello\n\nThis is **bold** and _italic_.')
+ * await printAnsi('# Hello\n\nThis is **bold** and _italic_.')
  * ```
  */
-export async function writeAnsi(markdown: string, options?: AnsiWriterOptions): Promise<void> {
-  return createAnsiWriter(options)(markdown)
+export async function printAnsi(markdown: string, options?: AnsiPrinterOptions): Promise<void> {
+  return createAnsiPrinter(options)(markdown)
 }
 
+/**
+ * Parse markdown and print it as ANSI-styled output to stdout.
+ *
+ * @deprecated Use {@link printAnsi} instead. Will be removed in the next major version.
+ */
+export const writeAnsi = printAnsi
+
 /**
  * Creates a reusable render function with pre-configured parse and render options.
  *