@pixerate/editor 0.260.0 → 0.262.0

package/dist/paint-editor/index.d.cts

@@ -57,4 +57,5 @@ export type { StickerProvider, StickerRef, StickerSummary } from '../stickers/ty
 export * from './sticker-art.cjs';
 export * from './collaboration.cjs';
 export * from './collaboration-tools.cjs';
-export { paintContracts, PAINT_CONTRACT_FORMAT_VERSION, PAINT_DOCUMENT_JSON_SCHEMA } from './contract.cjs';
+export { samplePath, MAX_PATH_SAMPLES, type PathSampleOptions } from './path-samples.cjs';
+export { createPaintConformanceHost, paintContracts, PAINT_CONTRACT_FORMAT_VERSION, PAINT_DOCUMENT_JSON_SCHEMA } from './contract.cjs';

package/dist/paint-editor/index.d.ts

@@ -57,4 +57,5 @@ export type { StickerProvider, StickerRef, StickerSummary } from '../stickers/ty
 export * from './sticker-art.js';
 export * from './collaboration.js';
 export * from './collaboration-tools.js';
-export { paintContracts, PAINT_CONTRACT_FORMAT_VERSION, PAINT_DOCUMENT_JSON_SCHEMA } from './contract.js';
+export { samplePath, MAX_PATH_SAMPLES, type PathSampleOptions } from './path-samples.js';
+export { createPaintConformanceHost, paintContracts, PAINT_CONTRACT_FORMAT_VERSION, PAINT_DOCUMENT_JSON_SCHEMA } from './contract.js';

package/dist/paint-editor/index.js

@@ -19,6 +19,9 @@ import {
 import {
   toVideoFfmpeg
 } from "../chunk-MWUZCEFT.js";
+import {
+  ToolRegistry
+} from "../chunk-K4BGRCSH.js";
 import {
   BRUSH_OPTION_CONTROLS,
   createLayerEffectTools,
@@ -150,7 +153,11 @@ import {
   stickerIdFor
 } from "../chunk-APX63ILU.js";
 import "../chunk-M6DNZNVY.js";
-import "../chunk-WEIK3UYB.js";
+import {
+  bezierPathToSvg,
+  flattenChain,
+  pathToContours
+} from "../chunk-WEIK3UYB.js";
 import "../chunk-PWBZH3FK.js";
 import {
   brushColourHex
@@ -274,7 +281,8 @@ import "../chunk-VDGBHYC7.js";
 import {
   EDITOR_DOCUMENT_FORMAT,
   createEditorAssetRegistry,
-  defineEditorDocument
+  defineEditorDocument,
+  toEditorDocumentFile
 } from "../chunk-XBQX76CT.js";
 import "../chunk-HF5QZS7Z.js";
 import "../chunk-M2TPMYJE.js";
@@ -5221,6 +5229,55 @@ function engineChanges(base, next) {
   return rest;
 }
 
+// src/paint-editor/path-samples.ts
+var FLATTEN_TOLERANCE = 0.1;
+var MAX_PATH_SAMPLES = 2e4;
+function profileAt(profile, t) {
+  if (profile.length === 1) return profile[0];
+  const at = t * (profile.length - 1);
+  const i = Math.min(profile.length - 2, Math.floor(at));
+  return profile[i] + (profile[i + 1] - profile[i]) * (at - i);
+}
+function samplePath(d, options = {}) {
+  const spacing = options.spacing ?? 2;
+  if (!(spacing >= 0.25 && spacing <= 100)) throw new Error(`spacing ${spacing} is out of range; use 0.25..100 document pixels.`);
+  const profile = options.pressure;
+  if (profile && (!profile.length || profile.some((p) => !(p >= 0 && p <= 1)))) throw new Error("pressure needs one or more values from 0 to 1, e.g. [0.2, 1, 0.2] for a taper.");
+  let contours;
+  try {
+    contours = pathToContours(d);
+  } catch (e) {
+    throw new Error(`path is not SVG path data (${e instanceof Error ? e.message : String(e)}); give e.g. "M 10 10 C 40 0 80 60 120 30".`);
+  }
+  const out = [];
+  for (const contour of contours) {
+    if (!contour.segments.length) continue;
+    const line = flattenChain(contour.segments, FLATTEN_TOLERANCE);
+    if (contour.closed && line.length) line.push(line[0]);
+    const lengths = [0];
+    for (let i = 1; i < line.length; i++) lengths.push(lengths[i - 1] + Math.hypot(line[i][0] - line[i - 1][0], line[i][1] - line[i - 1][1]));
+    const total = lengths[lengths.length - 1];
+    const n = Math.max(1, Math.ceil(total / spacing));
+    if (n + 1 > MAX_PATH_SAMPLES) throw new Error(`The path is ${Math.round(total)} px long: too many samples at spacing ${spacing}; use a larger spacing (at least ${Math.ceil(total / (MAX_PATH_SAMPLES - 1))}).`);
+    const points = [];
+    let j = 0;
+    for (let k = 0; k <= n; k++) {
+      const at = total * k / n;
+      while (j < line.length - 2 && lengths[j + 1] < at) j++;
+      const span = lengths[j + 1] - lengths[j] || 1;
+      const f = line.length > 1 ? Math.min(1, Math.max(0, (at - lengths[j]) / span)) : 0;
+      const a = line[j];
+      const b = line[Math.min(j + 1, line.length - 1)];
+      const x = Math.round((a[0] + (b[0] - a[0]) * f) * 1e3) / 1e3;
+      const y = Math.round((a[1] + (b[1] - a[1]) * f) * 1e3) / 1e3;
+      points.push(profile ? { x, y, pressure: Math.round(profileAt(profile, k / n) * 1e3) / 1e3 } : { x, y });
+    }
+    out.push(points);
+  }
+  if (!out.length) throw new Error('path has no segments to brush; give SVG path data such as "M 10 10 L 200 80".');
+  return out;
+}
+
 // src/paint-editor/live-strokes.ts
 var LIVE_STROKE_ENGINES = ["dab", "particle", "bristle", "mixer"];
 function liveStrokeRefusal(brush) {
@@ -7857,6 +7914,47 @@ var PaintEditorController = class _PaintEditorController {
     else this.emit([]);
     return result;
   }
+  /**
+   * Brushes vector path data (SVG `d`, document pixels) with the active brush, or `brushId` /
+   * `brush`, as if drawn by hand: one recorded stroke per subpath, sampled every `spacing` px
+   * with an optional `pressure` profile along each. All of it is one undo step. A given `seed`
+   * seeds the first subpath; the next ones take the following seeds.
+   */
+  strokePath(init) {
+    this.requireIdle("painting");
+    if (typeof init.path !== "string" || !init.path.trim()) throw new PaintEditorError('path is empty; give SVG path data in document pixels, e.g. "M 10 10 C 40 0 80 60 120 30".');
+    let subpaths;
+    try {
+      subpaths = samplePath(init.path, init);
+    } catch (e) {
+      throw new PaintEditorError(e instanceof Error ? e.message : String(e));
+    }
+    const { path: _path, spacing: _spacing, pressure: _pressure, ...stroke } = init;
+    const before = this.doc;
+    let doc = this.doc;
+    let bounds = null;
+    let dabs = 0;
+    const strokeIds = [];
+    let last = null;
+    try {
+      subpaths.forEach((points, i) => {
+        last = this.runStroke(doc, { ...stroke, ...stroke.seed !== void 0 ? { seed: stroke.seed + i } : {}, start: points[0] }, points);
+        doc = last.doc;
+        bounds = unionRect(bounds, last.result.bounds);
+        dabs += last.result.dabs;
+        if (last.result.strokeId) strokeIds.push(last.result.strokeId);
+      });
+    } catch (e) {
+      this.wetOp = null;
+      throw e;
+    }
+    const run = last;
+    if (run?.result.mixerLoad) this.keepLoad(run.brush, run.result.mixerLoad);
+    if (doc !== before || this.wetOp) this.commit(`${run?.brush.name ?? "Brush"} path stroke`, this.withWetEvents(doc), before);
+    else this.emit([]);
+    const layerId = run?.result.layerId ?? stroke.layerId ?? this.doc.activeLayerId ?? "";
+    return { layerId, bounds, dabs, strokeIds, ...run?.result.mixerLoad ? { mixerLoad: run.result.mixerLoad } : {}, ...run?.result.wet !== void 0 ? { wet: run.result.wet } : {} };
+  }
   /** Checks stroke samples (finite x and y, pressure 0..1) and returns them; throws a sentence naming the bad point. */
   checkPoints(points) {
     if (!Array.isArray(points) || !points.length) throw new PaintEditorError("points is empty; give at least one {x, y} in document pixels.");
@@ -11579,6 +11677,41 @@ function createPaintEditorToolProvider(controller, options = {}) {
       return r.mixerLoad ? { ...r, mixerLoad: loadResult(r.mixerLoad) } : r;
     }
   });
+  add({
+    name: "stroke_path",
+    title: "Brush along a path",
+    description: "Brushes vector path data (SVG path d in document pixels: M, L, H, V, C, S, Q, T, A and Z) on a pixel layer with a library brush or the active one, as if drawn by hand along it: the outline of a shape, a lettering guide, a curve from a vector tool. Each subpath becomes one recorded stroke, sampled every spacing px, with an optional pressure profile spread along each subpath (a taper such as [0.2, 1, 0.2]); closed subpaths end where they start. Brushes behave as in paint_stroke (grain, pick-up, wet and thick paint, guides off). One undo step for the whole path. Returns the layer id, changed bounds, dab count and the recorded strokeIds (for replay_strokes, update_stroke).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", minLength: 1, description: 'SVG path data in document pixels, e.g. "M 40 200 C 120 40 280 40 360 200". Several subpaths paint several strokes.' },
+        spacing: { type: "number", minimum: 0.25, maximum: 100, description: "Distance between samples along the path in document pixels (default 2); the brush spaces its own dabs, so this only sets how closely curves are followed." },
+        pressure: { type: "array", minItems: 1, maxItems: 64, items: { type: "number", minimum: 0, maximum: 1 }, description: "Pen pressure along each subpath, spread evenly from start to end (default full pressure); [0.2, 1, 0.2] tapers both ends." },
+        layerId: LAYER_ID4,
+        brushId: { type: "string", description: "Brush id from list_brush_presets (default the active brush)." },
+        brush: { type: "object", description: "Facets to change for this stroke only, laid over brushId or the active brush (as set_brush takes them).", properties: BRUSH_PATCH_PROPERTIES, additionalProperties: false },
+        color: { ...COLOR3, description: "Paint colour #rrggbb (default the paint colour)." },
+        paint: { ...PAINT_SOURCE_JSON_SCHEMA, description: "What the strokes paint with instead of the editor's paint: a colour, or gradient paint that changes colour as each stroke goes." },
+        seed: { type: "integer", minimum: 0, description: "Jitter seed of the first subpath, the next ones take the following seeds (default new ones); the same seed and path give the same marks." }
+      },
+      required: ["path"],
+      additionalProperties: false
+    },
+    annotations: { title: "Brush along a path", ...WRITE5 },
+    coordinates: { out: ["bounds"] },
+    handler: async (a) => {
+      await c.wetIdle();
+      const base = a.brushId ? c.getBrush(a.brushId) : c.getState().brush;
+      const brush = a.brush ? c.brushChanges(a.brush, a.brushId) : void 0;
+      if (base) {
+        const refs = brushStickerRefs(normalizePaintBrush({ ...brush ?? {}, id: base.id }, base));
+        if (refs.length) await c.prepareStickers(refs);
+      }
+      const path = options.origin && typeof a.path === "string" && a.path.trim() ? bezierPathToSvg(a.path, { offset: { x: -options.origin.x, y: -options.origin.y } }) : a.path;
+      const r = c.strokePath({ path, spacing: a.spacing, pressure: a.pressure, layerId: a.layerId, brushId: a.brushId, brush, color: a.color, paint: a.paint, seed: a.seed });
+      return r.mixerLoad ? { ...r, mixerLoad: loadResult(r.mixerLoad) } : r;
+    }
+  });
   add({
     name: "get_live_stroke",
     title: "Get the stroke being painted",
@@ -12480,6 +12613,12 @@ function toggleDotTexture(textures, stamp) {
   if (textures.includes(stamp)) return textures.filter((s) => s !== stamp);
   return textures.length < MAX_DOT_TEXTURES ? [...textures, stamp] : [...textures];
 }
+var PATH_STROKE_TAPERS = [
+  { id: "even", label: "Even" },
+  { id: "both", label: "Taper both ends", pressure: [0.2, 1, 0.2] },
+  { id: "in", label: "Fade in", pressure: [0.2, 1] },
+  { id: "out", label: "Fade out", pressure: [1, 0.2] }
+];
 var STROKE_SLIDERS = [
   { path: "tip.size", label: "Size", min: 1, max: 400, step: 1 },
   { path: "tip.opacity", label: "Opacity", min: 0, max: 1, step: 0.01 },
@@ -13270,6 +13409,7 @@ function uiTables() {
     blendMenu: BLEND_MENU_GROUPS,
     layerEffects: LAYER_EFFECT_MENU.map(({ kind, label }) => ({ kind, label, controls: layerEffectControls(defaultLayerEffect(kind, kind)) })),
     sliders: { paper: PAPER_SLIDERS, wet: WET_PARAM_SLIDERS, wetTilt: WET_TILT_SLIDERS, wetSpeed: WET_SPEED_SLIDER, light: LIGHT_SLIDERS, stroke: STROKE_SLIDERS, sticker: STICKER_SLIDERS },
+    pathStrokeTapers: PATH_STROKE_TAPERS,
     padSampleSizes: PAD_SAMPLE_SIZES,
     wetGpu: WET_GPU_OPTIONS,
     labels: {
@@ -13310,6 +13450,23 @@ function paintContracts(options) {
   };
   return files;
 }
+var GENERATED_ID = /^(pl[0-9a-z]{9,}|[a-z]+_[0-9a-z]{8,}_[0-9a-z]+)$/;
+function createPaintConformanceHost(setup, options) {
+  const controller = new PaintEditorController({ ...setup, wet: { kernel: "typescript", threads: 0, gpu: "off", ...setup.wet } });
+  controller.setEffectsProvider(options.effects);
+  const registry = new ToolRegistry({ validateArguments: true });
+  registry.register(createPaintEditorToolProvider(controller));
+  registry.register(createPaintEffectsToolProvider(controller));
+  registry.register(createPaintBrushLibraryToolProvider(controller));
+  registry.register(createPaintProposalToolProvider(createPaintProposals({ controller })));
+  return {
+    callTool: (name, args) => registry.callTool(name, args),
+    document: () => toEditorDocumentFile(createPaintEditorDocument(controller)),
+    pixels: ({ paper }) => controller.compositePixels({ paper }),
+    isGeneratedId: (value) => GENERATED_ID.test(value),
+    dispose: () => controller.dispose()
+  };
+}
 export {
   BACKLIGHT_SPILL,
   BLEND_MENU_GROUPS,
@@ -13364,6 +13521,7 @@ export {
   MAX_DOT_TEXTURES,
   MAX_IMAGE_SIDE,
   MAX_LIVE_EFFECT_SOURCES,
+  MAX_PATH_SAMPLES,
   MAX_STICKER_STAMPS,
   MAX_ZOOM,
   MIN_CANVAS_SIDE,
@@ -13407,6 +13565,7 @@ export {
   PARTICLE_KIND_LABELS,
   PARTICLE_RENDERS,
   PARTICLE_RENDER_LABELS,
+  PATH_STROKE_TAPERS,
   PaintCanvasPresenter,
   PaintDabStroke,
   PaintDirector,
@@ -13477,6 +13636,7 @@ export {
   createPaintBrushLibraryToolProvider,
   createPaintChangeFeed,
   createPaintCompositor,
+  createPaintConformanceHost,
   createPaintDocument,
   createPaintEditorDocument,
   createPaintEditorToolProvider,
@@ -13617,6 +13777,7 @@ export {
   sampleArt,
   sampleEffectAt,
   sampleEffectField,
+  samplePath,
   samplePressure,
   scalePaintGradient,
   scaleStencil,

package/dist/paint-editor/path-samples.d.cts

@@ -0,0 +1,19 @@
+/**
+ * Pen samples along vector path data, so a path can be brushed like a hand-drawn stroke
+ * (`strokePath`, the `stroke_path` tool): each subpath becomes one stroke, sampled at an even
+ * spacing, with an optional pressure profile spread along its length (a taper).
+ */
+import type { PenPoint } from './engine.cjs';
+/** The most samples one subpath may have (the stroke tools' point limit). */
+export declare const MAX_PATH_SAMPLES = 20000;
+export interface PathSampleOptions {
+    /** Distance between samples in document pixels (default 2). */
+    spacing?: number;
+    /** Pressure along each subpath, spread evenly from its start to its end (default full pressure). */
+    pressure?: readonly number[];
+}
+/**
+ * Samples SVG path data (document pixels) into pen points, one array per subpath. Closed
+ * subpaths end where they start. Throws a sentence when the path has nothing to brush.
+ */
+export declare function samplePath(d: string, options?: PathSampleOptions): PenPoint[][];

package/dist/paint-editor/path-samples.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pen samples along vector path data, so a path can be brushed like a hand-drawn stroke
+ * (`strokePath`, the `stroke_path` tool): each subpath becomes one stroke, sampled at an even
+ * spacing, with an optional pressure profile spread along its length (a taper).
+ */
+import type { PenPoint } from './engine.js';
+/** The most samples one subpath may have (the stroke tools' point limit). */
+export declare const MAX_PATH_SAMPLES = 20000;
+export interface PathSampleOptions {
+    /** Distance between samples in document pixels (default 2). */
+    spacing?: number;
+    /** Pressure along each subpath, spread evenly from its start to its end (default full pressure). */
+    pressure?: readonly number[];
+}
+/**
+ * Samples SVG path data (document pixels) into pen points, one array per subpath. Closed
+ * subpaths end where they start. Throws a sentence when the path has nothing to brush.
+ */
+export declare function samplePath(d: string, options?: PathSampleOptions): PenPoint[][];

package/dist/paint-editor/ui.d.cts

@@ -250,6 +250,12 @@ export declare function toggleStamp(stamps: readonly StampKind[], stamp: StampKi
  * else adds it while there are fewer than `MAX_DOT_TEXTURES`. Empty means round dots.
  */
 export declare function toggleDotTexture(textures: readonly StampKind[], stamp: StampKind): StampKind[];
+/** Pressure profiles the "Brush a path" panel offers for `strokePath` (`pressure` undefined: even). */
+export declare const PATH_STROKE_TAPERS: ReadonlyArray<{
+    id: string;
+    label: string;
+    pressure?: readonly number[];
+}>;
 /** The sticker panel's sliders for the selected sticker. */
 /** The brush sliders of a picked stroke on a stroke layer (paths into its brush; see `updateStroke`). */
 export declare const STROKE_SLIDERS: readonly SliderControl[];

package/dist/paint-editor/ui.d.ts

@@ -250,6 +250,12 @@ export declare function toggleStamp(stamps: readonly StampKind[], stamp: StampKi
  * else adds it while there are fewer than `MAX_DOT_TEXTURES`. Empty means round dots.
  */
 export declare function toggleDotTexture(textures: readonly StampKind[], stamp: StampKind): StampKind[];
+/** Pressure profiles the "Brush a path" panel offers for `strokePath` (`pressure` undefined: even). */
+export declare const PATH_STROKE_TAPERS: ReadonlyArray<{
+    id: string;
+    label: string;
+    pressure?: readonly number[];
+}>;
 /** The sticker panel's sliders for the selected sticker. */
 /** The brush sliders of a picked stroke on a stroke layer (paths into its brush; see `updateStroke`). */
 export declare const STROKE_SLIDERS: readonly SliderControl[];

package/dist/tools/conformance.d.cts

@@ -0,0 +1,138 @@
+/**
+ * Conformance scenarios: a recorded sequence of tool calls with what each one returned, so
+ * another implementation of an editor (the Swift port, #533) can replay the same calls and check
+ * it gets the same results, documents and pixels. `@pixerate/conformance` holds the scenarios
+ * (`domains/<domain>/fixtures/*.json`); `scripts/record-conformance.mjs` records them from this
+ * core and a core test replays them.
+ *
+ * Results are compared after {@link normalizeConformanceValue}: ids an implementation generates
+ * (from a clock, say) become `@1`, `@2`, … in the order they are first seen, and binary payloads
+ * become `"<binary>"`, so neither the id format nor the PNG encoder is part of the contract. Ids
+ * that come from counters or names (`s1`, `pad1`, `ink-pen`) stay as they are. Every implementation applies the same rules (written
+ * out in the package README).
+ */
+import type { McpToolResult } from './registry.cjs';
+/** One tool call of a scenario and, once recorded, what it returned. */
+export interface ConformanceStep {
+    /** Tool name, unprefixed (`paint_stroke`). */
+    tool: string;
+    /** Arguments. A string `@n` is replaced by the id that `@n` stands for. */
+    arguments?: Record<string, unknown>;
+    /** Also compare the saved document after this call. */
+    document?: boolean;
+    /**
+     * Also compare the rendered pixels after this call (`paper: false` leaves the paper out;
+     * `tolerance` loosens what another implementation is held to for this snapshot).
+     */
+    pixels?: boolean | {
+        paper?: boolean;
+        tolerance?: {
+            maxDelta?: number;
+            meanDelta?: number;
+        };
+    };
+    /**
+     * Parts of the result left out of the comparison because they describe this implementation
+     * rather than the contract (the wet engine's backend): JSON pointers like `/backend`, where a
+     * `*` segment stands for every array element or object member.
+     */
+    ignore?: string[];
+    /** Recorded results, written by the recorder. */
+    expect?: ConformanceExpectation;
+}
+export interface ConformanceExpectation {
+    /** The normalized `structuredContent`, or `{ error: { code, message, details? } }` for a failed call. */
+    result: unknown;
+    isError?: true;
+    document?: unknown;
+    pixels?: ConformancePixels;
+}
+/** A pixel snapshot: the PNG next to the scenario plus how close another implementation must be. */
+export interface ConformancePixels {
+    /** PNG file, relative to the scenario file. */
+    file: string;
+    width: number;
+    height: number;
+    /** SHA-256 of the RGBA bytes, hex. This core matches it exactly. */
+    sha256: string;
+    /** Largest difference allowed in any channel of any pixel (0–255). */
+    maxDelta: number;
+    /** Largest mean difference allowed over all channels. */
+    meanDelta: number;
+}
+export interface ConformanceScenario {
+    $schema?: string;
+    /** Unique kebab-case id within the domain; also the file name. */
+    id: string;
+    description: string;
+    /** Host options, such as the canvas size. */
+    setup?: Record<string, unknown>;
+    steps: ConformanceStep[];
+    /** Reasons an implementation skips the whole scenario, by implementation (`swift`). */
+    skip?: Record<string, string>;
+}
+/** What a scenario runs against: a tool registry plus ways to read the document and pixels. */
+export interface ConformanceHost {
+    callTool(name: string, args: Record<string, unknown>): Promise<McpToolResult>;
+    document(): unknown;
+    pixels(options: {
+        paper?: boolean;
+    }): {
+        width: number;
+        height: number;
+        data: Uint8Array | Uint8ClampedArray;
+    };
+    /** Whether a string is an id this implementation generated in its own format (default: none). */
+    isGeneratedId?(value: string): boolean;
+    dispose?(): void;
+}
+/** What one step produced, normalized (pixels are raw RGBA for the caller to hash or encode). */
+export interface ConformanceStepOutput {
+    result: unknown;
+    isError: boolean;
+    document?: unknown;
+    pixels?: {
+        width: number;
+        height: number;
+        data: Uint8Array;
+    };
+}
+/** Maps real ids to `@n` placeholders and back, across a whole scenario. */
+export declare class ConformanceIds {
+    private readonly toPlaceholder;
+    private readonly fromPlaceholder;
+    /** The placeholder for `id`, assigning the next one when it is new. */
+    add(id: string): string;
+    placeholder(id: string): string | undefined;
+    /** `text` with every known id in it replaced by its placeholder (longest ids first). */
+    replaceWithin(text: string): string;
+    /** The real id a placeholder stands for. */
+    resolve(placeholder: string): string | undefined;
+}
+/** Strings at least this long made only of base64 characters are binary payloads. */
+export declare const CONFORMANCE_BINARY_MIN_LENGTH = 200;
+type IdTest = (value: string) => boolean;
+/**
+ * A value as scenarios store it:
+ * 1. Every string value or object key the implementation generated as an id (`isGeneratedId`) is
+ *    numbered `@1`, `@2`, … in the order first seen, walking depth first with object keys sorted
+ *    (each key before its value); the numbering carries across the scenario's steps.
+ * 2. Every known id in a string or object key, whole or inside a longer string (an error message),
+ *    becomes its placeholder; longer ids are replaced first.
+ * 3. A string starting with `data:`, or at least 200 characters of base64, becomes `"<binary>"`.
+ * 4. An ISO 8601 date-time string (`2026-11-04T01:06:52.993Z`) becomes `"<time>"`: clocks differ.
+ * 5. Object keys are sorted; `undefined` values are dropped (as JSON would).
+ */
+export declare function normalizeConformanceValue(value: unknown, ids: ConformanceIds, isGeneratedId?: IdTest): unknown;
+/** `value` without the members at `paths` (`/a/b`, `*` for every element or member). */
+export declare function omitConformancePaths(value: unknown, paths: readonly string[]): unknown;
+/** Arguments with each `@n` placeholder string replaced by the id it stands for. */
+export declare function resolveConformanceArguments(value: unknown, ids: ConformanceIds): unknown;
+/** The comparable part of a tool result: `structuredContent`, or the error's code, message and details. */
+export declare function conformanceResult(result: McpToolResult): {
+    value: unknown;
+    isError: boolean;
+};
+/** Runs a scenario's calls in order against a fresh host and returns what each step produced. */
+export declare function runConformanceScenario(scenario: ConformanceScenario, host: ConformanceHost): Promise<ConformanceStepOutput[]>;
+export {};

package/dist/tools/conformance.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Conformance scenarios: a recorded sequence of tool calls with what each one returned, so
+ * another implementation of an editor (the Swift port, #533) can replay the same calls and check
+ * it gets the same results, documents and pixels. `@pixerate/conformance` holds the scenarios
+ * (`domains/<domain>/fixtures/*.json`); `scripts/record-conformance.mjs` records them from this
+ * core and a core test replays them.
+ *
+ * Results are compared after {@link normalizeConformanceValue}: ids an implementation generates
+ * (from a clock, say) become `@1`, `@2`, … in the order they are first seen, and binary payloads
+ * become `"<binary>"`, so neither the id format nor the PNG encoder is part of the contract. Ids
+ * that come from counters or names (`s1`, `pad1`, `ink-pen`) stay as they are. Every implementation applies the same rules (written
+ * out in the package README).
+ */
+import type { McpToolResult } from './registry.js';
+/** One tool call of a scenario and, once recorded, what it returned. */
+export interface ConformanceStep {
+    /** Tool name, unprefixed (`paint_stroke`). */
+    tool: string;
+    /** Arguments. A string `@n` is replaced by the id that `@n` stands for. */
+    arguments?: Record<string, unknown>;
+    /** Also compare the saved document after this call. */
+    document?: boolean;
+    /**
+     * Also compare the rendered pixels after this call (`paper: false` leaves the paper out;
+     * `tolerance` loosens what another implementation is held to for this snapshot).
+     */
+    pixels?: boolean | {
+        paper?: boolean;
+        tolerance?: {
+            maxDelta?: number;
+            meanDelta?: number;
+        };
+    };
+    /**
+     * Parts of the result left out of the comparison because they describe this implementation
+     * rather than the contract (the wet engine's backend): JSON pointers like `/backend`, where a
+     * `*` segment stands for every array element or object member.
+     */
+    ignore?: string[];
+    /** Recorded results, written by the recorder. */
+    expect?: ConformanceExpectation;
+}
+export interface ConformanceExpectation {
+    /** The normalized `structuredContent`, or `{ error: { code, message, details? } }` for a failed call. */
+    result: unknown;
+    isError?: true;
+    document?: unknown;
+    pixels?: ConformancePixels;
+}
+/** A pixel snapshot: the PNG next to the scenario plus how close another implementation must be. */
+export interface ConformancePixels {
+    /** PNG file, relative to the scenario file. */
+    file: string;
+    width: number;
+    height: number;
+    /** SHA-256 of the RGBA bytes, hex. This core matches it exactly. */
+    sha256: string;
+    /** Largest difference allowed in any channel of any pixel (0–255). */
+    maxDelta: number;
+    /** Largest mean difference allowed over all channels. */
+    meanDelta: number;
+}
+export interface ConformanceScenario {
+    $schema?: string;
+    /** Unique kebab-case id within the domain; also the file name. */
+    id: string;
+    description: string;
+    /** Host options, such as the canvas size. */
+    setup?: Record<string, unknown>;
+    steps: ConformanceStep[];
+    /** Reasons an implementation skips the whole scenario, by implementation (`swift`). */
+    skip?: Record<string, string>;
+}
+/** What a scenario runs against: a tool registry plus ways to read the document and pixels. */
+export interface ConformanceHost {
+    callTool(name: string, args: Record<string, unknown>): Promise<McpToolResult>;
+    document(): unknown;
+    pixels(options: {
+        paper?: boolean;
+    }): {
+        width: number;
+        height: number;
+        data: Uint8Array | Uint8ClampedArray;
+    };
+    /** Whether a string is an id this implementation generated in its own format (default: none). */
+    isGeneratedId?(value: string): boolean;
+    dispose?(): void;
+}
+/** What one step produced, normalized (pixels are raw RGBA for the caller to hash or encode). */
+export interface ConformanceStepOutput {
+    result: unknown;
+    isError: boolean;
+    document?: unknown;
+    pixels?: {
+        width: number;
+        height: number;
+        data: Uint8Array;
+    };
+}
+/** Maps real ids to `@n` placeholders and back, across a whole scenario. */
+export declare class ConformanceIds {
+    private readonly toPlaceholder;
+    private readonly fromPlaceholder;
+    /** The placeholder for `id`, assigning the next one when it is new. */
+    add(id: string): string;
+    placeholder(id: string): string | undefined;
+    /** `text` with every known id in it replaced by its placeholder (longest ids first). */
+    replaceWithin(text: string): string;
+    /** The real id a placeholder stands for. */
+    resolve(placeholder: string): string | undefined;
+}
+/** Strings at least this long made only of base64 characters are binary payloads. */
+export declare const CONFORMANCE_BINARY_MIN_LENGTH = 200;
+type IdTest = (value: string) => boolean;
+/**
+ * A value as scenarios store it:
+ * 1. Every string value or object key the implementation generated as an id (`isGeneratedId`) is
+ *    numbered `@1`, `@2`, … in the order first seen, walking depth first with object keys sorted
+ *    (each key before its value); the numbering carries across the scenario's steps.
+ * 2. Every known id in a string or object key, whole or inside a longer string (an error message),
+ *    becomes its placeholder; longer ids are replaced first.
+ * 3. A string starting with `data:`, or at least 200 characters of base64, becomes `"<binary>"`.
+ * 4. An ISO 8601 date-time string (`2026-11-04T01:06:52.993Z`) becomes `"<time>"`: clocks differ.
+ * 5. Object keys are sorted; `undefined` values are dropped (as JSON would).
+ */
+export declare function normalizeConformanceValue(value: unknown, ids: ConformanceIds, isGeneratedId?: IdTest): unknown;
+/** `value` without the members at `paths` (`/a/b`, `*` for every element or member). */
+export declare function omitConformancePaths(value: unknown, paths: readonly string[]): unknown;
+/** Arguments with each `@n` placeholder string replaced by the id it stands for. */
+export declare function resolveConformanceArguments(value: unknown, ids: ConformanceIds): unknown;
+/** The comparable part of a tool result: `structuredContent`, or the error's code, message and details. */
+export declare function conformanceResult(result: McpToolResult): {
+    value: unknown;
+    isError: boolean;
+};
+/** Runs a scenario's calls in order against a fresh host and returns what each step produced. */
+export declare function runConformanceScenario(scenario: ConformanceScenario, host: ConformanceHost): Promise<ConformanceStepOutput[]>;
+export {};