@buildinternet/uploads 0.30.0 → 0.31.0

package/README.md

@@ -39,7 +39,7 @@ Inside this monorepo only, `pnpm uploads …` builds the package first so you pi
 up local source; product docs and PR “how to try it” examples should use the
 global `uploads` form above.
 
-Commands: `attach`, `put`, `screenshot`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
+Commands: `attach`, `put`, `screenshot`, `annotate`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
 `reconcile`, `purge-expired`, `setup`, `install`, `login`, `whoami` (alias `status`),
 `logout`, `invite`, `admin`, `config`, `telemetry`, `report`, `doctor`, `health`, `mcp`,
 `completion`.
@@ -141,6 +141,21 @@ the key already exists).
 community art from [device-frames-media](https://github.com/jonnyjackson26/device-frames-media)
 into `~/.cache/uploads/frames` (not bundled).
 
+## Annotating screenshots
+
+Bake hand-drawn boxes, arrows, labels, freeform strokes, and redactions onto
+a screenshot before it's uploaded:
+
+```bash
+uploads screenshot http://localhost:3000 --via local --annotate ./callouts.json
+uploads annotate ./shot.png --spec ./callouts.json --out ./shot.marked.png
+```
+
+`screenshot --annotate` resolves CSS selectors against the live page (local
+capture backend only); `annotate` works on an existing image and accepts
+pixel coordinates only, no selectors. Spec format and workflow:
+[`skills/annotate-screenshots/SKILL.md`](../../skills/annotate-screenshots/SKILL.md).
+
 ## Public galleries
 
 Create an ordered gallery, then add existing uploads by key. The API returns the canonical
@@ -212,4 +227,4 @@ pnpm pack:check   # verify the npm tarball contents
 
 Maintainer release instructions: [`docs/releasing.md`](../../docs/releasing.md).
 
-Agent-oriented usage: [`skills/uploads-cli/SKILL.md`](../../skills/uploads-cli/SKILL.md) (full CLI reference) and [`skills/github-screenshots/SKILL.md`](../../skills/github-screenshots/SKILL.md) (visuals into PRs/issues). REST details: [`docs/api.md`](../../docs/api.md).
+Agent-oriented usage: [`skills/uploads-cli/SKILL.md`](../../skills/uploads-cli/SKILL.md) (full CLI reference), [`skills/github-screenshots/SKILL.md`](../../skills/github-screenshots/SKILL.md) (visuals into PRs/issues), and [`skills/annotate-screenshots/SKILL.md`](../../skills/annotate-screenshots/SKILL.md) (callouts and redaction). REST details: [`docs/api.md`](../../docs/api.md).

package/assets/OFL.txt

@@ -0,0 +1,90 @@
+Excalifont — Copyright (c) 2024 by Excalidraw. All rights reserved.
+Designer: Your Own Font Foundry (Virgil); Ján Filípek / DizajnDesign (Excalifont, modifications)
+Licensed under the SIL Open Font License, Version 1.1 (below; also at http://scripts.sil.org/OFL).
+Latin subset of Excalifont-Regular, decompressed from the woff2 shipped in github.com/excalidraw/excalidraw.
+
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/annotate/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Screenshot annotation module — hand-drawn boxes, arrows, labels, freeform
+ * strokes, and redactions baked onto an image before upload.
+ *
+ * This file is the ONLY public surface of `src/annotate/`. Nothing outside
+ * this module may import from `./spec.js`, `./render.js`, `./shapes.js`, or
+ * `./text.js` directly — always go through here, so the renderer stays
+ * swappable (tldraw, a server-side `/v1/render`, …) without touching CLI
+ * callers.
+ */
+export type { Annotation, AnnotationSpec, ArrowAnnotation, BoxAnnotation, DrawAnnotation, LabelAnnotation, Point, RedactAnnotation, SpecError, SvgAnnotation, } from "./spec.js";
+export { AnnotateSpecError, hasSelectors, resolveSelectors, specSelectors, validateSpec, } from "./spec.js";
+export { clampReport, renderAnnotations, type RenderOptions } from "./render.js";

package/dist/annotate/index.js

@@ -0,0 +1,2 @@
+export { AnnotateSpecError, hasSelectors, resolveSelectors, specSelectors, validateSpec, } from "./spec.js";
+export { clampReport, renderAnnotations } from "./render.js";

package/dist/annotate/render.d.ts

@@ -0,0 +1,18 @@
+import { type AnnotationSpec } from "./spec.js";
+export interface RenderOptions {
+    seed?: number;
+    scale?: number;
+}
+/**
+ * Reports which annotations (by index) fall outside `[0, width) x [0, height)`
+ * and would be clamped by `renderAnnotations`. Pure and side-effect-free —
+ * the CLI layer decides how to surface these as warnings.
+ */
+export declare function clampReport(spec: AnnotationSpec, width: number, height: number): string[];
+/**
+ * Renders `spec` onto `image`, returning a new PNG buffer. Deterministic for
+ * a fixed `opts.seed` (defaults to 7). Throws `AnnotateSpecError` if any
+ * annotation still carries an unresolved `selector` — selectors must be
+ * resolved to pixel geometry (via `resolveSelectors`) before rendering.
+ */
+export declare function renderAnnotations(image: Buffer | Uint8Array, spec: AnnotationSpec, opts?: RenderOptions): Promise<Buffer>;

package/dist/annotate/render.js

@@ -0,0 +1,155 @@
+/**
+ * `renderAnnotations` — the sole render entry point of the annotate module.
+ * Pure: image + resolved spec in, PNG out. No browser/playwright knowledge.
+ *
+ * Not exported outside this module directly — only `index.ts` re-exports it
+ * (see the module header there). Callers that import `index.ts` and reach
+ * `renderAnnotations` must dynamic-`import()` it, because this file imports
+ * `sharp` statically and sharp must stay out of the static import graphs of
+ * `src/index.ts`, `src/agent.ts`, and `src/mcp/server.ts`.
+ */
+import sharp from "sharp";
+import { renderArrow, renderBox, renderDraw, renderLabel, renderRedactSolid, renderSvg, HOUSE_STYLE, } from "./shapes.js";
+import { AnnotateSpecError, hasSelectors } from "./spec.js";
+const DEFAULT_SEED = 7;
+const BASE_SCALE_REFERENCE_WIDTH = 1280;
+function clampBox(box, width, height) {
+    const x = Math.max(0, Math.min(box.x, width));
+    const y = Math.max(0, Math.min(box.y, height));
+    const w = Math.max(0, Math.min(box.w, width - x));
+    const h = Math.max(0, Math.min(box.h, height - y));
+    const clamped = x !== box.x || y !== box.y || w !== box.w || h !== box.h;
+    return { box: { x, y, w, h }, clamped };
+}
+/** Clamps a single geometric annotation's fields in place to a new plain object. */
+function clampAnnotation(a, width, height) {
+    switch (a.type) {
+        case "box":
+        case "redact": {
+            const { box, clamped } = clampBox({ x: a.x, y: a.y, w: a.w, h: a.h }, width, height);
+            return { annotation: { ...a, ...box }, clamped };
+        }
+        case "arrow": {
+            const clampPoint = (p) => {
+                const cx = Math.max(0, Math.min(p[0], width));
+                const cy = Math.max(0, Math.min(p[1], height));
+                return [[cx, cy], cx !== p[0] || cy !== p[1]];
+            };
+            const [from, fromClamped] = clampPoint(a.from);
+            const [to, toClamped] = clampPoint(a.to);
+            return { annotation: { ...a, from, to }, clamped: fromClamped || toClamped };
+        }
+        case "label": {
+            const at = a.at ?? a.target;
+            if (!at)
+                return { annotation: a, clamped: false };
+            const cx = Math.max(0, Math.min(at[0], width));
+            const cy = Math.max(0, Math.min(at[1], height));
+            const clamped = cx !== at[0] || cy !== at[1];
+            if (!clamped)
+                return { annotation: a, clamped: false };
+            return {
+                annotation: a.at ? { ...a, at: [cx, cy] } : { ...a, target: [cx, cy] },
+                clamped,
+            };
+        }
+        case "draw":
+        case "svg":
+        default:
+            return { annotation: a, clamped: false };
+    }
+}
+/**
+ * Reports which annotations (by index) fall outside `[0, width) x [0, height)`
+ * and would be clamped by `renderAnnotations`. Pure and side-effect-free —
+ * the CLI layer decides how to surface these as warnings.
+ */
+export function clampReport(spec, width, height) {
+    const warnings = [];
+    spec.annotations.forEach((a, index) => {
+        const { clamped } = clampAnnotation(a, width, height);
+        if (clamped) {
+            warnings.push(`annotations[${index}]: geometry out of bounds, clamped to image size`);
+        }
+    });
+    return warnings;
+}
+function scaleFor(width, opts) {
+    if (opts?.scale)
+        return opts.scale;
+    return Math.max(1, Math.round(width / BASE_SCALE_REFERENCE_WIDTH));
+}
+async function redactBlurLayer(base, region, width, height) {
+    const left = Math.round(region.x);
+    const top = Math.round(region.y);
+    const w = Math.round(region.w);
+    const h = Math.round(region.h);
+    if (w <= 0 || h <= 0 || left >= width || top >= height)
+        return null;
+    const clampedW = Math.min(w, width - left);
+    const clampedH = Math.min(h, height - top);
+    if (clampedW <= 0 || clampedH <= 0)
+        return null;
+    const blurred = await sharp(base)
+        .extract({ left, top, width: clampedW, height: clampedH })
+        .blur(HOUSE_STYLE.redactBlurSigma)
+        .png()
+        .toBuffer();
+    return { input: blurred, left, top };
+}
+/**
+ * Renders `spec` onto `image`, returning a new PNG buffer. Deterministic for
+ * a fixed `opts.seed` (defaults to 7). Throws `AnnotateSpecError` if any
+ * annotation still carries an unresolved `selector` — selectors must be
+ * resolved to pixel geometry (via `resolveSelectors`) before rendering.
+ */
+export async function renderAnnotations(image, spec, opts) {
+    if (hasSelectors(spec)) {
+        throw new AnnotateSpecError([
+            { index: null, message: "spec still has unresolved selectors; call resolveSelectors first" },
+        ]);
+    }
+    const base = Buffer.isBuffer(image) ? image : Buffer.from(image);
+    const baseImg = sharp(base);
+    const meta = await baseImg.metadata();
+    const width = meta.width ?? 0;
+    const height = meta.height ?? 0;
+    const seed = opts?.seed ?? DEFAULT_SEED;
+    const scale = scaleFor(width, opts);
+    const ctx = { seed, scale };
+    const clamped = spec.annotations.map((a) => clampAnnotation(a, width, height).annotation);
+    // Blur redactions are applied as a pre-pass (extract -> blur -> composite
+    // back) BEFORE the sketchy overlay pass, per the house style. The blurs are
+    // independent reads of the same immutable base, so they run concurrently.
+    const compositeOps = (await Promise.all(clamped.map((annotation) => annotation.type === "redact" && (annotation.style ?? "solid") === "blur"
+        ? redactBlurLayer(base, { x: annotation.x, y: annotation.y, w: annotation.w, h: annotation.h }, width, height)
+        : Promise.resolve(null)))).filter((layer) => layer !== null);
+    const overlayParts = [];
+    for (const annotation of clamped) {
+        switch (annotation.type) {
+            case "box":
+                overlayParts.push(renderBox(annotation, ctx));
+                break;
+            case "arrow":
+                overlayParts.push(renderArrow(annotation, ctx));
+                break;
+            case "label":
+                overlayParts.push(renderLabel(annotation, ctx));
+                break;
+            case "draw":
+                overlayParts.push(renderDraw(annotation, ctx));
+                break;
+            case "redact":
+                if ((annotation.style ?? "solid") === "solid") {
+                    overlayParts.push(renderRedactSolid(annotation));
+                }
+                break;
+            case "svg":
+                overlayParts.push(renderSvg(annotation));
+                break;
+        }
+    }
+    const overlaySvg = `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">${overlayParts.join("")}</svg>`;
+    compositeOps.push({ input: Buffer.from(overlaySvg), left: 0, top: 0 });
+    return sharp(base).composite(compositeOps).png().toBuffer();
+}

package/dist/annotate/shapes.d.ts

@@ -0,0 +1,23 @@
+import type { ArrowAnnotation, BoxAnnotation, DrawAnnotation, LabelAnnotation, RedactAnnotation, SvgAnnotation } from "./spec.js";
+export declare const HOUSE_STYLE: {
+    readonly stroke: "#e11d48";
+    readonly roughness: 1.5;
+    readonly labelBorder: "#0f172a";
+    readonly labelFill: "#ffffff";
+    readonly labelFillOpacity: 0.92;
+    readonly redactFill: "#111111";
+    readonly redactBlurSigma: 18;
+    readonly labelPadding: 8;
+};
+interface RenderCtx {
+    seed: number;
+    scale: number;
+}
+export declare function renderBox(a: BoxAnnotation, ctx: RenderCtx): string;
+export declare function renderArrow(a: ArrowAnnotation, ctx: RenderCtx): string;
+export declare function renderLabel(a: LabelAnnotation, ctx: RenderCtx): string;
+export declare function renderDraw(a: DrawAnnotation, ctx: RenderCtx): string;
+/** Redact overlay drawn into the SVG pass (solid style only; blur is a sharp pre-pass). */
+export declare function renderRedactSolid(a: RedactAnnotation): string;
+export declare function renderSvg(a: SvgAnnotation): string;
+export {};

package/dist/annotate/shapes.js

@@ -0,0 +1,147 @@
+/**
+ * Per-annotation path generation: rough.js for sketchy shapes, perfect-freehand
+ * for freeform strokes, opentype.js paths for label text.
+ *
+ * Not exported outside this module — only `index.ts` re-exports the public
+ * surface (see the module header there).
+ */
+import { getStroke } from "perfect-freehand";
+import rough from "roughjs/bundled/rough.esm.js";
+import { AnnotateSpecError, DEFAULT_PLACEMENT, unsafeSvgFragmentReason } from "./spec.js";
+import { measureText, textToPath } from "./text.js";
+export const HOUSE_STYLE = {
+    stroke: "#e11d48",
+    roughness: 1.5,
+    labelBorder: "#0f172a",
+    labelFill: "#ffffff",
+    labelFillOpacity: 0.92,
+    redactFill: "#111111",
+    redactBlurSigma: 18,
+    labelPadding: 8,
+};
+/**
+ * Escapes a user-controlled string for use inside an SVG attribute value —
+ * `color` comes straight from agent-authored spec JSON, and an unescaped `"`
+ * would break out of the attribute and inject markup into the overlay SVG.
+ */
+function escapeAttr(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/"/g, """)
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function pathsToSvg(gen, drawable) {
+    return gen
+        .toPaths(drawable)
+        .map((p) => `<path d="${p.d}" fill="${escapeAttr(p.fill ?? "none")}" stroke="${escapeAttr(p.stroke ?? "none")}" stroke-width="${p.strokeWidth ?? 1}"/>`)
+        .join("");
+}
+function generator(ctx) {
+    return rough.generator({ options: { seed: ctx.seed, roughness: HOUSE_STYLE.roughness } });
+}
+export function renderBox(a, ctx) {
+    const gen = generator(ctx);
+    const strokeWidth = 3 * ctx.scale;
+    const d = gen.rectangle(a.x, a.y, a.w, a.h, {
+        stroke: a.color ?? HOUSE_STYLE.stroke,
+        strokeWidth,
+        fill: "none",
+    });
+    return pathsToSvg(gen, d);
+}
+/** Shared arrow rendering: rough shaft + two rough head strokes. */
+function arrowSvg(from, to, color, ctx) {
+    const gen = generator(ctx);
+    const strokeWidth = 3 * ctx.scale;
+    const [x1, y1] = from;
+    const [x2, y2] = to;
+    const angle = Math.atan2(y2 - y1, x2 - x1);
+    const headLen = 22 * ctx.scale;
+    const headSpread = 0.5;
+    const hx1 = x2 - headLen * Math.cos(angle - headSpread);
+    const hy1 = y2 - headLen * Math.sin(angle - headSpread);
+    const hx2 = x2 - headLen * Math.cos(angle + headSpread);
+    const hy2 = y2 - headLen * Math.sin(angle + headSpread);
+    const shaft = gen.line(x1, y1, x2, y2, { stroke: color, strokeWidth });
+    const headA = gen.line(x2, y2, hx1, hy1, { stroke: color, strokeWidth });
+    const headB = gen.line(x2, y2, hx2, hy2, { stroke: color, strokeWidth });
+    return pathsToSvg(gen, shaft) + pathsToSvg(gen, headA) + pathsToSvg(gen, headB);
+}
+export function renderArrow(a, ctx) {
+    return arrowSvg(a.from, a.to, a.color ?? HOUSE_STYLE.stroke, ctx);
+}
+export function renderLabel(a, ctx) {
+    const color = a.color ?? HOUSE_STYLE.stroke;
+    const fontSize = 28 * ctx.scale;
+    const padding = HOUSE_STYLE.labelPadding * ctx.scale;
+    // With no explicit `at`, offset the bubble away from its target so it
+    // doesn't sit on top of the thing it labels (clamped to stay on-image).
+    const at = a.at ??
+        (a.target
+            ? [
+                a.target[0] + DEFAULT_PLACEMENT.labelAt[0] * ctx.scale,
+                Math.max(8, a.target[1] + DEFAULT_PLACEMENT.labelAt[1] * ctx.scale),
+            ]
+            : [0, 0]);
+    const [atX, atY] = at;
+    const metrics = measureText(a.text, fontSize);
+    const bubbleW = metrics.width + padding * 2;
+    const bubbleH = metrics.height + padding * 2;
+    const bubbleX = atX;
+    const bubbleY = atY;
+    const gen = generator(ctx);
+    const bubble = gen.rectangle(bubbleX, bubbleY, bubbleW, bubbleH, {
+        stroke: HOUSE_STYLE.labelBorder,
+        strokeWidth: 2 * ctx.scale,
+        fill: HOUSE_STYLE.labelFill,
+        fillStyle: "solid",
+    });
+    const bubbleSvg = `<g opacity="${HOUSE_STYLE.labelFillOpacity}">${pathsToSvg(gen, bubble)}</g>`;
+    const textBaselineX = bubbleX + padding;
+    const textBaselineY = bubbleY + padding + metrics.height * 0.78;
+    const { d } = textToPath(a.text, textBaselineX, textBaselineY, fontSize);
+    const textSvg = `<path d="${d}" fill="${HOUSE_STYLE.labelBorder}"/>`;
+    let leaderSvg = "";
+    if (a.target) {
+        const [tx, ty] = a.target;
+        const bubbleCenterX = bubbleX + bubbleW / 2;
+        const bubbleCenterY = bubbleY + bubbleH / 2;
+        // leader from the nearest bubble edge point toward the target
+        const dx = tx - bubbleCenterX;
+        const dy = ty - bubbleCenterY;
+        const edgeX = dx === 0 ? bubbleCenterX : bubbleCenterX + Math.sign(dx) * (bubbleW / 2);
+        const edgeY = dy === 0 ? bubbleCenterY : bubbleCenterY + Math.sign(dy) * (bubbleH / 2);
+        leaderSvg = arrowSvg([edgeX, edgeY], [tx, ty], color, ctx);
+    }
+    return bubbleSvg + textSvg + leaderSvg;
+}
+/** Turns a perfect-freehand outline polygon into a closed SVG path `d`. */
+function strokeToPath(stroke) {
+    if (!stroke.length)
+        return "";
+    const d = stroke.reduce((acc, [x0, y0], i, arr) => {
+        const [x1, y1] = arr[(i + 1) % arr.length];
+        acc.push(x0, y0, (x0 + x1) / 2, (y0 + y1) / 2);
+        return acc;
+    }, ["M", ...stroke[0], "Q"]);
+    return `${d.join(" ")} Z`;
+}
+export function renderDraw(a, ctx) {
+    const color = a.color ?? HOUSE_STYLE.stroke;
+    const stroke = getStroke(a.points.map(([x, y]) => [x, y]), { size: 4 * ctx.scale, smoothing: 0.6, streamline: 0.4 });
+    const d = strokeToPath(stroke);
+    return `<path d="${d}" fill="${escapeAttr(color)}" opacity="0.9"/>`;
+}
+/** Redact overlay drawn into the SVG pass (solid style only; blur is a sharp pre-pass). */
+export function renderRedactSolid(a) {
+    return `<rect x="${a.x}" y="${a.y}" width="${a.w}" height="${a.h}" fill="${HOUSE_STYLE.redactFill}"/>`;
+}
+export function renderSvg(a) {
+    // Defense in depth: validateSpec already rejects unsafe fragments, but a
+    // caller could hand renderAnnotations a hand-built spec that skipped it.
+    const unsafe = unsafeSvgFragmentReason(a.fragment);
+    if (unsafe)
+        throw new AnnotateSpecError([{ index: null, message: unsafe }]);
+    return `<g>${a.fragment}</g>`;
+}

package/dist/annotate/spec.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Annotation spec: types, validation, and selector resolution.
+ *
+ * NOT exported outside this module directly — only `index.ts` re-exports
+ * these. Keep the public surface narrow so the renderer stays swappable
+ * (see the module header in `index.ts`).
+ */
+export type Point = [number, number];
+export interface BoxAnnotation {
+    type: "box";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color?: string;
+    selector?: string;
+}
+export interface ArrowAnnotation {
+    type: "arrow";
+    from: Point;
+    to: Point;
+    color?: string;
+    selector?: string;
+}
+export interface LabelAnnotation {
+    type: "label";
+    text: string;
+    target?: Point;
+    at?: Point;
+    color?: string;
+    selector?: string;
+}
+export interface DrawAnnotation {
+    type: "draw";
+    points: Point[];
+    color?: string;
+}
+export interface RedactAnnotation {
+    type: "redact";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    style?: "blur" | "solid";
+    selector?: string;
+}
+export interface SvgAnnotation {
+    type: "svg";
+    fragment: string;
+}
+export type Annotation = BoxAnnotation | ArrowAnnotation | LabelAnnotation | DrawAnnotation | RedactAnnotation | SvgAnnotation;
+export interface AnnotationSpec {
+    version: 1;
+    annotations: Annotation[];
+}
+export interface SpecError {
+    index: number | null;
+    message: string;
+}
+/** Thrown by `validateSpec` and `resolveSelectors`; carries every collected error. */
+export declare class AnnotateSpecError extends Error {
+    readonly errors: SpecError[];
+    constructor(errors: SpecError[]);
+}
+type Box = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Default placement offsets used when a spec omits an explicit position —
+ * kept together so "where things land by default" has one home. Units are
+ * image pixels; `labelAt` is additionally multiplied by the render scale.
+ */
+export declare const DEFAULT_PLACEMENT: {
+    /** Selector-only arrow: tail offset from the target center (resolveSelectors). */
+    arrowFrom: readonly [120, -120];
+    /** Label with a target but no `at`: bubble offset above-right (renderLabel). */
+    labelAt: readonly [30, -90];
+};
+/**
+ * Returns a rejection reason if a raw `svg` fragment is unsafe, else null.
+ * Shared by `validateSpec` and the renderer (defense in depth — the renderer
+ * re-checks in case a caller bypasses validation): `<script` is an obvious
+ * injection, and librsvg resolves href/xlink:href and CSS url() references,
+ * which has been an arbitrary-file-read vector (e.g. CVE-2023-38633).
+ */
+export declare function unsafeSvgFragmentReason(fragment: string): string | null;
+/** Throws AnnotateSpecError (carries errors: SpecError[]) on invalid input. */
+export declare function validateSpec(json: unknown): AnnotationSpec;
+/** True if any annotation still carries an unresolved selector. */
+export declare function hasSelectors(spec: AnnotationSpec): boolean;
+/** All distinct selectors in the spec, in order. */
+export declare function specSelectors(spec: AnnotationSpec): string[];
+/**
+ * Replace selector targeting with pixel geometry using measured boxes keyed
+ * by selector. Throws AnnotateSpecError naming any selector missing from
+ * boxes.
+ */
+export declare function resolveSelectors(spec: AnnotationSpec, boxes: Record<string, Box>): AnnotationSpec;
+export {};