@pixerate/editor 0.257.0 → 0.259.0

package/dist/brushes/contract.d.cts

@@ -0,0 +1,24 @@
+/**
+ * The brush module as language-neutral contracts (`@pixerate/conformance` `domains/brushes`), so
+ * another implementation (the Swift port) ships the same brushes: the brush JSON Schema, the
+ * built-in presets and the engine brushes they resolve to, the host profiles and what each host
+ * accepts, v1 migrations, the library file format, the library's agent tools and the brush editor
+ * sections. `scripts/export-contracts.mjs` writes them; a core test fails when the committed
+ * files differ from what this returns.
+ *
+ * Everything here is data from this module's own functions; nothing depends on the package
+ * version, so a release does not change the files.
+ */
+import type { JsonSchema } from '../tools/schema.cjs';
+/** Bumped when a contract file changes shape (not when its data changes). */
+export declare const BRUSH_CONTRACT_FORMAT_VERSION = 1;
+/** JSON Schema of a host profile (`profiles.json`). */
+export declare const BRUSH_PROFILE_JSON_SCHEMA: JsonSchema;
+/** JSON Schema of a brush library file (`pixerate-brushes` version 2). */
+export declare const BRUSH_LIBRARY_FILE_JSON_SCHEMA: JsonSchema;
+/**
+ * Every brush contract file, by its path under `domains/brushes/` (plain JSON values). The
+ * presets and their resolutions, checks and migrations are what an implementation must reproduce;
+ * the schemas and tools are what it must accept and offer.
+ */
+export declare function brushContracts(): Record<string, unknown>;

package/dist/brushes/contract.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The brush module as language-neutral contracts (`@pixerate/conformance` `domains/brushes`), so
+ * another implementation (the Swift port) ships the same brushes: the brush JSON Schema, the
+ * built-in presets and the engine brushes they resolve to, the host profiles and what each host
+ * accepts, v1 migrations, the library file format, the library's agent tools and the brush editor
+ * sections. `scripts/export-contracts.mjs` writes them; a core test fails when the committed
+ * files differ from what this returns.
+ *
+ * Everything here is data from this module's own functions; nothing depends on the package
+ * version, so a release does not change the files.
+ */
+import type { JsonSchema } from '../tools/schema.js';
+/** Bumped when a contract file changes shape (not when its data changes). */
+export declare const BRUSH_CONTRACT_FORMAT_VERSION = 1;
+/** JSON Schema of a host profile (`profiles.json`). */
+export declare const BRUSH_PROFILE_JSON_SCHEMA: JsonSchema;
+/** JSON Schema of a brush library file (`pixerate-brushes` version 2). */
+export declare const BRUSH_LIBRARY_FILE_JSON_SCHEMA: JsonSchema;
+/**
+ * Every brush contract file, by its path under `domains/brushes/` (plain JSON values). The
+ * presets and their resolutions, checks and migrations are what an implementation must reproduce;
+ * the schemas and tools are what it must accept and offer.
+ */
+export declare function brushContracts(): Record<string, unknown>;

package/dist/brushes/index.cjs

@@ -55,6 +55,9 @@ require('../chunk-A2IS7EHE.cjs');
 
 
 
+
+
+
 
 
 
@@ -280,6 +283,118 @@ function brushLibraryGroups(entries, filter = {}) {
   return [...groups.values()].sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id));
 }
 
+// src/brushes/contract.ts
+var BRUSH_CONTRACT_FORMAT_VERSION = 1;
+var SUPPORT = { type: "string", enum: ["full", "ignored", "none"], description: "full: rendered; ignored: accepted, painted without it (a warning); none: refused (an error)." };
+var BRUSH_PROFILE_JSON_SCHEMA = {
+  type: "object",
+  description: "What a host can render (`BrushHostProfile`).",
+  properties: {
+    id: { type: "string", description: "paint, image, canvas, vector\u2026" },
+    name: { type: "string", description: "Display name, used in messages." },
+    kinds: { type: "array", items: { type: "string", enum: [..._chunkRSIKDWOPcjs.BRUSH_KINDS] }, description: "Brush kinds it has." },
+    tools: { type: "array", items: { type: "string", enum: [..._chunkRSIKDWOPcjs.BRUSH_TOOLS] }, description: "Tools it has (kind tool)." },
+    tipShapes: { type: "array", items: { type: "string", enum: [..._chunkRSIKDWOPcjs.BRUSH_TIP_SHAPES] }, description: "Tip shapes it renders." },
+    marks: { type: "array", items: { type: "string", enum: [..._chunkRSIKDWOPcjs.BRUSH_MARKS_KINDS] }, description: "Marks kinds it renders." },
+    surfaces: { type: "array", items: { type: "string", enum: [..._chunkRSIKDWOPcjs.BRUSH_SURFACES] }, description: "Surfaces it renders." },
+    exchange: { ...SUPPORT, description: "Picking paint up and mixing it in." },
+    reservoir: { ...SUPPORT, description: "The Mixer Brush reservoir." },
+    grain: { ...SUPPORT, description: "Paper grain response." },
+    light: { ...SUPPORT, description: "Light paint." },
+    motion: { ...SUPPORT, description: "Motion after painting." },
+    colours: { type: "array", items: { type: "string", enum: ["solid", "dual", "gradient", "effect"] }, description: "Colour kinds a default colour may be." },
+    velocity: { ...SUPPORT, description: "Velocity dynamics." },
+    tilt: { ...SUPPORT, description: "Tilt dynamics." }
+  },
+  required: ["id", "name", "kinds", "tools", "tipShapes", "marks", "surfaces", "exchange", "reservoir", "grain", "light", "motion", "colours", "velocity", "tilt"],
+  additionalProperties: false
+};
+var BRUSH_LIBRARY_FILE_JSON_SCHEMA = {
+  type: "object",
+  description: "A brush library file, as export_brushes writes it. Readers also accept version 1 files (flat engine brushes, migrated) and a bare array of brushes.",
+  properties: {
+    format: { type: "string", const: "pixerate-brushes", description: 'Always "pixerate-brushes".' },
+    version: { type: "integer", const: 2, description: "Always 2." },
+    brushes: { type: "array", items: { $ref: "brush.schema.json" }, description: "The brushes, each a facet brush (brush.schema.json)." }
+  },
+  required: ["format", "version", "brushes"],
+  additionalProperties: false
+};
+function migrationInputs() {
+  const pick = (id) => _chunkRSIKDWOPcjs.brushToJSON.call(void 0, _chunkRSIKDWOPcjs.BUILTIN_BRUSHES.find((b) => b.id === id));
+  return [
+    { id: "plain", name: "Plain" },
+    pick("pencil-6b"),
+    { ...pick("soft-pastel"), id: "my-pastel", name: "My pastel", category: "custom", grain: 0.2, tip: { ...pick("soft-pastel").tip, size: 50 } },
+    pick("mixer-brush"),
+    pick("watercolor-wash"),
+    pick("impasto-brush"),
+    pick("hair-strands"),
+    pick("bristle-round"),
+    pick("sticker-stars"),
+    pick("rainbow-marker"),
+    pick("blender"),
+    pick("add-water"),
+    pick("spray-can"),
+    // Fields an engine never reads are dropped on migration.
+    { ...pick("ink-pen"), id: "ink-with-mixer", name: "Ink with mixer settings", mixer: { wet: 0.9, load: 0.1, mix: 0.9, loadEachStroke: false, cleanEachStroke: false, mixing: "pigment" } }
+  ];
+}
+function editorSectionFixtures() {
+  const ids = ["highlighter", "chalk", "watercolor-wash", "hair-strands", "mixer-brush", "blender", "spray-can"];
+  return ids.flatMap(
+    (id) => Object.keys(_chunkRSIKDWOPcjs.BRUSH_HOST_PROFILES).map((host) => {
+      const brush = _chunkRSIKDWOPcjs.BRUSH_PRESETS.find((b) => b.id === id);
+      return { brush: id, host, sections: brushEditorSections(brush, _chunkRSIKDWOPcjs.BRUSH_HOST_PROFILES[host]) };
+    })
+  );
+}
+function toolDefinitions() {
+  const library = _chunkRSIKDWOPcjs.createBrushLibrary.call(void 0, );
+  const toolsFor = (host) => _chunkMQGQTKVWcjs.createBrushLibraryTools.call(void 0, library, { profile: _chunkRSIKDWOPcjs.BRUSH_HOST_PROFILES[host], renderPreview: () => ({ data: "", mimeType: "image/png" }) });
+  return {
+    tools: toolsFor("paint").map((t) => ({ name: t.name, title: t.title, description: t.description, inputSchema: t.inputSchema, annotations: t.annotations })),
+    hosts: Object.fromEntries(Object.keys(_chunkRSIKDWOPcjs.BRUSH_HOST_PROFILES).map((host) => [host, toolsFor(host).map((t) => t.name)]))
+  };
+}
+function brushContracts() {
+  const presets = _chunkRSIKDWOPcjs.BRUSH_PRESETS.map((b) => JSON.parse(JSON.stringify(b)));
+  const resolved = _chunkRSIKDWOPcjs.BRUSH_PRESETS.map((b) => ({ id: b.id, engine: _chunkRSIKDWOPcjs.resolveEngine.call(void 0, b), category: _chunkRSIKDWOPcjs.resolveCategory.call(void 0, b), brush: _chunkRSIKDWOPcjs.brushToJSON.call(void 0, _chunkRSIKDWOPcjs.resolveBrush.call(void 0, b)) }));
+  const profiles = Object.values(_chunkRSIKDWOPcjs.BRUSH_HOST_PROFILES);
+  const checks = _chunkRSIKDWOPcjs.BRUSH_PRESETS.map((b) => ({
+    id: b.id,
+    hosts: Object.fromEntries(profiles.map((p) => {
+      const c = _chunkRSIKDWOPcjs.checkBrush.call(void 0, b, p);
+      return [p.id, { ok: c.ok, issues: c.issues.map(({ facet, severity }) => ({ facet, severity })) }];
+    }))
+  }));
+  const migrations = migrationInputs().map((input) => ({ input, output: _chunkRSIKDWOPcjs.migrateBrushV1.call(void 0, input), resolved: _chunkRSIKDWOPcjs.brushToJSON.call(void 0, _chunkRSIKDWOPcjs.resolveBrush.call(void 0, _chunkRSIKDWOPcjs.migrateBrushV1.call(void 0, input))), engine: _chunkRSIKDWOPcjs.normalizePaintBrush.call(void 0, input).engine }));
+  const files = {
+    "brush.schema.json": { $schema: "https://json-schema.org/draft/2020-12/schema", $id: "brush.schema.json", ..._chunkRSIKDWOPcjs.BRUSH_JSON_SCHEMA },
+    "profile.schema.json": { $schema: "https://json-schema.org/draft/2020-12/schema", $id: "profile.schema.json", ...BRUSH_PROFILE_JSON_SCHEMA },
+    "library-file.schema.json": { $schema: "https://json-schema.org/draft/2020-12/schema", $id: "library-file.schema.json", ...BRUSH_LIBRARY_FILE_JSON_SCHEMA },
+    "presets.json": presets,
+    "resolved.json": resolved,
+    "profiles.json": profiles,
+    "checks.json": checks,
+    "migrations.json": migrations,
+    "tools.json": toolDefinitions(),
+    "editor-sections.json": editorSectionFixtures()
+  };
+  files["manifest.json"] = {
+    domain: "brushes",
+    formatVersion: BRUSH_CONTRACT_FORMAT_VERSION,
+    limits: { maxPalette: _chunkRSIKDWOPcjs.MAX_BRUSH_PALETTE },
+    counts: { presets: presets.length, profiles: profiles.length, migrations: migrations.length, editorSections: files["editor-sections.json"].length },
+    files: Object.keys(files).sort()
+  };
+  return files;
+}
+
+
+
+
+
 
 
 
@@ -322,4 +437,4 @@ function brushLibraryGroups(entries, filter = {}) {
 
 
 
-exports.BRUSH_FACET_SCHEMAS = _chunkRSIKDWOPcjs.BRUSH_FACET_SCHEMAS; exports.BRUSH_HOST_PROFILES = _chunkRSIKDWOPcjs.BRUSH_HOST_PROFILES; exports.BRUSH_JSON_SCHEMA = _chunkRSIKDWOPcjs.BRUSH_JSON_SCHEMA; exports.BRUSH_KINDS = _chunkRSIKDWOPcjs.BRUSH_KINDS; exports.BRUSH_MARKS_KINDS = _chunkRSIKDWOPcjs.BRUSH_MARKS_KINDS; exports.BRUSH_MEDIA = _chunkRSIKDWOPcjs.BRUSH_MEDIA; exports.BRUSH_PATCH_PROPERTIES = _chunkMQGQTKVWcjs.BRUSH_PATCH_PROPERTIES; exports.BRUSH_PRESETS = _chunkRSIKDWOPcjs.BRUSH_PRESETS; exports.BRUSH_SURFACES = _chunkRSIKDWOPcjs.BRUSH_SURFACES; exports.BRUSH_TIP_SHAPES = _chunkRSIKDWOPcjs.BRUSH_TIP_SHAPES; exports.BRUSH_TOOLS = _chunkRSIKDWOPcjs.BRUSH_TOOLS; exports.BRUSH_UNSET_PROPERTY = _chunkMQGQTKVWcjs.BRUSH_UNSET_PROPERTY; exports.BRUSH_WORD = _chunkRSIKDWOPcjs.BRUSH_WORD; exports.BrushLibraryError = _chunkRSIKDWOPcjs.BrushLibraryError; exports.CANVAS_PROFILE = _chunkRSIKDWOPcjs.CANVAS_PROFILE; exports.IMAGE_PROFILE = _chunkRSIKDWOPcjs.IMAGE_PROFILE; exports.MAX_BRUSH_PALETTE = _chunkRSIKDWOPcjs.MAX_BRUSH_PALETTE; exports.PAINT_PROFILE = _chunkRSIKDWOPcjs.PAINT_PROFILE; exports.UNSETTABLE_BRUSH_FACETS = _chunkMQGQTKVWcjs.UNSETTABLE_BRUSH_FACETS; exports.VECTOR_PROFILE = _chunkRSIKDWOPcjs.VECTOR_PROFILE; exports.WET_BRUSH_TOOLS = _chunkRSIKDWOPcjs.WET_BRUSH_TOOLS; exports.brushColourHex = _chunkLRTR4ASZcjs.brushColourHex; exports.brushColourKind = _chunkRSIKDWOPcjs.brushColourKind; exports.brushEditorSections = brushEditorSections; exports.brushLibraryGroups = brushLibraryGroups; exports.changedBrushPaths = _chunkMQGQTKVWcjs.changedBrushPaths; exports.checkBrush = _chunkRSIKDWOPcjs.checkBrush; exports.createBrushLibrary = _chunkRSIKDWOPcjs.createBrushLibrary; exports.createBrushLibraryToolProvider = _chunkMQGQTKVWcjs.createBrushLibraryToolProvider; exports.createBrushLibraryTools = _chunkMQGQTKVWcjs.createBrushLibraryTools; exports.degrade = _chunkRSIKDWOPcjs.degrade; exports.listPresets = _chunkRSIKDWOPcjs.listPresets; exports.mergeBrushPatch = _chunkMQGQTKVWcjs.mergeBrushPatch; exports.migrateBrushV1 = _chunkRSIKDWOPcjs.migrateBrushV1; exports.normalizeBrushSpec = _chunkRSIKDWOPcjs.normalizeBrushSpec; exports.parseBrushLibrary = _chunkRSIKDWOPcjs.parseBrushLibrary2; exports.resolveBrush = _chunkRSIKDWOPcjs.resolveBrush; exports.resolveCategory = _chunkRSIKDWOPcjs.resolveCategory; exports.resolveEngine = _chunkRSIKDWOPcjs.resolveEngine; exports.resolveWetMedium = _chunkRSIKDWOPcjs.resolveWetMedium; exports.setBrushEditorValue = setBrushEditorValue; exports.snapshotBrushLibrary = _chunkRSIKDWOPcjs.snapshotBrushLibrary;
+exports.BRUSH_CONTRACT_FORMAT_VERSION = BRUSH_CONTRACT_FORMAT_VERSION; exports.BRUSH_FACET_SCHEMAS = _chunkRSIKDWOPcjs.BRUSH_FACET_SCHEMAS; exports.BRUSH_HOST_PROFILES = _chunkRSIKDWOPcjs.BRUSH_HOST_PROFILES; exports.BRUSH_JSON_SCHEMA = _chunkRSIKDWOPcjs.BRUSH_JSON_SCHEMA; exports.BRUSH_KINDS = _chunkRSIKDWOPcjs.BRUSH_KINDS; exports.BRUSH_LIBRARY_FILE_JSON_SCHEMA = BRUSH_LIBRARY_FILE_JSON_SCHEMA; exports.BRUSH_MARKS_KINDS = _chunkRSIKDWOPcjs.BRUSH_MARKS_KINDS; exports.BRUSH_MEDIA = _chunkRSIKDWOPcjs.BRUSH_MEDIA; exports.BRUSH_PATCH_PROPERTIES = _chunkMQGQTKVWcjs.BRUSH_PATCH_PROPERTIES; exports.BRUSH_PRESETS = _chunkRSIKDWOPcjs.BRUSH_PRESETS; exports.BRUSH_PROFILE_JSON_SCHEMA = BRUSH_PROFILE_JSON_SCHEMA; exports.BRUSH_SURFACES = _chunkRSIKDWOPcjs.BRUSH_SURFACES; exports.BRUSH_TIP_SHAPES = _chunkRSIKDWOPcjs.BRUSH_TIP_SHAPES; exports.BRUSH_TOOLS = _chunkRSIKDWOPcjs.BRUSH_TOOLS; exports.BRUSH_UNSET_PROPERTY = _chunkMQGQTKVWcjs.BRUSH_UNSET_PROPERTY; exports.BRUSH_WORD = _chunkRSIKDWOPcjs.BRUSH_WORD; exports.BrushLibraryError = _chunkRSIKDWOPcjs.BrushLibraryError; exports.CANVAS_PROFILE = _chunkRSIKDWOPcjs.CANVAS_PROFILE; exports.IMAGE_PROFILE = _chunkRSIKDWOPcjs.IMAGE_PROFILE; exports.MAX_BRUSH_PALETTE = _chunkRSIKDWOPcjs.MAX_BRUSH_PALETTE; exports.PAINT_PROFILE = _chunkRSIKDWOPcjs.PAINT_PROFILE; exports.UNSETTABLE_BRUSH_FACETS = _chunkMQGQTKVWcjs.UNSETTABLE_BRUSH_FACETS; exports.VECTOR_PROFILE = _chunkRSIKDWOPcjs.VECTOR_PROFILE; exports.WET_BRUSH_TOOLS = _chunkRSIKDWOPcjs.WET_BRUSH_TOOLS; exports.brushColourHex = _chunkLRTR4ASZcjs.brushColourHex; exports.brushColourKind = _chunkRSIKDWOPcjs.brushColourKind; exports.brushContracts = brushContracts; exports.brushEditorSections = brushEditorSections; exports.brushLibraryGroups = brushLibraryGroups; exports.changedBrushPaths = _chunkMQGQTKVWcjs.changedBrushPaths; exports.checkBrush = _chunkRSIKDWOPcjs.checkBrush; exports.createBrushLibrary = _chunkRSIKDWOPcjs.createBrushLibrary; exports.createBrushLibraryToolProvider = _chunkMQGQTKVWcjs.createBrushLibraryToolProvider; exports.createBrushLibraryTools = _chunkMQGQTKVWcjs.createBrushLibraryTools; exports.degrade = _chunkRSIKDWOPcjs.degrade; exports.listPresets = _chunkRSIKDWOPcjs.listPresets; exports.mergeBrushPatch = _chunkMQGQTKVWcjs.mergeBrushPatch; exports.migrateBrushV1 = _chunkRSIKDWOPcjs.migrateBrushV1; exports.normalizeBrushSpec = _chunkRSIKDWOPcjs.normalizeBrushSpec; exports.parseBrushLibrary = _chunkRSIKDWOPcjs.parseBrushLibrary2; exports.resolveBrush = _chunkRSIKDWOPcjs.resolveBrush; exports.resolveCategory = _chunkRSIKDWOPcjs.resolveCategory; exports.resolveEngine = _chunkRSIKDWOPcjs.resolveEngine; exports.resolveWetMedium = _chunkRSIKDWOPcjs.resolveWetMedium; exports.setBrushEditorValue = setBrushEditorValue; exports.snapshotBrushLibrary = _chunkRSIKDWOPcjs.snapshotBrushLibrary;

package/dist/brushes/index.d.cts

@@ -15,6 +15,7 @@ export { resolveBrush, resolveCategory, resolveEngine, resolveWetMedium, type Re
 export { migrateBrushV1 } from './migrate.cjs';
 export { BRUSH_PRESETS } from './presets.cjs';
 export { brushColourHex } from './colour.cjs';
+export { BRUSH_CONTRACT_FORMAT_VERSION, BRUSH_LIBRARY_FILE_JSON_SCHEMA, BRUSH_PROFILE_JSON_SCHEMA, brushContracts } from './contract.cjs';
 export { BRUSH_HOST_PROFILES, brushColourKind, CANVAS_PROFILE, checkBrush, degrade, IMAGE_PROFILE, listPresets, PAINT_PROFILE, VECTOR_PROFILE, type BrushCheck, type BrushColourKind, type BrushHostProfile, type BrushIssue, type BrushSupport, type DegradedBrush } from './profiles.cjs';
 export { BrushLibraryError, createBrushLibrary, parseBrushLibrary, snapshotBrushLibrary, type BrushFilter, type BrushLibrary, type BrushLibraryEntry, type BrushLibraryErrorCode, type BrushLibraryFile, type BrushLibrarySnapshot, type BrushLibraryOptions, type ImportBrushesResult, type SaveBrushResult, } from './library.cjs';
 export { BRUSH_PATCH_PROPERTIES, BRUSH_UNSET_PROPERTY, changedBrushPaths, mergeBrushPatch, UNSETTABLE_BRUSH_FACETS, type BrushPatch, type UnsettableBrushFacet } from './patch.cjs';

package/dist/brushes/index.d.ts

@@ -15,6 +15,7 @@ export { resolveBrush, resolveCategory, resolveEngine, resolveWetMedium, type Re
 export { migrateBrushV1 } from './migrate.js';
 export { BRUSH_PRESETS } from './presets.js';
 export { brushColourHex } from './colour.js';
+export { BRUSH_CONTRACT_FORMAT_VERSION, BRUSH_LIBRARY_FILE_JSON_SCHEMA, BRUSH_PROFILE_JSON_SCHEMA, brushContracts } from './contract.js';
 export { BRUSH_HOST_PROFILES, brushColourKind, CANVAS_PROFILE, checkBrush, degrade, IMAGE_PROFILE, listPresets, PAINT_PROFILE, VECTOR_PROFILE, type BrushCheck, type BrushColourKind, type BrushHostProfile, type BrushIssue, type BrushSupport, type DegradedBrush } from './profiles.js';
 export { BrushLibraryError, createBrushLibrary, parseBrushLibrary, snapshotBrushLibrary, type BrushFilter, type BrushLibrary, type BrushLibraryEntry, type BrushLibraryErrorCode, type BrushLibraryFile, type BrushLibrarySnapshot, type BrushLibraryOptions, type ImportBrushesResult, type SaveBrushResult, } from './library.js';
 export { BRUSH_PATCH_PROPERTIES, BRUSH_UNSET_PROPERTY, changedBrushPaths, mergeBrushPatch, UNSETTABLE_BRUSH_FACETS, type BrushPatch, type UnsettableBrushFacet } from './patch.js';

package/dist/brushes/index.js

@@ -28,6 +28,7 @@ import {
   BRUSH_TIP_SHAPES,
   BRUSH_TOOLS,
   BRUSH_WORD,
+  BUILTIN_BRUSHES,
   BrushLibraryError,
   CANVAS_PROFILE,
   DOT_ROTATIONS,
@@ -45,6 +46,7 @@ import {
   WET_BRUSH_TOOLS,
   WET_MEDIA,
   brushColourKind,
+  brushToJSON,
   checkBrush,
   createBrushLibrary,
   degrade,
@@ -52,6 +54,7 @@ import {
   listPresets,
   migrateBrushV1,
   normalizeBrushSpec,
+  normalizePaintBrush,
   parseBrushLibrary2 as parseBrushLibrary,
   resolveBrush,
   resolveCategory,
@@ -279,15 +282,126 @@ function brushLibraryGroups(entries, filter = {}) {
   const order = ["dry", "ink", "paint", "spray", "other", "tools"];
   return [...groups.values()].sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id));
 }
+
+// src/brushes/contract.ts
+var BRUSH_CONTRACT_FORMAT_VERSION = 1;
+var SUPPORT = { type: "string", enum: ["full", "ignored", "none"], description: "full: rendered; ignored: accepted, painted without it (a warning); none: refused (an error)." };
+var BRUSH_PROFILE_JSON_SCHEMA = {
+  type: "object",
+  description: "What a host can render (`BrushHostProfile`).",
+  properties: {
+    id: { type: "string", description: "paint, image, canvas, vector\u2026" },
+    name: { type: "string", description: "Display name, used in messages." },
+    kinds: { type: "array", items: { type: "string", enum: [...BRUSH_KINDS] }, description: "Brush kinds it has." },
+    tools: { type: "array", items: { type: "string", enum: [...BRUSH_TOOLS] }, description: "Tools it has (kind tool)." },
+    tipShapes: { type: "array", items: { type: "string", enum: [...BRUSH_TIP_SHAPES] }, description: "Tip shapes it renders." },
+    marks: { type: "array", items: { type: "string", enum: [...BRUSH_MARKS_KINDS] }, description: "Marks kinds it renders." },
+    surfaces: { type: "array", items: { type: "string", enum: [...BRUSH_SURFACES] }, description: "Surfaces it renders." },
+    exchange: { ...SUPPORT, description: "Picking paint up and mixing it in." },
+    reservoir: { ...SUPPORT, description: "The Mixer Brush reservoir." },
+    grain: { ...SUPPORT, description: "Paper grain response." },
+    light: { ...SUPPORT, description: "Light paint." },
+    motion: { ...SUPPORT, description: "Motion after painting." },
+    colours: { type: "array", items: { type: "string", enum: ["solid", "dual", "gradient", "effect"] }, description: "Colour kinds a default colour may be." },
+    velocity: { ...SUPPORT, description: "Velocity dynamics." },
+    tilt: { ...SUPPORT, description: "Tilt dynamics." }
+  },
+  required: ["id", "name", "kinds", "tools", "tipShapes", "marks", "surfaces", "exchange", "reservoir", "grain", "light", "motion", "colours", "velocity", "tilt"],
+  additionalProperties: false
+};
+var BRUSH_LIBRARY_FILE_JSON_SCHEMA = {
+  type: "object",
+  description: "A brush library file, as export_brushes writes it. Readers also accept version 1 files (flat engine brushes, migrated) and a bare array of brushes.",
+  properties: {
+    format: { type: "string", const: "pixerate-brushes", description: 'Always "pixerate-brushes".' },
+    version: { type: "integer", const: 2, description: "Always 2." },
+    brushes: { type: "array", items: { $ref: "brush.schema.json" }, description: "The brushes, each a facet brush (brush.schema.json)." }
+  },
+  required: ["format", "version", "brushes"],
+  additionalProperties: false
+};
+function migrationInputs() {
+  const pick = (id) => brushToJSON(BUILTIN_BRUSHES.find((b) => b.id === id));
+  return [
+    { id: "plain", name: "Plain" },
+    pick("pencil-6b"),
+    { ...pick("soft-pastel"), id: "my-pastel", name: "My pastel", category: "custom", grain: 0.2, tip: { ...pick("soft-pastel").tip, size: 50 } },
+    pick("mixer-brush"),
+    pick("watercolor-wash"),
+    pick("impasto-brush"),
+    pick("hair-strands"),
+    pick("bristle-round"),
+    pick("sticker-stars"),
+    pick("rainbow-marker"),
+    pick("blender"),
+    pick("add-water"),
+    pick("spray-can"),
+    // Fields an engine never reads are dropped on migration.
+    { ...pick("ink-pen"), id: "ink-with-mixer", name: "Ink with mixer settings", mixer: { wet: 0.9, load: 0.1, mix: 0.9, loadEachStroke: false, cleanEachStroke: false, mixing: "pigment" } }
+  ];
+}
+function editorSectionFixtures() {
+  const ids = ["highlighter", "chalk", "watercolor-wash", "hair-strands", "mixer-brush", "blender", "spray-can"];
+  return ids.flatMap(
+    (id) => Object.keys(BRUSH_HOST_PROFILES).map((host) => {
+      const brush = BRUSH_PRESETS.find((b) => b.id === id);
+      return { brush: id, host, sections: brushEditorSections(brush, BRUSH_HOST_PROFILES[host]) };
+    })
+  );
+}
+function toolDefinitions() {
+  const library = createBrushLibrary();
+  const toolsFor = (host) => createBrushLibraryTools(library, { profile: BRUSH_HOST_PROFILES[host], renderPreview: () => ({ data: "", mimeType: "image/png" }) });
+  return {
+    tools: toolsFor("paint").map((t) => ({ name: t.name, title: t.title, description: t.description, inputSchema: t.inputSchema, annotations: t.annotations })),
+    hosts: Object.fromEntries(Object.keys(BRUSH_HOST_PROFILES).map((host) => [host, toolsFor(host).map((t) => t.name)]))
+  };
+}
+function brushContracts() {
+  const presets = BRUSH_PRESETS.map((b) => JSON.parse(JSON.stringify(b)));
+  const resolved = BRUSH_PRESETS.map((b) => ({ id: b.id, engine: resolveEngine(b), category: resolveCategory(b), brush: brushToJSON(resolveBrush(b)) }));
+  const profiles = Object.values(BRUSH_HOST_PROFILES);
+  const checks = BRUSH_PRESETS.map((b) => ({
+    id: b.id,
+    hosts: Object.fromEntries(profiles.map((p) => {
+      const c = checkBrush(b, p);
+      return [p.id, { ok: c.ok, issues: c.issues.map(({ facet, severity }) => ({ facet, severity })) }];
+    }))
+  }));
+  const migrations = migrationInputs().map((input) => ({ input, output: migrateBrushV1(input), resolved: brushToJSON(resolveBrush(migrateBrushV1(input))), engine: normalizePaintBrush(input).engine }));
+  const files = {
+    "brush.schema.json": { $schema: "https://json-schema.org/draft/2020-12/schema", $id: "brush.schema.json", ...BRUSH_JSON_SCHEMA },
+    "profile.schema.json": { $schema: "https://json-schema.org/draft/2020-12/schema", $id: "profile.schema.json", ...BRUSH_PROFILE_JSON_SCHEMA },
+    "library-file.schema.json": { $schema: "https://json-schema.org/draft/2020-12/schema", $id: "library-file.schema.json", ...BRUSH_LIBRARY_FILE_JSON_SCHEMA },
+    "presets.json": presets,
+    "resolved.json": resolved,
+    "profiles.json": profiles,
+    "checks.json": checks,
+    "migrations.json": migrations,
+    "tools.json": toolDefinitions(),
+    "editor-sections.json": editorSectionFixtures()
+  };
+  files["manifest.json"] = {
+    domain: "brushes",
+    formatVersion: BRUSH_CONTRACT_FORMAT_VERSION,
+    limits: { maxPalette: MAX_BRUSH_PALETTE },
+    counts: { presets: presets.length, profiles: profiles.length, migrations: migrations.length, editorSections: files["editor-sections.json"].length },
+    files: Object.keys(files).sort()
+  };
+  return files;
+}
 export {
+  BRUSH_CONTRACT_FORMAT_VERSION,
   BRUSH_FACET_SCHEMAS,
   BRUSH_HOST_PROFILES,
   BRUSH_JSON_SCHEMA,
   BRUSH_KINDS,
+  BRUSH_LIBRARY_FILE_JSON_SCHEMA,
   BRUSH_MARKS_KINDS,
   BRUSH_MEDIA,
   BRUSH_PATCH_PROPERTIES,
   BRUSH_PRESETS,
+  BRUSH_PROFILE_JSON_SCHEMA,
   BRUSH_SURFACES,
   BRUSH_TIP_SHAPES,
   BRUSH_TOOLS,
@@ -303,6 +417,7 @@ export {
   WET_BRUSH_TOOLS,
   brushColourHex,
   brushColourKind,
+  brushContracts,
   brushEditorSections,
   brushLibraryGroups,
   changedBrushPaths,

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

@@ -178,3 +178,41 @@ export declare function paintProposalGhost(proposal: PaintProposal): {
     height: number;
     data: Uint8ClampedArray;
 } | null;
+/** A stroke an agent is painting live, drawn over the canvas until it is painted for real. */
+export interface PaintAgentStroke {
+    id: string;
+    /** Who paints it (`agent:<id>`). */
+    origin: string;
+    /** Path in document pixels. */
+    points: readonly {
+        x: number;
+        y: number;
+    }[];
+    /** #rrggbb */
+    color: string;
+    /** Line width in document pixels. */
+    size: number;
+    /** 0..1 (default 0.6). */
+    opacity?: number;
+}
+export interface PaintAgentStrokesState {
+    strokes: readonly PaintAgentStroke[];
+}
+/** Agent strokes in progress, for `PaintCanvas` (`agentStrokes`) to draw while the user's pen is down. */
+export interface PaintAgentStrokes {
+    getState(): PaintAgentStrokesState;
+    subscribe(listener: (state: PaintAgentStrokesState) => void): () => void;
+    /** Adds or replaces a stroke (by id). */
+    set(stroke: PaintAgentStroke): void;
+    remove(id: string): void;
+    /** Removes every stroke (or those of one origin). */
+    clear(origin?: string): void;
+}
+/**
+ * Live agent strokes: an agent painting along with the user draws its companion strokes here
+ * while the user's stroke is in progress (the editor can't paint two strokes at once), then paints
+ * them for real when the user lifts the pen. `PaintCanvas` draws them as soft lines over the canvas.
+ */
+export declare function createPaintAgentStrokes(): PaintAgentStrokes;
+/** An SVG `points` attribute for a live agent stroke. */
+export declare function paintAgentStrokePoints(stroke: PaintAgentStroke): string;

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

@@ -178,3 +178,41 @@ export declare function paintProposalGhost(proposal: PaintProposal): {
     height: number;
     data: Uint8ClampedArray;
 } | null;
+/** A stroke an agent is painting live, drawn over the canvas until it is painted for real. */
+export interface PaintAgentStroke {
+    id: string;
+    /** Who paints it (`agent:<id>`). */
+    origin: string;
+    /** Path in document pixels. */
+    points: readonly {
+        x: number;
+        y: number;
+    }[];
+    /** #rrggbb */
+    color: string;
+    /** Line width in document pixels. */
+    size: number;
+    /** 0..1 (default 0.6). */
+    opacity?: number;
+}
+export interface PaintAgentStrokesState {
+    strokes: readonly PaintAgentStroke[];
+}
+/** Agent strokes in progress, for `PaintCanvas` (`agentStrokes`) to draw while the user's pen is down. */
+export interface PaintAgentStrokes {
+    getState(): PaintAgentStrokesState;
+    subscribe(listener: (state: PaintAgentStrokesState) => void): () => void;
+    /** Adds or replaces a stroke (by id). */
+    set(stroke: PaintAgentStroke): void;
+    remove(id: string): void;
+    /** Removes every stroke (or those of one origin). */
+    clear(origin?: string): void;
+}
+/**
+ * Live agent strokes: an agent painting along with the user draws its companion strokes here
+ * while the user's stroke is in progress (the editor can't paint two strokes at once), then paints
+ * them for real when the user lifts the pen. `PaintCanvas` draws them as soft lines over the canvas.
+ */
+export declare function createPaintAgentStrokes(): PaintAgentStrokes;
+/** An SVG `points` attribute for a live agent stroke. */
+export declare function paintAgentStrokePoints(stroke: PaintAgentStroke): string;

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

@@ -204,6 +204,21 @@ export interface PaintLayerInfo {
     /** How many live layer effects (glows, shadows, strokes…) it has, when any (`getLayerEffects`). */
     effects?: number;
 }
+/** A live stroke as it is painted (`onStrokeSample`), for agents that paint along with the user. */
+export interface PaintStrokeSample {
+    /** `begin`: the pen went down. `points`: new samples. `end`: the stroke was recorded. `cancel`: it was abandoned. */
+    phase: 'begin' | 'points' | 'end' | 'cancel';
+    layerId: string;
+    brush: PaintBrush;
+    /** #rrggbb */
+    color: string;
+    /** Every raw sample so far (document pixels), in order. */
+    points: readonly PenPoint[];
+    /** The samples this event added (`points` only). */
+    added: readonly PenPoint[];
+    /** `end`: the recorded stroke's id, or `null` when it painted nothing. */
+    strokeId?: string | null;
+}
 /** One change to the paint history, for hosts and change feeds (`onCommit`). */
 export interface PaintCommitEvent {
     /** `execute`: a new undo step. `merge`: folded into the last one (a slider drag). */
@@ -371,6 +386,7 @@ export declare class PaintEditorController {
     private readonly encodeImage;
     private listeners;
     private commitListeners;
+    private sampleListeners;
     /** Origins set by `withOrigin`, innermost last. */
     private origins;
     /** `group` in progress: commits fold into one step, recorded when it ends. */
@@ -433,6 +449,21 @@ export declare class PaintEditorController {
     private paperEffectNodeCache;
     constructor(options?: PaintEditorOptions);
     subscribe(listener: () => void): () => void;
+    /**
+     * Hears the user's live strokes as they are painted (`beginStroke` sessions, not strokes painted
+     * from data): when the pen goes down, each batch of samples, and the end or cancel. For agents
+     * that paint along in real time. Returns an unsubscribe function.
+     */
+    onStrokeSample(listener: (sample: PaintStrokeSample) => void): () => void;
+    private notifySample;
+    /** The stroke being painted now, or `null`: its layer, brush, colour and samples so far. */
+    getLiveStroke(): {
+        layerId: string;
+        brushId: string;
+        brushName: string;
+        color: string;
+        points: readonly PenPoint[];
+    } | null;
     /** Hears each undo step recorded, merged, undone or redone, with who made it. Returns an unsubscribe function. */
     onCommit(listener: (event: PaintCommitEvent) => void): () => void;
     private notifyCommit;

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

@@ -204,6 +204,21 @@ export interface PaintLayerInfo {
     /** How many live layer effects (glows, shadows, strokes…) it has, when any (`getLayerEffects`). */
     effects?: number;
 }
+/** A live stroke as it is painted (`onStrokeSample`), for agents that paint along with the user. */
+export interface PaintStrokeSample {
+    /** `begin`: the pen went down. `points`: new samples. `end`: the stroke was recorded. `cancel`: it was abandoned. */
+    phase: 'begin' | 'points' | 'end' | 'cancel';
+    layerId: string;
+    brush: PaintBrush;
+    /** #rrggbb */
+    color: string;
+    /** Every raw sample so far (document pixels), in order. */
+    points: readonly PenPoint[];
+    /** The samples this event added (`points` only). */
+    added: readonly PenPoint[];
+    /** `end`: the recorded stroke's id, or `null` when it painted nothing. */
+    strokeId?: string | null;
+}
 /** One change to the paint history, for hosts and change feeds (`onCommit`). */
 export interface PaintCommitEvent {
     /** `execute`: a new undo step. `merge`: folded into the last one (a slider drag). */
@@ -371,6 +386,7 @@ export declare class PaintEditorController {
     private readonly encodeImage;
     private listeners;
     private commitListeners;
+    private sampleListeners;
     /** Origins set by `withOrigin`, innermost last. */
     private origins;
     /** `group` in progress: commits fold into one step, recorded when it ends. */
@@ -433,6 +449,21 @@ export declare class PaintEditorController {
     private paperEffectNodeCache;
     constructor(options?: PaintEditorOptions);
     subscribe(listener: () => void): () => void;
+    /**
+     * Hears the user's live strokes as they are painted (`beginStroke` sessions, not strokes painted
+     * from data): when the pen goes down, each batch of samples, and the end or cancel. For agents
+     * that paint along in real time. Returns an unsubscribe function.
+     */
+    onStrokeSample(listener: (sample: PaintStrokeSample) => void): () => void;
+    private notifySample;
+    /** The stroke being painted now, or `null`: its layer, brush, colour and samples so far. */
+    getLiveStroke(): {
+        layerId: string;
+        brushId: string;
+        brushName: string;
+        color: string;
+        points: readonly PenPoint[];
+    } | null;
     /** Hears each undo step recorded, merged, undone or redone, with who made it. Returns an unsubscribe function. */
     onCommit(listener: (event: PaintCommitEvent) => void): () => void;
     private notifyCommit;