@cyanheads/mcp-ts-core 0.1.0-beta.12

package/skills/api-services/references/speech.md

@@ -0,0 +1,72 @@
+# Speech Service (`services/speech`)
+
+## `ISpeechProvider` interface
+
+The provider interface — implemented by ElevenLabs (TTS) and Whisper (STT):
+
+| Member | Type | Notes |
+|:-------|:-----|:------|
+| `.textToSpeech(opts)` | `Promise<TextToSpeechResult>` | Synthesize speech from text |
+| `.speechToText(opts)` | `Promise<SpeechToTextResult>` | Transcribe audio to text |
+| `.getVoices()` | `Promise<Voice[]>` | List available voices (TTS providers only) |
+| `.healthCheck()` | `Promise<boolean>` | Liveness check |
+| `.supportsTTS` | `boolean` | Check before calling `textToSpeech` |
+| `.supportsSTT` | `boolean` | Check before calling `speechToText` |
+| `.name` | `string` | Provider identifier (e.g., `'elevenlabs'`) |
+
+## `SpeechService` orchestrator
+
+`SpeechService` does **not** expose `textToSpeech`/`speechToText` directly. It manages independent TTS and STT provider instances. Access the underlying providers via accessors:
+
+| Method | Return | Notes |
+|:-------|:-------|:------|
+| `.getTTSProvider()` | `ISpeechProvider` | Throws `McpError(InvalidRequest)` if no TTS provider configured |
+| `.getSTTProvider()` | `ISpeechProvider` | Throws `McpError(InvalidRequest)` if no STT provider configured |
+| `.hasTTS()` | `boolean` | Check if TTS is available |
+| `.hasSTT()` | `boolean` | Check if STT is available |
+| `.healthCheck()` | `Promise<{ tts: boolean; stt: boolean }>` | Checks both providers in parallel |
+
+## Providers
+
+| Provider | Capability | Tier 3 peer |
+|:---------|:-----------|:------------|
+| `ElevenLabsProvider` | TTS only (`supportsTTS: true`, `supportsSTT: false`) | ElevenLabs API (direct HTTP) |
+| `WhisperProvider` | STT only (`supportsTTS: false`, `supportsSTT: true`) | `openai` (Whisper API). 25MB file size limit. |
+
+## Configuration
+
+| Env Var | Purpose |
+|:--------|:--------|
+| `SPEECH_TTS_ENABLED` | Enable TTS (`true`/`false`) |
+| `SPEECH_TTS_API_KEY` | TTS provider API key (e.g., ElevenLabs) |
+| `SPEECH_TTS_DEFAULT_MODEL_ID` | Default TTS model ID |
+| `SPEECH_TTS_DEFAULT_VOICE_ID` | Default TTS voice ID |
+| `SPEECH_STT_ENABLED` | Enable STT (`true`/`false`) |
+| `SPEECH_STT_API_KEY` | STT provider API key (e.g., OpenAI) |
+
+## Usage
+
+```ts
+// Text-to-Speech — access the provider, then call methods on it
+const ttsProvider = speechService.getTTSProvider();
+const ttsResult = await ttsProvider.textToSpeech({
+  text: 'Hello, world!',
+  voice: 'some-voice-id',
+  outputFormat: 'mp3_44100_128',
+});
+
+// Speech-to-Text
+const sttProvider = speechService.getSTTProvider();
+const sttResult = await sttProvider.speechToText({
+  audioData: buffer,
+  mimeType: 'audio/mp3',
+  language: 'en',
+});
+
+// List available voices
+const voices = await ttsProvider.getVoices();
+
+// Health check
+const health = await speechService.healthCheck();
+// health: { tts: boolean, stt: boolean }
+```

package/skills/api-testing/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: api-testing
+description: >
+  Testing patterns for MCP tool/resource handlers using `createMockContext` and Vitest. Covers mock context options, handler testing, McpError assertions, format testing, Vitest config setup, and test isolation conventions.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+Tests target handler behavior directly — call `handler(input, ctx)`, assert on the return value or thrown error. The framework's handler factory (try/catch, formatting, telemetry) is not involved. Use `createMockContext` from `@cyanheads/mcp-ts-core/testing` to construct the `ctx` argument.
+
+**Philosophy:** Test behavior, not implementation. Refactors should not break tests. Colocate test files with source (`foo.tool.ts` → `foo.tool.test.ts`). Integration tests at I/O boundaries over unit tests of internals.
+
+---
+
+## `createMockContext` options
+
+```ts
+import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+
+createMockContext()                                           // minimal — ctx.state operations throw without tenantId
+createMockContext({ tenantId: 'test-tenant' })               // enables ctx.state (tenant-scoped in-memory storage)
+createMockContext({ sample: vi.fn().mockResolvedValue(...) }) // with MCP sampling
+createMockContext({ elicit: vi.fn().mockResolvedValue(...) }) // with elicitation
+createMockContext({ progress: true })                        // with task progress (ctx.progress populated)
+createMockContext({ requestId: 'my-id' })                    // override request ID (default: 'test-request-id')
+createMockContext({ signal: controller.signal })             // custom AbortSignal
+createMockContext({ auth: { clientId: 'test', scopes: [] } }) // with auth context
+createMockContext({ uri: new URL('myscheme://item/123') })   // for resource handler testing
+```
+
+`MockContextOptions` interface:
+
+```ts
+interface MockContextOptions {
+  auth?: AuthContext;
+  elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
+  progress?: boolean;
+  requestId?: string;
+  sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
+  signal?: AbortSignal;
+  tenantId?: string;
+  uri?: URL;
+}
+```
+
+| Option | Effect |
+|:-------|:-------|
+| _(none)_ | Minimal context — `ctx.state` operations throw without `tenantId`; `ctx.elicit`/`ctx.sample`/`ctx.progress` are `undefined` |
+| `auth` | Sets `ctx.auth` for scope-checking tests |
+| `elicit` | Assigns a function to `ctx.elicit` for testing elicitation calls |
+| `progress` | Populates `ctx.progress` with real state-tracking implementation (see below) |
+| `requestId` | Overrides `ctx.requestId` (default: `'test-request-id'`) |
+| `sample` | Assigns a function to `ctx.sample` for testing sampling calls |
+| `signal` | Overrides `ctx.signal` — useful for cancellation testing |
+| `tenantId` | Sets `ctx.tenantId` and enables `ctx.state` operations with in-memory storage |
+| `uri` | Sets `ctx.uri` for resource handler testing |
+
+### Mock progress
+
+When `progress: true`, `ctx.progress` is a real state-tracking object — not `vi.fn()` spies. It maintains internal state accessible via inspection properties:
+
+```ts
+const ctx = createMockContext({ progress: true });
+// ctx.progress is typed as ContextProgress, but the mock exposes internal state:
+const progress = ctx.progress as ContextProgress & {
+  _total: number;
+  _completed: number;
+  _messages: string[];
+};
+
+await ctx.progress!.setTotal(10);
+await ctx.progress!.increment(3);
+await ctx.progress!.update('step message');
+
+expect(progress._total).toBe(10);
+expect(progress._completed).toBe(3);
+expect(progress._messages).toContain('step message');
+```
+
+### Mock logger
+
+`ctx.log` captures all log calls for inspection:
+
+```ts
+const ctx = createMockContext();
+const log = ctx.log as ContextLogger & {
+  calls: Array<{ level: string; msg: string; data?: unknown }>;
+};
+
+await myTool.handler(input, ctx);
+expect(log.calls.some(c => c.level === 'info' && c.msg.includes('Processing'))).toBe(true);
+```
+
+---
+
+## Full test example
+
+```ts
+// src/mcp-server/tools/definitions/my-tool.tool.test.ts
+import { describe, expect, it, vi } from 'vitest';
+import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+import { McpError } from '@cyanheads/mcp-ts-core/errors';
+import { myTool } from '@/mcp-server/tools/definitions/my-tool.tool.js';
+
+describe('myTool', () => {
+  it('returns expected output', async () => {
+    const ctx = createMockContext();
+    const input = myTool.input.parse({ query: 'hello' });
+    const result = await myTool.handler(input, ctx);
+    expect(result.result).toBe('Found: hello');
+  });
+
+  it('throws McpError on invalid state', async () => {
+    const ctx = createMockContext();
+    const input = myTool.input.parse({ query: 'TRIGGER_ERROR' });
+    await expect(myTool.handler(input, ctx)).rejects.toThrow(McpError);
+  });
+
+  it('formats response correctly', () => {
+    const result = { result: 'test' };
+    const blocks = myTool.format!(result);
+    expect(blocks[0].type).toBe('text');
+  });
+});
+```
+
+Key points:
+
+- Parse input through `myTool.input.parse(...)` — validates against the Zod schema and produces the typed input the handler expects.
+- Call `myTool.handler(input, ctx)` directly — not through the MCP SDK or any framework wrapper.
+- Assert on the return value for happy paths; use `.rejects.toThrow(McpError)` for error paths.
+- Test `format` separately if the tool defines one — it is a pure function and needs no `ctx`.
+
+---
+
+## Testing with optional capabilities
+
+```ts
+it('uses elicitation when available', async () => {
+  const elicit = vi.fn().mockResolvedValue({
+    action: 'accept',
+    data: { format: 'json' },
+  });
+  const ctx = createMockContext({ elicit });
+  const input = myTool.input.parse({ query: 'hello' });
+  await myTool.handler(input, ctx);
+  expect(elicit).toHaveBeenCalledOnce();
+});
+
+it('uses sampling when available', async () => {
+  const sample = vi.fn().mockResolvedValue({
+    role: 'assistant',
+    content: { type: 'text', text: 'Summary text' },
+  });
+  const ctx = createMockContext({ sample });
+  const input = myTool.input.parse({ query: 'summarize this' });
+  const result = await myTool.handler(input, ctx);
+  expect(result.summary).toBeDefined();
+});
+
+it('handles missing elicitation gracefully', async () => {
+  // ctx.elicit is undefined — handler must check before calling
+  const ctx = createMockContext();
+  const input = myTool.input.parse({ query: 'hello' });
+  // Should not throw even when ctx.elicit is absent
+  await expect(myTool.handler(input, ctx)).resolves.toBeDefined();
+});
+```
+
+---
+
+## Vitest config
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+export default defineConfig({
+  plugins: [tsconfigPaths()],
+  ssr: {
+    noExternal: ['zod'],
+  },
+  test: {
+    globals: true,
+    environment: 'node',
+    setupFiles: ['./tests/setup.ts'],
+    exclude: ['tests/integration/**', 'node_modules/**'],
+    pool: 'forks',
+    maxWorkers: 4,
+    isolate: true,
+    coverage: {
+      provider: 'istanbul',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.d.ts'],
+      thresholds: {
+        lines: 80,
+        functions: 75,
+        branches: 70,
+        statements: 80,
+      },
+    },
+  },
+});
+```
+
+Key points:
+- `tsconfigPaths()` resolves the `@/` path alias from `tsconfig.json` — no manual `resolve.alias` needed.
+- `ssr: { noExternal: ['zod'] }` fixes Vite SSR transform issues with Zod 4.
+- Integration tests (in `tests/integration/`) are excluded from the default run; they have their own config.
+- `pool: 'forks'` with `isolate: true` prevents mock pollution between test files.
+- `setupFiles` points to `tests/setup.ts` for any global test setup (e.g., env vars).
+
+---
+
+## Test isolation
+
+**Construct dependencies fresh in `beforeEach`.** Never share mutable state across tests.
+
+```ts
+import { beforeEach, describe, expect, it } from 'vitest';
+import { initMyService } from '@/services/my-domain/my-service.js';
+
+describe('myTool with service', () => {
+  beforeEach(() => {
+    // Re-initialize with a fresh instance before each test
+    initMyService(mockConfig, mockStorage);
+  });
+
+  it('calls service correctly', async () => {
+    const ctx = createMockContext({ tenantId: 'test-tenant' });
+    // ...
+  });
+});
+```
+
+- Re-init services with `initMyService()` (or equivalent) per test suite — the module-level singleton must be reset so tests don't share state.
+- Vitest runs test files in separate worker threads — parallel file execution is safe by default.
+- Use `createMockContext({ tenantId })` whenever the handler accesses `ctx.state` — omitting `tenantId` causes `ctx.state` to throw.
+
+---
+
+## McpError assertions
+
+```ts
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+it('throws NotFound for missing resource', async () => {
+  const ctx = createMockContext();
+  const input = myTool.input.parse({ id: 'nonexistent' });
+  await expect(myTool.handler(input, ctx)).rejects.toMatchObject({
+    code: JsonRpcErrorCode.NotFound,
+  });
+});
+```
+
+Use `.rejects.toThrow(McpError)` to assert type only. Use `.rejects.toMatchObject({ code: ... })` when the specific error code matters.

package/skills/api-utils/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: api-utils
+description: >
+  API reference for all `@cyanheads/mcp-ts-core/utils/*` subpath exports. Use when looking up utility method signatures, options, peer dependencies, or usage patterns.
+metadata:
+  author: cyanheads
+  version: "2.0"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+Utility subpath exports from `@cyanheads/mcp-ts-core/utils/*`. Complex utilities with rich APIs have dedicated reference files; simpler utilities are documented inline below.
+
+**Tier 3** = optional peer dependency. Install as needed (e.g., `bun add js-yaml`). All Tier 3 methods are **async** (lazy-load deps on first call).
+
+## References
+
+| Reference | Path | Subpath | Covers |
+|:----------|:-----|:--------|:-------|
+| Formatting | `references/formatting.md` | `utils/formatting` | `markdown()`, `MarkdownBuilder`, `diffFormatter`, `tableFormatter`, `treeFormatter` — builder patterns, option types, style variants, usage examples |
+| Parsing | `references/parsing.md` | `utils/parsing` | `yamlParser`, `xmlParser`, `csvParser`, `jsonParser`, `pdfParser`, `dateParser`, `frontmatterParser` — method signatures, option types, peer deps, `Allow` flags, PDF workflows |
+| Security | `references/security.md` | `utils/security` | `sanitization`, `RateLimiter`, `IdGenerator` — config types, method details, sensitive fields, usage examples |
+
+---
+
+## `@cyanheads/mcp-ts-core/utils/network`
+
+| Export | API | Notes |
+|:-------|:----|:------|
+| `fetchWithTimeout` | `(url, timeoutMs, context: RequestContext, options?: FetchWithTimeoutOptions) -> Promise<Response>` | Wraps `fetch` with `AbortController` timeout. `FetchWithTimeoutOptions` extends `RequestInit` (minus `signal`) and adds `rejectPrivateIPs?: boolean` and `signal?: AbortSignal` (external cancellation). SSRF protection: blocks RFC 1918, loopback, link-local, CGNAT, cloud metadata. DNS validation on Node; hostname-only on Workers. Manual redirect following (max 5) with per-hop SSRF check. |
+
+---
+
+## `@cyanheads/mcp-ts-core/utils/pagination`
+
+| Export | API | Notes |
+|:-------|:----|:------|
+| `extractCursor` | `(params?) -> string \| undefined` | Extracts opaque cursor string from MCP request params. Checks `params.cursor` then `params._meta.cursor`. Returns `undefined` when no cursor is present. Does not decode. |
+| `paginateArray` | `<T>(items, cursorStr, defaultPageSize, maxPageSize, context: RequestContext) -> PaginatedResult<T>` | Decodes cursor, slices array, returns `{ items, nextCursor?, totalCount }`. `nextCursor` omitted on last page. Throws `McpError(InvalidParams)` on invalid cursor. |
+| `encodeCursor` | `(state: PaginationState) -> string` | Encodes `{ offset, limit, ...extra }` to opaque base64url string. |
+| `decodeCursor` | `(cursor, context: RequestContext) -> PaginationState` | Decodes opaque base64url cursor. Throws `McpError(InvalidParams)` if malformed. |
+
+---
+
+## `@cyanheads/mcp-ts-core/utils/runtime`
+
+| Export | API | Notes |
+|:-------|:----|:------|
+| `runtimeCaps` | `RuntimeCapabilities` object | Snapshot at import time. Fields: `isNode`, `isBun`, `isWorkerLike`, `isBrowserLike`, `hasProcess`, `hasBuffer`, `hasTextEncoder`, `hasPerformanceNow`. All booleans, never throw. |
+
+---
+
+## `@cyanheads/mcp-ts-core/utils/scheduling`
+
+| Export | API | Notes |
+|:-------|:----|:------|
+| `schedulerService` | `.schedule(id, schedule, taskFunction, description) -> Promise<Job>` `.start(id) -> void` `.stop(id) -> void` `.remove(id) -> void` `.listJobs() -> Job[]` | **Async** `schedule()` — Tier 3 peer: `node-cron`. **Node-only** (throws `ConfigurationError` in Workers). Jobs start in stopped state; call `start(id)` to activate. Skips overlapping executions. Each tick gets fresh `RequestContext`. `Job: { id, schedule, description, isRunning, task }`. `taskFunction: (context: RequestContext) => void | Promise<void>`. |
+
+---
+
+## `@cyanheads/mcp-ts-core/utils/types`
+
+The `utils/types` subpath exports only two guards. The full set of guards lives in the internal module and is not part of the public API.
+
+| Export | Signature | Notes |
+|:-------|:----------|:------|
+| `isErrorWithCode` | `(error: unknown) -> error is Error & { code: unknown }` | Type guard — `true` when value is an `Error` instance with a `code` property |
+| `isRecord` | `(value: unknown) -> value is Record<string, unknown>` | Type guard for plain objects (non-null, non-array) |
+
+---
+
+## `@cyanheads/mcp-ts-core/utils/logger`
+
+| Export | API | Notes |
+|:-------|:----|:------|
+| `logger` | Pino instance. `.debug()` `.info()` `.notice()` `.warning()` `.error()` `.fatal()` | Global structured logger. Use `ctx.log` in handlers instead. `logger` is for lifecycle/background contexts (startup, shutdown, `setup()`). Auto-redacts sensitive fields. |
+
+---
+
+## `@cyanheads/mcp-ts-core/utils/requestContext`
+
+| Export | API | Notes |
+|:-------|:----|:------|
+| `requestContextService` | `.createRequestContext(opts?) -> RequestContext` `.createFromHeaders(headers, fallback?) -> RequestContext` | Creates tracing context with `requestId`, `timestamp`, `traceId`, `spanId`, `tenantId`, `auth`. Internal — most consumers use `ctx` from handlers. |
+| `RequestContext` | Type: `{ requestId, timestamp, operation?, traceId?, spanId?, tenantId?, auth? }` | Request tracing metadata. |
+
+---
+
+## `@cyanheads/mcp-ts-core/utils/errorHandler`
+
+| Export | API | Notes |
+|:-------|:----|:------|
+| `ErrorHandler` | `.tryCatch<T>(fn, opts) -> Promise<T>` `.handleError(error, opts) -> Error` `.determineErrorCode(error) -> JsonRpcErrorCode` `.mapError(error, mappings, defaultFactory?) -> T \| Error` `.formatError(error) -> Record<string, unknown>` | Service-level error handling. `tryCatch` wraps async or sync `fn`, logs via `handleError`, and always rethrows. No `.tryCatchSync()`. Use in services, NOT in tool handlers (those throw raw `McpError`). Options: `operation`, `context`, `errorCode`, `input`, `rethrow`, `includeStack`, `critical`, `errorMapper`. |
+
+---
+
+## `@cyanheads/mcp-ts-core/utils/telemetry`
+
+| Export | Subpath | API | Notes |
+|:-------|:--------|:----|:------|
+| `initInstrumentation` | `telemetry/instrumentation` | `(config) -> void` | Initializes OpenTelemetry SDK with OTLP exporter. Call once at startup. |
+| `metrics` | `telemetry/metrics` | `.recordToolExecution(name, duration, success)` `.recordResourceAccess(uri, duration)` `.getMetrics()` | In-process metrics collection with OTEL integration. |
+| `trace` | `telemetry/trace` | `.startSpan(name, opts?)` `.runInSpan(name, fn)` `.runInContext(fn)` | Tracing helpers wrapping OTEL `@opentelemetry/api`. |
+| `SEMCONV_*` | `telemetry/semconv` | 38 semantic convention constants | Attribute keys following OpenTelemetry semantic conventions. |

package/skills/api-utils/references/formatting.md

@@ -0,0 +1,237 @@
+# Formatting Utilities (`utils/formatting`)
+
+```ts
+import { markdown, MarkdownBuilder, diffFormatter, tableFormatter, treeFormatter } from '@cyanheads/mcp-ts-core/utils/formatting';
+```
+
+---
+
+## `markdown()` / `MarkdownBuilder`
+
+`markdown()` is a factory shorthand for `new MarkdownBuilder()`. Fluent builder — all methods return `this` except `build()`.
+
+### Methods
+
+| Method | Signature | Notes |
+|:-------|:----------|:------|
+| `h1` | `(text, emoji?) -> this` | `# [emoji ]text` |
+| `h2` | `(text, emoji?) -> this` | `## [emoji ]text` |
+| `h3` | `(text, emoji?) -> this` | `### [emoji ]text` |
+| `h4` | `(text, emoji?) -> this` | `#### [emoji ]text` |
+| `keyValue` | `(key, value) -> this` | `**key:** value` |
+| `keyValuePlain` | `(key, value) -> this` | `key: value` (no bold) |
+| `list` | `(items, ordered?) -> this` | `ordered` defaults to `false`; empty arrays silently ignored |
+| `codeBlock` | `(content, language?) -> this` | Fenced block; `language` defaults to `''` |
+| `inlineCode` | `(code) -> this` | Backtick-wrapped; no trailing newline |
+| `paragraph` | `(text) -> this` | Text + `\n\n` |
+| `blockquote` | `(text) -> this` | Each line prefixed with `> ` |
+| `hr` | `() -> this` | `---` |
+| `link` | `(text, url) -> this` | `[text](url)`; no trailing newline |
+| `table` | `(headers, rows) -> this` | GFM table; no-ops if headers or rows empty |
+| `section` | `(title, content) -> this` | H2 heading + callback |
+| `section` | `(title, level, content) -> this` | Heading at level 2/3/4 + callback |
+| `details` | `(summary, details) -> this` | HTML `<details>`/`<summary>` collapsible block |
+| `alert` | `(type, content) -> this` | GFM `[!TYPE]` alert blockquote |
+| `taskList` | `(items) -> this` | GFM checkbox list; `items: Array<{ checked: boolean; text: string }>` |
+| `image` | `(altText, url, title?) -> this` | `![alt](url "title")` |
+| `strikethrough` | `(text) -> this` | `~~text~~`; no trailing newline |
+| `diff` | `(changes) -> this` | ` ```diff ` block; `changes: { additions?: string[]; deletions?: string[]; context?: string[] }` |
+| `badge` | `(label, message, color?) -> this` | shields.io badge image; `color` defaults to `'blue'` |
+| `bold` | `(text) -> this` | `**text**`; no trailing newline |
+| `italic` | `(text) -> this` | `*text*`; no trailing newline |
+| `boldItalic` | `(text) -> this` | `***text***`; no trailing newline |
+| `raw` | `(markdown) -> this` | Appends verbatim |
+| `blankLine` | `() -> this` | Single `\n` |
+| `text` | `(text) -> this` | Plain text, no formatting, no implicit newlines |
+| `when` | `(condition, content) -> this` | Conditional append; `content: () => void` |
+| `reset` | `() -> this` | Clears buffer |
+| `build` | `() -> string` | Returns trimmed joined buffer; does NOT reset |
+
+### Usage
+
+```ts
+const md = markdown()
+  .h1('Report', '📊')
+  .paragraph('Generated automatically.')
+  .section('Results', 3, () => {
+    md.table(['Name', 'Score'], [['Alice', '95'], ['Bob', '87']]);
+  })
+  .when(hasWarnings, () => {
+    md.alert('warning', 'Some items need attention.');
+  })
+  .build();
+```
+
+Inline methods (`bold`, `italic`, `inlineCode`, `link`, `strikethrough`) do not append newlines — combine them with `text()` or `paragraph()` for inline composition.
+
+---
+
+## `diffFormatter`
+
+**Tier 3 peer:** `diff` (`bun add diff`). All methods are **async**.
+
+### Types
+
+```ts
+type DiffFormat = 'unified' | 'patch' | 'inline';
+
+interface DiffFormatterOptions {
+  context?: number;           // unchanged lines around changes; default 3
+  format?: DiffFormat;        // default 'unified'
+  includeHeaders?: boolean;   // ---/+++ headers (patch only); default true
+  oldPath?: string;           // file path for old version (headers)
+  newPath?: string;           // file path for new version (headers)
+  showLineNumbers?: boolean;  // default true
+}
+```
+
+### Methods
+
+| Method | Signature | Returns |
+|:-------|:----------|:--------|
+| `diff` | `(oldText, newText, options?, context?) -> Promise<string>` | Formatted diff string |
+| `diffLines` | `(oldLines, newLines, options?, context?) -> Promise<string>` | Same as `diff` but accepts pre-split `string[]` arrays |
+| `diffWords` | `(oldText, newText, context?) -> Promise<string>` | Word-level inline diff: `[+added+]` / `[-removed-]` |
+| `getStats` | `(oldText, newText, context?) -> Promise<{ additions, deletions, changes }>` | Line-count stats; `changes = additions + deletions` |
+
+### Format behavior
+
+| Format | Output |
+|:-------|:-------|
+| `'unified'` | Hunk headers (`@@`) only — strips `---`/`+++` file headers. Default. |
+| `'patch'` | Full patch with file headers. `includeHeaders: false` strips them. |
+| `'inline'` | No headers or hunk markers. Additions as `[+text+]`, removals as `[-text-]`. |
+
+### Usage
+
+```ts
+const diff = await diffFormatter.diff(oldCode, newCode, {
+  format: 'unified',
+  context: 5,
+  showLineNumbers: true,
+});
+
+const stats = await diffFormatter.getStats(oldCode, newCode);
+// { additions: 12, deletions: 3, changes: 15 }
+```
+
+---
+
+## `tableFormatter`
+
+Synchronous — no peer dependency.
+
+### Types
+
+```ts
+type TableStyle = 'markdown' | 'ascii' | 'grid' | 'compact';
+type Alignment = 'left' | 'center' | 'right';
+
+interface TableFormatterOptions {
+  style?: TableStyle;                    // default 'markdown'
+  alignment?: Record<string, Alignment>; // key = column name or numeric index string
+  maxWidth?: number;                     // truncates at this width; default 50
+  minWidth?: number;                     // default 3
+  truncate?: boolean;                    // truncate with '...' when exceeding maxWidth; default true
+  headerStyle?: 'bold' | 'uppercase' | 'none';
+  padding?: number;                      // spaces around cell content; default 1
+}
+```
+
+### Methods
+
+| Method | Signature | Notes |
+|:-------|:----------|:------|
+| `format` | `<T extends Record<string, unknown>>(data, options?, context?) -> string` | Extracts headers from first object's keys; stringifies values. Returns `''` if empty. |
+| `formatRaw` | `(headers, rows, options?, context?) -> string` | Pre-serialized `string[][]`; every row must match `headers.length`. Returns `''` if empty. |
+
+### Styles
+
+| Style | Description |
+|:------|:------------|
+| `markdown` | GFM pipes with alignment indicators in separator row |
+| `ascii` | `+`/`-`/`|` box drawing |
+| `grid` | Unicode box drawing (`┌─┬─┐` / `│` / `├─┼─┤` / `└─┴─┘`) |
+| `compact` | Space-separated, no borders |
+
+### Usage
+
+```ts
+// From objects — headers auto-extracted from keys
+const table = tableFormatter.format(
+  [{ name: 'Alice', score: 95 }, { name: 'Bob', score: 87 }],
+  { style: 'grid', alignment: { score: 'right' } },
+);
+
+// From raw arrays
+const raw = tableFormatter.formatRaw(
+  ['Name', 'Score'],
+  [['Alice', '95'], ['Bob', '87']],
+  { style: 'markdown', headerStyle: 'bold' },
+);
+```
+
+---
+
+## `treeFormatter`
+
+Synchronous — no peer dependency.
+
+### Types
+
+```ts
+type TreeStyle = 'unicode' | 'ascii' | 'compact';
+
+interface TreeNode {
+  name: string;                           // required, must be non-empty
+  children?: TreeNode[];                  // presence determines folder vs leaf icon
+  metadata?: Record<string, unknown>;     // rendered as key=value when showMetadata enabled
+}
+
+interface TreeFormatterOptions {
+  style?: TreeStyle;        // default 'unicode'
+  maxDepth?: number;        // 0-based cutoff; undefined = no limit
+  showMetadata?: boolean;   // append metadata after node name; default false
+  icons?: boolean;          // prefix nodes with icons; default false
+  indent?: string;          // per-level indent; default '  ' (two spaces)
+  folderIcon?: string;      // icon for branch nodes; default folder emoji
+  fileIcon?: string;        // icon for leaf nodes; default page emoji
+}
+```
+
+### Methods
+
+| Method | Signature | Notes |
+|:-------|:----------|:------|
+| `format` | `(root, options?, context?) -> string` | Single tree. Detects and marks circular references as `[Circular Reference]`. |
+| `formatMultiple` | `(roots, options?, context?) -> string` | Forest of trees joined by `\n\n`. `roots` must be non-empty. |
+
+### Styles
+
+| Style | Connectors |
+|:------|:-----------|
+| `unicode` | `├──` / `└──` / `│` |
+| `ascii` | `+--` / `\--` / `|` |
+| `compact` | Indented list, no connectors |
+
+### Usage
+
+```ts
+const tree: TreeNode = {
+  name: 'src',
+  children: [
+    { name: 'index.ts' },
+    {
+      name: 'utils',
+      children: [{ name: 'helpers.ts', metadata: { lines: 42 } }],
+    },
+  ],
+};
+
+const output = treeFormatter.format(tree, {
+  style: 'unicode',
+  icons: true,
+  showMetadata: true,
+  maxDepth: 3,
+});
+```