gazetta 0.6.0 → 0.8.0

package/dist/ai/refusal.js

@@ -0,0 +1,100 @@
+/**
+ * Refusal detection for AI provider responses.
+ *
+ * # Why this lives in `ai/` and not `alt/`
+ *
+ * Provider safety refusals look the same regardless of task. Whether
+ * the model is asked to describe an image (alt-text) or translate a
+ * paragraph (future), a refusal arrives as a 200 OK with text like
+ * "I can't help with that" in the response body — structurally
+ * indistinguishable from a successful response without inspection.
+ *
+ * v1.5's only consumer is `alt/`, but refusal detection is conceptually
+ * cross-task. Right structure now beats right structure later, per
+ * [team-preferences rule 18]: "extract shared code when you first see
+ * the split concern". Translation as the documented next consumer
+ * (per [design-ai-implementation.md]) makes this a known split.
+ *
+ * # Marker maintenance
+ *
+ * The marker list below MUST stay current as providers tune their
+ * safety messaging. Plan: review at every major model version bump
+ * (e.g., when an adapter's `defaultModel` jumps a major). Provider-
+ * specific phrases live in the adapter (passed via `adapterMarkers`)
+ * so generic markers and provider-specific ones can evolve
+ * independently.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "raw text → structured refusal info"
+ *   - OCP: per-adapter markers extend without touching the shared list
+ *   - DIP: callers depend on `detectRefusal`, not on substring inspection
+ *     scattered across the codebase
+ */
+/**
+ * Cross-provider refusal phrases. Lowercase substrings — the matcher
+ * lowercases both sides, so casing in the upstream response doesn't
+ * matter. Order is irrelevant; `Array.some` is fine at this size.
+ *
+ * Each entry corresponds to a phrase observed across at least two
+ * providers' refusal outputs. Provider-specific phrasing belongs in
+ * the adapter, passed via `adapterMarkers`.
+ */
+const SHARED_REFUSAL_MARKERS = [
+    "i can't describe",
+    'i cannot describe',
+    "i'm not able to describe",
+    'i am not able to describe',
+    "i'm unable to describe",
+    'i am unable to describe',
+    "i can't provide",
+    'i cannot provide',
+    "i'm unable to provide",
+    'i am unable to provide',
+    "i can't help",
+    'i cannot help',
+    "i'm not able to help",
+    "i'm sorry, but",
+];
+/**
+ * Minimum useful response length. Below this, even a non-refusal
+ * response is too short to be a real description — treat as a refusal
+ * with a generic reason. Calibrated for the alt-text use case where
+ * five chars is below "Cat." (4) but above "Hi" (2); empty responses
+ * also fall through here.
+ *
+ * If a future task has different length expectations (e.g., a single-
+ * word tag), the consumer should normalize the response before passing
+ * it to `detectRefusal`, OR the threshold becomes a parameter. Don't
+ * generalize speculatively — wait for the second task to force the
+ * shape.
+ */
+const MIN_USEFUL_LENGTH = 5;
+/**
+ * Detect whether `text` is a refusal. Caller passes adapter-specific
+ * markers (e.g., Anthropic's particular phrasing) on top of the shared
+ * list.
+ *
+ * Returns `{ refused: false, reason: null }` for descriptive responses;
+ * `{ refused: true, reason: <truncated text> }` otherwise. Reason is
+ * truncated to 200 chars so logs and UI toasts don't render arbitrarily
+ * long refusal blocks.
+ */
+export function detectRefusal(text, adapterMarkers = []) {
+    const lower = text.toLowerCase();
+    for (const marker of SHARED_REFUSAL_MARKERS) {
+        if (lower.includes(marker)) {
+            return { refused: true, reason: text.slice(0, 200) };
+        }
+    }
+    for (const marker of adapterMarkers) {
+        if (lower.includes(marker.toLowerCase())) {
+            return { refused: true, reason: text.slice(0, 200) };
+        }
+    }
+    if (text.trim().length < MIN_USEFUL_LENGTH) {
+        return { refused: true, reason: 'Empty or unusably short response' };
+    }
+    return { refused: false, reason: null };
+}
+//# sourceMappingURL=refusal.js.map

package/dist/ai/refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../src/ai/refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;;;GAQG;AACH,MAAM,sBAAsB,GAAsB;IAChD,kBAAkB;IAClB,mBAAmB;IACnB,0BAA0B;IAC1B,2BAA2B;IAC3B,wBAAwB;IACxB,yBAAyB;IACzB,iBAAiB;IACjB,kBAAkB;IAClB,uBAAuB;IACvB,wBAAwB;IACxB,cAAc;IACd,eAAe;IACf,sBAAsB;IACtB,gBAAgB;CACjB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,iBAAiB,GAAG,CAAC,CAAA;AAQ3B;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,iBAAoC,EAAE;IAChF,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;IAChC,KAAK,MAAM,MAAM,IAAI,sBAAsB,EAAE,CAAC;QAC5C,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;QACtD,CAAC;IACH,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;QACpC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;QACtD,CAAC;IACH,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QAC3C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAA;IACtE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;AACzC,CAAC"}

package/dist/ai/vision-prep.d.ts

@@ -0,0 +1,32 @@
+/** Default long-edge cap. Per-call override available via `maxEdge`. */
+export declare const MAX_EDGE = 768;
+export interface PrepareInput {
+    /** Source bytes (raw asset bytes, post-preprocess). */
+    bytes: Uint8Array;
+    /** Source MIME type from the asset manifest. */
+    mime: string;
+    /**
+     * For animated images, the analyzer's extracted first-frame poster
+     * bytes (always PNG). When provided, used directly — no further
+     * rasterization. Skip for static images.
+     */
+    posterBytes?: Uint8Array;
+    /** Long-edge cap override; defaults to {@link MAX_EDGE}. */
+    maxEdge?: number;
+}
+export interface PreparedImage {
+    /** Bytes ready to send to a vision provider. */
+    bytes: Uint8Array;
+    /** MIME of the prepared bytes — `image/jpeg` or `image/png`. */
+    mime: string;
+}
+/**
+ * Prepare image bytes for a vision-call. Single async call that picks
+ * the right code path based on input.
+ *
+ * Throws on hard failures (corrupt source bytes that sharp can't
+ * decode, even past metadata). Callers wrap in their adapter's error
+ * taxonomy.
+ */
+export declare function prepareForVision(input: PrepareInput): Promise<PreparedImage>;
+//# sourceMappingURL=vision-prep.d.ts.map

package/dist/ai/vision-prep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-prep.d.ts","sourceRoot":"","sources":["../../src/ai/vision-prep.ts"],"names":[],"mappings":"AA2DA,wEAAwE;AACxE,eAAO,MAAM,QAAQ,MAAM,CAAA;AAE3B,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,KAAK,EAAE,UAAU,CAAA;IACjB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,CAAA;IACxB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,KAAK,EAAE,UAAU,CAAA;IACjB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;CACb;AAWD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAuClF"}

package/dist/ai/vision-prep.js

@@ -0,0 +1,113 @@
+/**
+ * Image preprocessing for vision-using AI tasks.
+ *
+ * # Single responsibility
+ *
+ * Take raw asset bytes; return bytes suitable for sending to a vision
+ * provider. Concretely:
+ *
+ *   - Resize to `MAX_EDGE` long-edge (default 768) preserving aspect ratio
+ *   - Re-encode to JPEG (or PNG if alpha) post-resize
+ *   - Rasterize SVG to PNG at MAX_EDGE
+ *   - Pass through if already small (no needless re-encode)
+ *   - Use the analyzer-extracted poster bytes for animated images
+ *
+ * No knowledge of providers, prompts, refusal, or task-specific config.
+ *
+ * # Why 768
+ *
+ * Smallest size that fits all v1.5 providers natively without quality
+ * loss:
+ *
+ *   - Ollama llama3.2-vision native input is 1120×1120
+ *   - Anthropic Claude (non-Opus) recommended max long edge is 1568
+ *   - OpenAI gpt-4o "high detail" mode targets 768 as the short-edge
+ *     value when tiling 512×512 — chosen by OpenAI as the size where
+ *     in-image text remains legible
+ *
+ * 768 sits below all three ceilings, makes OpenAI tile to exactly
+ * 4 tiles + base = 765 tokens, and produces predictable cost on
+ * Anthropic (~786 tokens for a 768×768 image, well under the 1568
+ * token ceiling).
+ *
+ * Going lower (e.g., 512) hits OpenAI's "low detail" tier which the
+ * provider's own docs mark as worse for in-image text. Going higher
+ * exceeds Ollama's native input so the model downsamples internally
+ * — we'd be paying upload bandwidth for bytes that get discarded.
+ *
+ * # Per-task override
+ *
+ * Vision tasks that need different sizing (e.g., a future tag-suggestion
+ * task on detailed product shots wanting 1024) pass `maxEdge` per call.
+ * `MAX_EDGE` is the default; `prepareForVision` accepts an override.
+ *
+ * # Animated images
+ *
+ * The animated-image analyzer (shipped in media v1) extracts a
+ * first-frame PNG poster as a supplementary file. Suggester callers
+ * pass those bytes via `posterBytes` — `prepareForVision` skips its
+ * own rasterization and uses the poster directly. Cross-feature reuse
+ * over duplication.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "raw asset bytes → vision-call bytes"
+ *   - OCP: a future `pdf-prep.ts` peer handles document tasks the same way
+ *   - DIP: callers depend on `prepareForVision`, not on sharp directly
+ */
+import sharp from 'sharp';
+/** Default long-edge cap. Per-call override available via `maxEdge`. */
+export const MAX_EDGE = 768;
+/**
+ * SVG rasterization density. 144 dpi is a sensible doubled-72-dpi
+ * default that produces ~2x the nominal SVG dimensions. Combined with
+ * the resize step, the final output is bounded by `maxEdge` regardless
+ * of the SVG's intrinsic size — density only affects rendering quality
+ * before the cap kicks in.
+ */
+const SVG_DENSITY = 144;
+/**
+ * Prepare image bytes for a vision-call. Single async call that picks
+ * the right code path based on input.
+ *
+ * Throws on hard failures (corrupt source bytes that sharp can't
+ * decode, even past metadata). Callers wrap in their adapter's error
+ * taxonomy.
+ */
+export async function prepareForVision(input) {
+    const maxEdge = input.maxEdge ?? MAX_EDGE;
+    // Animated source: use the pre-extracted poster bytes (always PNG).
+    // Posters are extracted at upload time and already represent the
+    // first frame; for vision-call purposes that's what we want.
+    if (input.posterBytes) {
+        return { bytes: input.posterBytes, mime: 'image/png' };
+    }
+    // SVG: rasterize to PNG at the cap. Vector input has no intrinsic
+    // pixel size; we pick density × resize to bound the output.
+    if (input.mime === 'image/svg+xml') {
+        const buf = await sharp(input.bytes, { density: SVG_DENSITY })
+            .resize({ width: maxEdge, height: maxEdge, fit: 'inside' })
+            .png()
+            .toBuffer();
+        return { bytes: new Uint8Array(buf), mime: 'image/png' };
+    }
+    // Raster: resize if larger than maxEdge on long edge; otherwise pass
+    // through. Avoids a no-op JPEG-of-JPEG re-encode that would lose
+    // quality without saving bandwidth.
+    const meta = await sharp(input.bytes).metadata();
+    const longEdge = Math.max(meta.width ?? 0, meta.height ?? 0);
+    if (longEdge > 0 && longEdge <= maxEdge) {
+        return { bytes: input.bytes, mime: input.mime };
+    }
+    // Preserve PNG when source has alpha (logos with transparency lose
+    // semantically when flattened to JPEG). Otherwise JPEG quality 85 —
+    // sharp's default for `.jpeg()`, well-balanced for AI input.
+    const hasAlpha = meta.hasAlpha === true;
+    const pipeline = sharp(input.bytes).resize({ width: maxEdge, height: maxEdge, fit: 'inside' });
+    const buf = hasAlpha ? await pipeline.png().toBuffer() : await pipeline.jpeg({ quality: 85 }).toBuffer();
+    return {
+        bytes: new Uint8Array(buf),
+        mime: hasAlpha ? 'image/png' : 'image/jpeg',
+    };
+}
+//# sourceMappingURL=vision-prep.js.map

package/dist/ai/vision-prep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-prep.js","sourceRoot":"","sources":["../../src/ai/vision-prep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,wEAAwE;AACxE,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAA;AAwB3B;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,GAAG,CAAA;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAmB;IACxD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,QAAQ,CAAA;IAEzC,oEAAoE;IACpE,iEAAiE;IACjE,6DAA6D;IAC7D,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,CAAA;IACxD,CAAC;IAED,kEAAkE;IAClE,4DAA4D;IAC5D,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;aAC3D,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;aAC1D,GAAG,EAAE;aACL,QAAQ,EAAE,CAAA;QACb,OAAO,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAA;IAC1D,CAAC;IAED,qEAAqE;IACrE,iEAAiE;IACjE,oCAAoC;IACpC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAA;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAA;IAC5D,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,IAAI,OAAO,EAAE,CAAC;QACxC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAA;IACjD,CAAC;IAED,mEAAmE;IACnE,oEAAoE;IACpE,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAA;IACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAA;IAC9F,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAA;IACxG,OAAO;QACL,KAAK,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC;QAC1B,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY;KAC5C,CAAA;AACH,CAAC"}

package/dist/alt/adapter.d.ts

@@ -0,0 +1,140 @@
+/**
+ * `AltTextAdapter` — provider-substitutable interface for generating
+ * alt text from image bytes.
+ *
+ * Three concrete implementations ship in v1.5: `anthropicAltAdapter`,
+ * `openAIAltAdapter`, `ollamaAltAdapter` (commits 3-5). One safe
+ * default also ships: `nullAltAdapter` (this commit), used when no
+ * adapter is configured for the target.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the alt-text task contracts (request,
+ *     suggestion, adapter interface). Nothing else lives here.
+ *   - OCP: new providers implement the interface and slot into the
+ *     factory (commit 6). No existing module changes.
+ *   - LSP: every adapter — including `nullAltAdapter` — honors the
+ *     same contract. Substitutable in tests.
+ *   - ISP: adapter exposes only `name`, `supports`, `generate` — no
+ *     UI concerns, no config concerns.
+ *   - DIP: callers depend on this interface, not on Anthropic SDK,
+ *     OpenAI SDK, or Ollama HTTP details.
+ *
+ * # Why `AltSuggestion` carries refused state
+ *
+ * Vision providers can return a 200 OK with refusal text in the
+ * content field (e.g., "I can't describe this image"). The structural
+ * cut: refusal is a *successful API call with a domain-level no*.
+ * Treating refusal as a structured field — not as inspecting `text`
+ * for substrings in every consumer — keeps DIP. UI consumers branch
+ * on `refused`, not on text patterns.
+ *
+ * Considered and rejected: a `confidence: number | null` field.
+ * Vision providers don't expose calibrated confidence for free-form
+ * description tasks; a hardcoded null would be a stub-on-the-interface
+ * (LSP violation, per [team-preferences rule 18]). If a future
+ * provider exposes real calibrated confidence, it lands as a separate
+ * field — not as a retrofit of a placeholder.
+ */
+import type { PromptPolicy } from '../ai/compose-prompt.js';
+/**
+ * What the caller wants. Provider-agnostic. Each field has a documented
+ * default applied by the factory when callers don't specify.
+ */
+export interface AltRequest {
+    /**
+     * Target language for the description (BCP 47 locale code; 'en',
+     * 'fr', 'pt-BR'). The model writes alt directly in this language —
+     * no separate translation pass. Default 'en'.
+     */
+    locale: string;
+    /**
+     * Soft length suggestion in characters. Used in prompt guidance
+     * ("Maximum N characters") and as native `max_tokens` derivation
+     * for adapters that have it. Default 125 (WAI-ARIA convention).
+     *
+     * NOT enforced by the suggester or adapter — if the model returns
+     * longer text, the consumer sees the full string and can edit. Hard
+     * truncation would lose meaning.
+     */
+    maxChars: number;
+    /**
+     * Output style. Closed enum; extended additively (future:
+     * `'marketing' | 'technical'`).
+     */
+    style: AltStyle;
+}
+/** Closed enum; extends additively. */
+export type AltStyle = 'descriptive';
+/** Default `AltRequest` values, applied by the suggester when callers omit fields. */
+export declare const DEFAULT_ALT_REQUEST: AltRequest;
+/**
+ * What the suggester delivers. `text` is the model's output (which may
+ * be a refusal). `refused` is the structured signal: when true, don't
+ * auto-fill, surface `refusalReason` to the author instead.
+ */
+export interface AltSuggestion {
+    text: string;
+    /** True when the model declined or couldn't describe the image. */
+    refused: boolean;
+    /** Truncated reason text when refused; null otherwise. */
+    refusalReason: string | null;
+}
+/**
+ * Input to an adapter's `generate` call. The suggester does prep:
+ *
+ *   - Resolves `AltRequest` from caller-provided fields + defaults
+ *   - Composes the prompt via `composePrompt(request, policies)`
+ *   - Calls `prepareForVision` on the bytes
+ *
+ * The adapter receives both the structured request (for native params
+ * like Anthropic's `max_tokens`) and the composed prompt string (for
+ * adapters that just inject text). Pre-computed once per call.
+ */
+export interface AltGenerateInput {
+    /** Bytes ready to send to the provider (post-prep, ≤ maxImageEdge). */
+    bytes: Uint8Array;
+    /** MIME of the prepared bytes — `image/jpeg` or `image/png`. */
+    mime: string;
+    /** Structured request — adapters with native parameters use this. */
+    request: AltRequest;
+    /** Composed prompt string — adapters that just need a prompt use this. */
+    prompt: string;
+}
+/**
+ * Per-task adapter contract. Every implementation honors this exactly;
+ * substitutable across tests and production via the factory.
+ *
+ * Throws on transport / provider errors (`AIAdapterFailedError` from
+ * `ai/errors.ts`). Refusals are NOT thrown — they're returned in the
+ * structured `AltSuggestion`. The distinction: throws are runtime
+ * failures (retryable; gateway-level concern); refusals are domain
+ * outcomes (not retryable; user-level concern).
+ */
+export interface AltTextAdapter {
+    /** Stable identifier for diagnostics ('anthropic', 'openai', 'ollama', 'null'). */
+    readonly name: string;
+    /**
+     * True when this adapter can describe the given MIME. v1.5 adapters
+     * support image MIMEs only. The null adapter returns false for
+     * everything.
+     */
+    supports(mime: string): boolean;
+    /**
+     * Generate alt text. Forwards `signal` to the underlying provider
+     * call so consumers can cancel in-flight requests (e.g., when the
+     * author starts typing into the alt field).
+     *
+     * Throws `AIAdapterFailedError` / `AIInvalidResponseError` on
+     * transport or response-shape failures. Returns refusals as
+     * `AltSuggestion` with `refused: true`.
+     */
+    generate(input: AltGenerateInput, signal?: AbortSignal): Promise<AltSuggestion>;
+}
+/**
+ * Type alias for prompt policies operating on alt-text requests.
+ * Per-task policy modules implement these and pass arrays to the
+ * generic `composePrompt<AltRequest>(req, policies)`.
+ */
+export type AltPromptPolicy = PromptPolicy<AltRequest>;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/alt/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/alt/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,KAAK,EAAE,QAAQ,CAAA;CAChB;AAED,uCAAuC;AACvC,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAA;AAEpC,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,EAAE,UAIjC,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAA;IAChB,0DAA0D;IAC1D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,KAAK,EAAE,UAAU,CAAA;IACjB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,OAAO,EAAE,UAAU,CAAA;IACnB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAE/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAChF;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,UAAU,CAAC,CAAA"}

package/dist/alt/adapter.js

@@ -0,0 +1,7 @@
+/** Default `AltRequest` values, applied by the suggester when callers omit fields. */
+export const DEFAULT_ALT_REQUEST = {
+    locale: 'en',
+    maxChars: 125,
+    style: 'descriptive',
+};
+//# sourceMappingURL=adapter.js.map

package/dist/alt/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/alt/adapter.ts"],"names":[],"mappings":"AAuEA,sFAAsF;AACtF,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,MAAM,EAAE,IAAI;IACZ,QAAQ,EAAE,GAAG;IACb,KAAK,EAAE,aAAa;CACrB,CAAA"}

package/dist/alt/anthropic.d.ts

@@ -0,0 +1,63 @@
+import type { AIProvider } from '../ai/provider.js';
+import type { AltTextAdapter } from './adapter.js';
+/**
+ * Default model for the Anthropic adapter. Haiku is the cost-optimized
+ * choice for the alt-text task (~$0.003/image at 768x768 input). Sites
+ * needing higher quality set `altText.model` in `site.config.ts` to a
+ * Sonnet or Opus model.
+ */
+export declare const ANTHROPIC_DEFAULT_MODEL = "claude-haiku-4-5";
+/**
+ * Anthropic transport-only options. Per Path X (single-axis with
+ * transport-vs-task split for AI), these fields bind to "which Anthropic
+ * account at which endpoint" — not to per-task tuning. Per-task config
+ * (model, systemPrompt, maxTokens) lives on the resolver-supplied
+ * `AltTextTaskConfig`, not here.
+ */
+export interface AnthropicTransportOptions {
+    apiKey: string;
+    /**
+     * Optional override of the SDK base URL — handy for tests pointing
+     * at msw, or future operators routing through a private proxy.
+     */
+    baseURL?: string;
+    /**
+     * Override the SDK's retry count (default 2). Tests pass 0 to keep
+     * runs deterministic and fast; production sticks with the default
+     * so transient 429/5xx are auto-retried with backoff.
+     */
+    maxRetries?: number;
+}
+/**
+ * Internal type for `createAnthropicAltAdapter` callers (tests).
+ * Combines transport with per-task config so existing tests don't have
+ * to thread two arguments. New code goes through the operator-facing
+ * `anthropicProvider(transport).altText(taskConfig)` chain.
+ */
+export interface AnthropicAltAdapterOptions extends AnthropicTransportOptions {
+    /** Model ID; defaults to {@link ANTHROPIC_DEFAULT_MODEL} when absent. */
+    model?: string;
+    /** Operator-supplied system prompt; prepended to system-composed prompt. */
+    systemPrompt?: string;
+    /** Generation token cap; provider derives from maxChars when absent. */
+    maxTokens?: number;
+}
+/**
+ * Construct the Anthropic alt-text adapter. Internal factory — kept
+ * public for tests + advanced wiring. Operator-facing config goes
+ * through `anthropicProvider(transport).altText(taskConfig)` (Path X).
+ */
+export declare function createAnthropicAltAdapter(opts: AnthropicAltAdapterOptions): AltTextAdapter;
+/**
+ * Operator-facing Anthropic provider. Constructs the transport-only
+ * `AIProvider` used in `site.config.ts`:
+ *
+ *   const anthropic = anthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! })
+ *   ai: { provider: anthropic, model: 'claude-haiku-4-5' }
+ *
+ * The provider exposes per-task builders (`.altText({...})`); the
+ * resolver supplies the merged `AltTextTaskConfig` from the three-rung
+ * inheritance chain at boot.
+ */
+export declare function anthropicProvider(transport: AnthropicTransportOptions): AIProvider;
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/alt/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../src/alt/anthropic.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,UAAU,EAAqB,MAAM,mBAAmB,CAAA;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AASlD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,qBAAqB,CAAA;AAUzD;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,yBAAyB;IAC3E,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAOD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,0BAA0B,GAAG,cAAc,CAoD1F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,yBAAyB,GAAG,UAAU,CAelF"}

package/dist/alt/anthropic.js

@@ -0,0 +1,147 @@
+/**
+ * Anthropic Claude adapter — alt-text via the `messages.create` vision API.
+ *
+ * # Defaults
+ *
+ *   - Model: `claude-haiku-4-5` (cost-effective vision; ~$0.003/image).
+ *     Sites needing higher quality override via `altText.model` in `site.config.ts`.
+ *
+ * # API contract details (verified against @anthropic-ai/sdk v0.92.0)
+ *
+ *   - Image content: `{ type: 'image', source: { type: 'base64',
+ *     media_type, data: <base64-string> } }`. SDK requires base64-encoded
+ *     string, not raw bytes/Uint8Array.
+ *   - Accepted MIME types: `image/jpeg`, `image/png`, `image/gif`,
+ *     `image/webp`. After `prepareForVision`, our bytes are always JPEG
+ *     or PNG, both supported.
+ *   - `max_tokens` is required by the API. Scaffold derives it from
+ *     `request.maxChars` unless operator overrides via `maxTokens`.
+ *   - `system` parameter at the top level (not a message role). The
+ *     scaffold-prepared `systemPrompt` (operator override + composed)
+ *     becomes the system prompt; the user message holds the image.
+ *
+ * # AbortSignal
+ *
+ *   - Passed via `messages.create(body, { signal })`. SDK throws
+ *     `APIUserAbortError` on abort; scaffold's `isAbortError` recognizes
+ *     it so the suggester can return null on cancellation.
+ *
+ * # SOLID
+ *
+ *   - SRP: this module owns the Anthropic-specific request shape and
+ *     response parsing only. Orchestration (prompt-prepend, max-tokens
+ *     derivation, error translation, refusal detection) lives in
+ *     `ai/adapter-scaffold.ts`.
+ *   - LSP: implements `AltTextAdapter` exactly via the scaffold —
+ *     substitutable.
+ *   - DIP: callers depend on `AltTextAdapter`; never on `Anthropic` SDK
+ *     type directly.
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import { AIInvalidResponseError } from '../ai/errors.js';
+import { buildAltAdapterFromScaffold } from '../ai/adapter-scaffold.js';
+/**
+ * Anthropic-specific refusal phrases observed in production responses
+ * but not yet in `ai/refusal.ts`'s shared list. Maintained here so
+ * provider-specific markers evolve independently of the shared list.
+ */
+const ANTHROPIC_REFUSAL_MARKERS = ['i cannot create captions', 'i cannot generate descriptions'];
+/**
+ * Default model for the Anthropic adapter. Haiku is the cost-optimized
+ * choice for the alt-text task (~$0.003/image at 768x768 input). Sites
+ * needing higher quality set `altText.model` in `site.config.ts` to a
+ * Sonnet or Opus model.
+ */
+export const ANTHROPIC_DEFAULT_MODEL = 'claude-haiku-4-5';
+/**
+ * Anthropic only accepts a subset of image MIME types. After
+ * `prepareForVision` our bytes are JPEG or PNG, but defending here
+ * means a future caller invoking the adapter directly with WebP or
+ * GIF still gets the right answer.
+ */
+const ANTHROPIC_SUPPORTED_MIMES = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp']);
+/** Encode a Uint8Array as a base64 string for the API call. */
+function toBase64(bytes) {
+    return Buffer.from(bytes).toString('base64');
+}
+/**
+ * Construct the Anthropic alt-text adapter. Internal factory — kept
+ * public for tests + advanced wiring. Operator-facing config goes
+ * through `anthropicProvider(transport).altText(taskConfig)` (Path X).
+ */
+export function createAnthropicAltAdapter(opts) {
+    const client = new Anthropic({
+        apiKey: opts.apiKey,
+        baseURL: opts.baseURL,
+        maxRetries: opts.maxRetries,
+    });
+    const model = opts.model ?? ANTHROPIC_DEFAULT_MODEL;
+    return buildAltAdapterFromScaffold({
+        name: 'anthropic',
+        supportedMimes: ANTHROPIC_SUPPORTED_MIMES,
+        operatorSystemPrompt: opts.systemPrompt,
+        operatorMaxTokens: opts.maxTokens,
+        refusalMarkers: ANTHROPIC_REFUSAL_MARKERS,
+        isAbortError: err => err instanceof Anthropic.APIUserAbortError,
+        async callProvider({ bytes, mime, systemPrompt, maxTokens, signal }) {
+            const response = await client.messages.create({
+                model,
+                max_tokens: maxTokens,
+                system: systemPrompt,
+                messages: [
+                    {
+                        role: 'user',
+                        content: [
+                            {
+                                type: 'image',
+                                source: {
+                                    type: 'base64',
+                                    // SDK accepts the four MIMEs above; cast is safe
+                                    // because supports() guards entry.
+                                    media_type: mime,
+                                    data: toBase64(bytes),
+                                },
+                            },
+                        ],
+                    },
+                ],
+            }, { signal });
+            // Response shape: `content` is an array of blocks; alt-text comes
+            // back as a single text block. Defensive against tool-use blocks
+            // or unexpected shapes by finding the first text block.
+            const textBlock = response.content.find(block => block.type === 'text');
+            if (!textBlock || textBlock.type !== 'text') {
+                throw new AIInvalidResponseError('Anthropic response contained no text content block');
+            }
+            return textBlock.text;
+        },
+    });
+}
+/**
+ * Operator-facing Anthropic provider. Constructs the transport-only
+ * `AIProvider` used in `site.config.ts`:
+ *
+ *   const anthropic = anthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! })
+ *   ai: { provider: anthropic, model: 'claude-haiku-4-5' }
+ *
+ * The provider exposes per-task builders (`.altText({...})`); the
+ * resolver supplies the merged `AltTextTaskConfig` from the three-rung
+ * inheritance chain at boot.
+ */
+export function anthropicProvider(transport) {
+    if (!transport.apiKey) {
+        throw new Error('anthropicProvider: "apiKey" is required (typically `process.env.ANTHROPIC_API_KEY!`)');
+    }
+    return {
+        name: 'anthropic',
+        altText(taskConfig) {
+            return createAnthropicAltAdapter({
+                ...transport,
+                model: taskConfig.model,
+                systemPrompt: taskConfig.systemPrompt,
+                maxTokens: taskConfig.maxTokens,
+            });
+        },
+    };
+}
+//# sourceMappingURL=anthropic.js.map

package/dist/alt/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../src/alt/anthropic.ts"],"names":[],"mappings":"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"}