@scrawl-board/board 0.1.0-beta.0 → 0.1.0-beta.1

package/dist/browser.d.ts

@@ -5,6 +5,9 @@ type StrokeId = string & {
 
 /** Wire grammar: `asset:<namespace>:<opaque-id>`. Interpreted only by the Host. */
 type AssetRef = string;
+declare function isAssetRef(value: unknown): value is AssetRef;
+/** Throws on malformed input; use `isAssetRef` where a boolean is wanted instead. */
+declare function assetRef(value: string): AssetRef;
 type AssetKind = "image";
 type AssetPurpose = "render" | "thumbnail" | "export";
 interface AssetResolveRequest {
@@ -46,6 +49,12 @@ interface AssetIngestor {
     ingest(request: AssetIngestRequest): Promise<AssetIngestResult>;
 }
 type AssetResolutionErrorCode = "resolver-unavailable" | "not-found" | "forbidden" | "offline" | "unsupported-type" | "too-large" | "invalid-content" | "decode-failed" | "budget-exceeded" | "aborted" | "unknown";
+declare class AssetResolutionError extends Error {
+    readonly code: AssetResolutionErrorCode;
+    readonly retryable: boolean;
+    readonly ref?: AssetRef | undefined;
+    constructor(code: AssetResolutionErrorCode, retryable: boolean, message: string, ref?: AssetRef | undefined);
+}
 /** Runtime event for a resolution/ingestion failure — never carries credentials or a fetchable location. */
 interface AssetDiagnostic {
     code: AssetResolutionErrorCode;
@@ -54,6 +63,9 @@ interface AssetDiagnostic {
     objectKind: "image" | "custom";
     retryable: boolean;
 }
+declare const SUPPORTED_ASSET_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/webp"];
+type SupportedAssetMediaType = (typeof SUPPORTED_ASSET_MEDIA_TYPES)[number];
+declare function clampAssetCacheBytes(value: number | undefined): number;
 
 type Mat2x3 = [number, number, number, number, number, number];
 
@@ -101,6 +113,7 @@ interface CustomBoardObject {
     };
     props: JsonValue;
 }
+declare function cloneCustomObject(object: CustomBoardObject): CustomBoardObject;
 /**
  * The read-only view handed to `describe`. Deep-readonly by construction
  * (not derived via a shallow `Readonly<>`) because `describe` must treat its
@@ -867,22 +880,31 @@ interface CreateBoardControllerOptions {
      * Trusted Custom tool/object registrations (ticket #22, design:
      * docs/research/extension-contracts.md). Validated atomically at
      * construction; registration failure throws before any controller is
-     * returned. Not yet re-exported from a public package entry point —
-     * internal-only until the reference Extension proves the seam.
+     * returned.
      */
     extensions?: readonly ScrawlExtension[];
     /**
      * Optional Host-managed Asset capabilities (ticket #23, design:
      * docs/research/asset-resolution-resource-policy.md). Without a
      * resolver, referenced Assets preserve their Document geometry and
-     * render an accessible placeholder. Not yet re-exported from a public
-     * package entry point — internal-only until the reference resolver
-     * proves the seam, matching how `extensions` is scoped.
+     * render an accessible placeholder.
      */
     assetResolver?: AssetResolver;
     assetIngestor?: AssetIngestor;
     /** Clamped to 64–512MiB; defaults to 256MiB. */
     assetCacheBytes?: number;
+    /**
+     * The rendered board surface's color and reference grid. Defaults to the
+     * light theme preset's values; `<Scrawl>` keeps this current across theme
+     * changes via `boardTheme.set` below — a headless/browser-tier Host that
+     * doesn't use the React theme system can set this directly instead.
+     */
+    boardTheme?: {
+        surface?: string;
+        gridMode?: "none" | "line" | "dot";
+        gridColor?: string;
+        gridSpacing?: number;
+    };
 }
 interface BoardController {
     readonly document: ReadonlyBoardDocument;
@@ -908,6 +930,15 @@ interface BoardController {
         undo(): void;
         redo(): void;
     };
+    readonly boardTheme: {
+        /** Live update of the board surface color/grid — the controller's identity stays fixed across theme changes. */
+        set(theme: {
+            surface?: string;
+            gridMode?: "none" | "line" | "dot";
+            gridColor?: string;
+            gridSpacing?: number;
+        }): void;
+    };
     readonly view: {
         fit(): void;
         zoomTo(value: number): void;
@@ -1008,5 +1039,5 @@ type LocalBoard = {
 };
 declare function createLocalBoard(options: LocalBoardOptions): LocalBoard;
 
-export { STAMPS, createBoardController, createLocalBoard, isStampKind, stampDataUrl };
-export type { ApplyOpsResult, BoardController, BoardControllerError, BoardEventMap, BoardObject, BoardObjectInput, BoardObjectPatch, BoardSnapshot, BoardStyle, BoardView, BuiltInTool, CollaborationAdapter, CollaborationReceiver, CollaborationSession, CollaborationSnapshot, CollaboratorIdentity, CommentMarker, ControllerOp, CreateBoardControllerOptions, DeepReadonly, DocumentContext, LoadResult, LocalBoard, LocalBoardOptions, LocalBoardSnapshot, PersistenceAdapter, PersistenceDiagnostic, PersistenceSnapshot, PresenceCursor, PresenceUser, PresenceView, ReadonlyBoardDocument, ReadonlyDocumentChange, ScreenPoint, ScreenRect, StampKind };
+export { AssetResolutionError, STAMPS, SUPPORTED_ASSET_MEDIA_TYPES, assetRef, clampAssetCacheBytes, cloneCustomObject, createBoardController, createLocalBoard, isAssetRef, isStampKind, stampDataUrl };
+export type { ApplyOpsResult, AssetDiagnostic, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BoardController, BoardControllerError, BoardEventMap, BoardKeyInput, BoardObject, BoardObjectInput, BoardObjectPatch, BoardPointerInput, BoardScene, BoardSnapshot, BoardStyle, BoardView, BuiltInTool, CollaborationAdapter, CollaborationReceiver, CollaborationSession, CollaborationSnapshot, CollaboratorIdentity, CommentMarker, ControllerOp, CreateBoardControllerOptions, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DeepReadonly, DocumentContext, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, InputModifiers, JsonObject, JsonValue, LoadResult, LocalBoard, LocalBoardOptions, LocalBoardSnapshot, Mat2x3, ObjectDescribeContext, ObjectIntent, ObjectType, PersistenceAdapter, PersistenceDiagnostic, PersistenceSnapshot, PresenceCursor, PresenceUser, PresenceView, QueryableBoardObject, ReadonlyBoardDocument, ReadonlyCustomObject, ReadonlyDocumentChange, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlExtension, ScreenPoint, ScreenRect, StampKind, SupportedAssetMediaType, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId };

package/dist/browser.js

@@ -20,6 +20,11 @@ var AssetResolutionError = class extends Error {
 var ASSET_CACHE_BYTES_DEFAULT = 256 * 1024 * 1024;
 var ASSET_CACHE_BYTES_MIN = 64 * 1024 * 1024;
 var ASSET_CACHE_BYTES_MAX = 512 * 1024 * 1024;
+var SUPPORTED_ASSET_MEDIA_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp"
+];
 function clampAssetCacheBytes(value) {
 	if (value === void 0 || !Number.isFinite(value)) return ASSET_CACHE_BYTES_DEFAULT;
 	return Math.min(ASSET_CACHE_BYTES_MAX, Math.max(ASSET_CACHE_BYTES_MIN, Math.floor(value)));
@@ -442,7 +447,6 @@ function measureTable(table) {
 		height: table.rowHeights.reduce((sum, h) => sum + h, 0)
 	};
 }
-var BOARD_COLOR = "#FFFFFF";
 var FOG_COLOR = "#FFFFFF";
 function cloneImage(img) {
 	return { ...img };
@@ -1895,12 +1899,19 @@ var LIGHT = {
 var MARGIN = 4;
 var NOTE_FONT_RATIO = 44 / 512;
 var NOTE_PAD_RATIO = 40 / 512;
+/** Matches the theme system's light-preset `boardSurface` default (theme.ts) — kept in sync manually, since core-internal stays decoupled from the theme layer. */
+var DEFAULT_BACKGROUND_COLOR = "#f5f5f3";
 /**
 * `registry` is optional and only enables rendering Custom objects through
 * their own `describe()` — without it (or for an object whose extension
 * isn't in it), Custom objects still export via the standard fallback
 * placeholder (`fallback.bounds`/`label`), never silently dropped.
 *
+* `backgroundColor` should be the Host's actual resolved `boardTheme.surface`
+* so an export matches what was on screen; defaults to the theme system's
+* own light-preset default when the caller doesn't have one on hand. The
+* board's reference grid, if any, is a screen-only aid and never exported.
+*
 * `resolvedAssets` (ticket #23) maps an Asset reference to an already-
 * resolved `data:` URI — see `assetExport.ts`'s `exportDocumentSVGWithAssets`,
 * which is the only intended caller that ever passes one. Without it, every
@@ -1908,7 +1919,7 @@ var NOTE_PAD_RATIO = 40 / 512;
 * placeholder instead of guessing at a URL; a legacy `src`-backed image is
 * unaffected either way.
 */
-function documentToSVG(doc, now = 0, registry, resolvedAssets) {
+function documentToSVG(doc, now = 0, registry, backgroundColor = DEFAULT_BACKGROUND_COLOR, resolvedAssets) {
 	const notes = doc.notes ?? [];
 	const texts = doc.textBlocks ?? [];
 	const tables = doc.tables ?? [];
@@ -1921,7 +1932,7 @@ function documentToSVG(doc, now = 0, registry, resolvedAssets) {
 	const highlights = doc.strokes.filter((s) => s.tool === "highlighter");
 	const ink = doc.strokes.filter((s) => s.tool !== "highlighter");
 	return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${view}">\n<defs>\n${defs}\n</defs>\n${[
-		`<rect x="${fmt(bounds.minX)}" y="${fmt(bounds.minY)}" width="${fmt(bounds.width)}" height="${fmt(bounds.height)}" fill="${BOARD_COLOR}"/>`,
+		`<rect x="${fmt(bounds.minX)}" y="${fmt(bounds.minY)}" width="${fmt(bounds.width)}" height="${fmt(bounds.height)}" fill="${backgroundColor}"/>`,
 		...images.map((image) => imageToElement(image, resolvedAssets)),
 		...tables.map(tableToGroup),
 		...highlights.flatMap(strokeToPaths),
@@ -2837,7 +2848,7 @@ var SvgAssetExportError = class extends Error {
 		this.name = "SvgAssetExportError";
 	}
 };
-async function exportDocumentSVGWithAssets(doc, now, registry, assetController, options) {
+async function exportDocumentSVGWithAssets(doc, now, registry, assetController, backgroundColor, options) {
 	const refs = collectDocumentAssetRefs(doc, registry);
 	const resolvedAssets = /* @__PURE__ */ new Map();
 	const missingAssets = [];
@@ -2873,7 +2884,7 @@ async function exportDocumentSVGWithAssets(doc, now, registry, assetController,
 	}
 	if (missingAssets.length > 0 && options?.missingAssets !== "placeholder") throw new SvgAssetExportError(missingAssets);
 	return {
-		svg: documentToSVG(doc, now, registry, resolvedAssets),
+		svg: documentToSVG(doc, now, registry, backgroundColor, resolvedAssets),
 		missingAssets
 	};
 }
@@ -35794,6 +35805,21 @@ var FOG_GLSL = `
 `;
 //#endregion
 //#region ../../src/scrawl/engine/boardSurface.ts
+var GRID_MODE_CODE = {
+	none: 0,
+	line: 1,
+	dot: 2
+};
+/** Used when a caller doesn't supply one (e.g. ScrawlEngine constructed without a Host theme). */
+var DEFAULT_BOARD_SURFACE_THEME = {
+	color: "#f5f5f3",
+	gridMode: "none",
+	gridColor: "#deded8",
+	gridSpacing: 5
+};
+/** Grid alpha fades out below this on-screen spacing (px) — otherwise it aliases into a solid wash when zoomed out. */
+var GRID_FADE_MIN_PX = 3;
+var GRID_FADE_MAX_PX = 8;
 var VERTEX$1 = `
   varying vec3 vWorldPos;
   void main() {
@@ -35807,6 +35833,11 @@ var FRAGMENT = `
   uniform vec3 uFogColor;
   uniform float uFogNear;
   uniform float uFogFar;
+  uniform float uGridMode;
+  uniform vec3 uGridColor;
+  uniform float uGridSpacing;
+  uniform float uGridLineWorld;
+  uniform float uGridFade;
   varying vec3 vWorldPos;
 
   float hash(vec2 p) {
@@ -35825,6 +35856,22 @@ var FRAGMENT = `
 
   ${FOG_GLSL}
 
+  // Distance from p's nearest axis-aligned grid line, in world units.
+  float gridLineAlpha(vec2 p) {
+    vec2 cell = mod(p, uGridSpacing);
+    vec2 distToLine = min(cell, uGridSpacing - cell);
+    vec2 lineAlpha2 = 1.0 - smoothstep(uGridLineWorld, uGridLineWorld * 2.0, distToLine);
+    return max(lineAlpha2.x, lineAlpha2.y);
+  }
+
+  // Distance from p's nearest grid intersection, in world units.
+  float gridDotAlpha(vec2 p) {
+    vec2 cell = mod(p, uGridSpacing) - uGridSpacing * 0.5;
+    float dist = length(cell);
+    float radius = uGridLineWorld * 1.5;
+    return 1.0 - smoothstep(radius, radius * 2.0, dist);
+  }
+
   void main() {
     vec3 col = uColor;
 
@@ -35842,16 +35889,26 @@ var FRAGMENT = `
     float spec = pow(max(dot(N, H), 0.0), 90.0);
     col += (fres * 0.18 + spec * 0.06) * vec3(1.0);
 
+    if (uGridMode > 0.5 && uGridFade > 0.001) {
+      float gridAlpha = (uGridMode < 1.5 ? gridLineAlpha(vWorldPos.xy) : gridDotAlpha(vWorldPos.xy)) * uGridFade;
+      col = mix(col, uGridColor, gridAlpha);
+    }
+
     col = applyBoardFog(col, vWorldPos);
     gl_FragColor = vec4(col, 1.0);
   }
 `;
-function createBoardSurface(fog) {
+function createBoardSurface(fog, theme) {
 	const material = new ShaderMaterial({
 		vertexShader: VERTEX$1,
 		fragmentShader: FRAGMENT,
 		uniforms: {
-			uColor: { value: new Color(BOARD_COLOR) },
+			uColor: { value: new Color(theme.color) },
+			uGridMode: { value: GRID_MODE_CODE[theme.gridMode] },
+			uGridColor: { value: new Color(theme.gridColor) },
+			uGridSpacing: { value: Math.max(.001, theme.gridSpacing) },
+			uGridLineWorld: { value: .05 },
+			uGridFade: { value: 0 },
 			...fog
 		}
 	});
@@ -35859,11 +35916,32 @@ function createBoardSurface(fog) {
 	mesh.name = "board-surface";
 	return mesh;
 }
-/** Keep the plane centered under the view and larger than the fog horizon. */
-function updateBoardSurface(mesh, centerX, centerY, fogFar) {
+/** Applies a theme change (initial or live) — everything except the per-frame fade/line-width. */
+function setBoardSurfaceTheme(mesh, theme) {
+	const uniforms = mesh.material.uniforms;
+	uniforms.uColor.value.set(theme.color);
+	uniforms.uGridMode.value = GRID_MODE_CODE[theme.gridMode];
+	uniforms.uGridColor.value.set(theme.gridColor);
+	uniforms.uGridSpacing.value = Math.max(.001, theme.gridSpacing);
+}
+/** Keep the plane centered under the view, larger than the fog horizon, and the grid's on-screen weight/fade current. */
+function updateBoardSurface(mesh, centerX, centerY, fogFar, worldPerPixel) {
 	mesh.position.set(centerX, centerY, 0);
 	const size = fogFar * 2.5;
 	mesh.scale.set(size, size, 1);
+	const uniforms = mesh.material.uniforms;
+	uniforms.uGridLineWorld.value = worldPerPixel;
+	const t = (uniforms.uGridSpacing.value / Math.max(1e-6, worldPerPixel) - GRID_FADE_MIN_PX) / (GRID_FADE_MAX_PX - GRID_FADE_MIN_PX);
+	uniforms.uGridFade.value = MathUtils.clamp(t, 0, 1);
+}
+/** Temporarily zeroes the grid's contribution (for export snapshots) and returns a restore function. */
+function suppressBoardSurfaceGrid(mesh) {
+	const uniforms = mesh.material.uniforms;
+	const previous = uniforms.uGridFade.value;
+	uniforms.uGridFade.value = 0;
+	return () => {
+		uniforms.uGridFade.value = previous;
+	};
 }
 var MIN_HEIGHT = 40;
 var MAX_HEIGHT = 1500;
@@ -36027,7 +36105,7 @@ var CameraRig = class {
 //#endregion
 //#region ../../src/scrawl/engine/scene.ts
 var SceneRig = class {
-	constructor(canvas) {
+	constructor(canvas, boardTheme) {
 		this.renderer = new WebGLRenderer({
 			canvas,
 			antialias: true
@@ -36037,7 +36115,7 @@ var SceneRig = class {
 		this.scene = new Scene();
 		this.cameraRig = new CameraRig(canvas.clientWidth / Math.max(1, canvas.clientHeight));
 		this.fog = createFogUniforms(FOG_COLOR);
-		this.board = createBoardSurface(this.fog);
+		this.board = createBoardSurface(this.fog, boardTheme);
 		this.scene.add(this.board);
 		this.inkGroup = new Group();
 		this.inkGroup.name = "ink";
@@ -36054,9 +36132,17 @@ var SceneRig = class {
 	renderFrame(dtMs) {
 		this.cameraRig.update(dtMs);
 		updateFogForCamera(this.fog, this.cameraRig.height);
-		updateBoardSurface(this.board, this.cameraRig.center.x, this.cameraRig.center.y, this.fog.uFogFar.value);
+		updateBoardSurface(this.board, this.cameraRig.center.x, this.cameraRig.center.y, this.fog.uFogFar.value, this.cameraRig.worldPerPixel());
 		this.renderer.render(this.scene, this.cameraRig.camera);
 	}
+	/** Live theme update — the board controller's identity stays fixed across theme changes; this is how a new one reaches the render engine. */
+	applyBoardTheme(theme) {
+		setBoardSurfaceTheme(this.board, theme);
+	}
+	/** Zeroes the grid for one render pass (PNG export never bakes it in) and returns a restore function. */
+	suppressGrid() {
+		return suppressBoardSurfaceGrid(this.board);
+	}
 	dispose() {
 		this.board.geometry.dispose();
 		this.board.material.dispose();
@@ -46505,9 +46591,10 @@ function emptyExtensionRegistry() {
 * React never reaches past this class.
 */
 var ScrawlEngine = class {
-	constructor(canvas, documentId$1, extensionRegistry = emptyExtensionRegistry(), assetController = new AssetController(void 0)) {
+	constructor(canvas, documentId$1, extensionRegistry = emptyExtensionRegistry(), assetController = new AssetController(void 0), boardTheme = DEFAULT_BOARD_SURFACE_THEME) {
 		this.canvas = canvas;
 		this.extensionRegistry = extensionRegistry;
+		this.boardTheme = boardTheme;
 		this.onToolChange = null;
 		this.onZoomChange = null;
 		this.onAuditEvent = null;
@@ -46554,7 +46641,7 @@ var ScrawlEngine = class {
 		this.stampKind = "star";
 		this.timerDurationMs = TIMER_DEFAULT_DURATION_MS;
 		this.readOnly = false;
-		this.scene = new SceneRig(canvas);
+		this.scene = new SceneRig(canvas, boardTheme);
 		this.document = new BoardDocument(documentId(documentId$1));
 		this.history = new History(this.document);
 		this.history.onCommand = (command, kind) => {
@@ -46861,6 +46948,11 @@ var ScrawlEngine = class {
 			height: rig.height
 		};
 	}
+	/** Live update of the board surface color/grid — the engine's identity stays fixed across theme changes. */
+	applyBoardTheme(theme) {
+		this.boardTheme = theme;
+		this.scene.applyBoardTheme(theme);
+	}
 	/**
 	* Snap to a peer's camera. No-op while drawing so pointer-to-board
 	* mapping does not warp the in-progress stroke.
@@ -46879,7 +46971,7 @@ var ScrawlEngine = class {
 	}
 	/** The saved document as standalone SVG — a pure walk of the wire format. */
 	exportSVG() {
-		return documentToSVG(this.document.toJSON(), Date.now(), this.extensionRegistry);
+		return documentToSVG(this.document.toJSON(), Date.now(), this.extensionRegistry, this.boardTheme.color);
 	}
 	/**
 	* Content-framed PNG snapshot. Renders once offscreen-style with UI props
@@ -46915,6 +47007,7 @@ var ScrawlEngine = class {
 		this.notesRenderer.setFocus(null);
 		this.textsRenderer.setFocus(null);
 		this.renderer.setGhostsVisible(false);
+		const restoreGrid = this.scene.suppressGrid();
 		try {
 			rig.yaw = 0;
 			rig.pitch = 0;
@@ -46925,6 +47018,7 @@ var ScrawlEngine = class {
 			const dataUrl = this.scene.renderer.domElement.toDataURL("image/png");
 			return await (await fetch(dataUrl)).blob();
 		} finally {
+			restoreGrid();
 			rig.center.x = saved.x;
 			rig.center.y = saved.y;
 			rig.height = saved.height;
@@ -47934,7 +48028,13 @@ function createBoardControllerWithEngine(options, existingEngine) {
 	}
 	const extensionRegistry = registryResult.registry;
 	const assetController = new AssetController(options.assetResolver, { cacheBytes: options.assetCacheBytes });
-	const engine = existingEngine ?? (options.canvas ? new ScrawlEngine(options.canvas, options.document.id, extensionRegistry, assetController) : null);
+	let currentBoardTheme = {
+		color: options.boardTheme?.surface ?? DEFAULT_BOARD_SURFACE_THEME.color,
+		gridMode: options.boardTheme?.gridMode ?? DEFAULT_BOARD_SURFACE_THEME.gridMode,
+		gridColor: options.boardTheme?.gridColor ?? DEFAULT_BOARD_SURFACE_THEME.gridColor,
+		gridSpacing: options.boardTheme?.gridSpacing ?? DEFAULT_BOARD_SURFACE_THEME.gridSpacing
+	};
+	const engine = existingEngine ?? (options.canvas ? new ScrawlEngine(options.canvas, options.document.id, extensionRegistry, assetController, currentBoardTheme) : null);
 	const document = engine?.document ?? new BoardDocument(documentId(options.document.id));
 	const history = engine?.history ?? new History(document);
 	const createId = options.createId ?? (() => crypto.randomUUID());
@@ -48418,6 +48518,15 @@ function createBoardControllerWithEngine(options, existingEngine) {
 				changed();
 			}
 		},
+		boardTheme: { set(theme) {
+			currentBoardTheme = {
+				color: theme.surface ?? currentBoardTheme.color,
+				gridMode: theme.gridMode ?? currentBoardTheme.gridMode,
+				gridColor: theme.gridColor ?? currentBoardTheme.gridColor,
+				gridSpacing: theme.gridSpacing ?? currentBoardTheme.gridSpacing
+			};
+			engine?.applyBoardTheme(currentBoardTheme);
+		} },
 		view: {
 			fit() {
 				assertActive();
@@ -48722,10 +48831,10 @@ function createBoardControllerWithEngine(options, existingEngine) {
 			gather: (nextView) => engine?.applyGatherView(nextView) ?? false
 		},
 		export: {
-			svg: () => engine ? engine.exportSVG() : documentToSVG(document.toJSON(), Date.now(), extensionRegistry),
+			svg: () => engine ? engine.exportSVG() : documentToSVG(document.toJSON(), Date.now(), extensionRegistry, currentBoardTheme.color),
 			png: (options) => engine ? engine.exportPNG(options?.maxSide, { awaitAssets: options?.awaitAssets }) : Promise.resolve(null),
 			json: () => document.toJSON(),
-			svgAsync: (svgOptions) => exportDocumentSVGWithAssets(document.toJSON(), Date.now(), extensionRegistry, assetController, svgOptions)
+			svgAsync: (svgOptions) => exportDocumentSVGWithAssets(document.toJSON(), Date.now(), extensionRegistry, assetController, currentBoardTheme.color, svgOptions)
 		},
 		assets: { async ingest(bytes, mediaType, name, signal) {
 			assertActive();
@@ -49187,4 +49296,4 @@ function createLocalBoard(options) {
 	};
 }
 //#endregion
-export { STAMPS, createBoardController, createLocalBoard, isStampKind, stampDataUrl };
+export { AssetResolutionError, STAMPS, SUPPORTED_ASSET_MEDIA_TYPES, assetRef, clampAssetCacheBytes, cloneCustomObject, createBoardController, createLocalBoard, isAssetRef, isStampKind, stampDataUrl };

package/dist/core.d.ts

@@ -11,6 +11,79 @@ declare function strokeId(value: string): StrokeId;
 
 /** Wire grammar: `asset:<namespace>:<opaque-id>`. Interpreted only by the Host. */
 type AssetRef = string;
+declare const ASSET_REF_PATTERN: RegExp;
+/** Hard ceiling on a reference's own wire length — independent of any resource limit below. */
+declare const ASSET_REF_MAX_BYTES = 512;
+declare function isAssetRef(value: unknown): value is AssetRef;
+/** Throws on malformed input; use `isAssetRef` where a boolean is wanted instead. */
+declare function assetRef(value: string): AssetRef;
+type AssetKind = "image";
+type AssetPurpose = "render" | "thumbnail" | "export";
+interface AssetResolveRequest {
+    ref: AssetRef;
+    kind: AssetKind;
+    purpose: AssetPurpose;
+    signal: AbortSignal;
+}
+interface AssetResolveResult {
+    bytes: Uint8Array;
+    mediaType: string;
+}
+/**
+ * Host-owned lookup. Scrawl passes only the reference, kind, purpose, and
+ * signal — never Document contents, an Extension instance, or credentials.
+ * The returned bytes are copied into SDK-owned storage and independently
+ * validated before use; a resolver's claimed `mediaType` is never trusted
+ * on its own (see `assetValidation.ts`).
+ */
+interface AssetResolver {
+    resolve(request: AssetResolveRequest): Promise<AssetResolveResult>;
+}
+interface AssetIngestRequest {
+    bytes: Uint8Array;
+    mediaType: string;
+    name?: string;
+    signal: AbortSignal;
+}
+interface AssetIngestResult {
+    ref: AssetRef;
+}
+/**
+ * Host-owned upload/creation path. Scrawl validates the candidate against
+ * SDK limits before calling this, and validates the returned reference
+ * before it can enter any command. Cancellation or failure creates no
+ * Document object, Op, or history entry.
+ */
+interface AssetIngestor {
+    ingest(request: AssetIngestRequest): Promise<AssetIngestResult>;
+}
+type AssetResolutionErrorCode = "resolver-unavailable" | "not-found" | "forbidden" | "offline" | "unsupported-type" | "too-large" | "invalid-content" | "decode-failed" | "budget-exceeded" | "aborted" | "unknown";
+declare class AssetResolutionError extends Error {
+    readonly code: AssetResolutionErrorCode;
+    readonly retryable: boolean;
+    readonly ref?: AssetRef | undefined;
+    constructor(code: AssetResolutionErrorCode, retryable: boolean, message: string, ref?: AssetRef | undefined);
+}
+/** Runtime event for a resolution/ingestion failure — never carries credentials or a fetchable location. */
+interface AssetDiagnostic {
+    code: AssetResolutionErrorCode;
+    ref?: AssetRef;
+    objectId: string;
+    objectKind: "image" | "custom";
+    retryable: boolean;
+}
+declare const ASSET_MAX_ENCODED_BYTES: number;
+declare const ASSET_MAX_DIMENSION_PX = 8192;
+declare const ASSET_MAX_DECODED_MEGAPIXELS = 40;
+declare const ASSET_MAX_CONCURRENT_RESOLUTIONS = 6;
+declare const ASSET_CACHE_BYTES_DEFAULT: number;
+declare const ASSET_CACHE_BYTES_MIN: number;
+declare const ASSET_CACHE_BYTES_MAX: number;
+declare const ASSET_EXPORT_MAX_ENCODED_BYTES: number;
+declare const ASSET_EXPORT_MAX_DECODED_MEGAPIXELS = 100;
+declare const SUPPORTED_ASSET_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/webp"];
+type SupportedAssetMediaType = (typeof SUPPORTED_ASSET_MEDIA_TYPES)[number];
+declare function clampAssetCacheBytes(value: number | undefined): number;
 
 type Mat2x3 = [number, number, number, number, number, number];
 declare const IDENTITY: Mat2x3;
@@ -69,6 +142,7 @@ interface CustomBoardObject {
     };
     props: JsonValue;
 }
+declare function cloneCustomObject(object: CustomBoardObject): CustomBoardObject;
 /**
  * The read-only view handed to `describe`. Deep-readonly by construction
  * (not derived via a shallow `Readonly<>`) because `describe` must treat its
@@ -106,7 +180,7 @@ interface CustomObjectDefinition<Props extends JsonValue = JsonValue> {
     parse(input: unknown, schemaVersion: number): Props;
     /** One pure, synchronous step per consecutive schema version. */
     migrate?: Readonly<Record<number, (oldProps: JsonValue) => JsonValue>>;
-    describe(object: ReadonlyCustomObject<Props>, context: ObjectDescribeContext): BoardScene$1;
+    describe(object: ReadonlyCustomObject<Props>, context: ObjectDescribeContext): BoardScene;
 }
 interface SceneNodeBase {
     key: string;
@@ -138,9 +212,9 @@ interface SceneText extends SceneNodeBase {
 }
 interface SceneGroup extends SceneNodeBase {
     kind: "group";
-    children: readonly BoardScene$1[];
+    children: readonly BoardScene[];
 }
-interface ScenePath$1 extends SceneNodeBase {
+interface ScenePath extends SceneNodeBase {
     kind: "path";
     /** SVG-style path data, board-local coordinates. */
     d: string;
@@ -173,7 +247,7 @@ interface SceneEllipse extends SceneNodeBase {
     stroke?: string;
     strokeWidth?: number;
 }
-type BoardScene$1 = SceneGroup | ScenePath$1 | SceneText | SceneImage | SceneRect | SceneEllipse;
+type BoardScene = SceneGroup | ScenePath | SceneText | SceneImage | SceneRect | SceneEllipse;
 type ToolCursor = "default" | "crosshair" | "pointer" | "grab" | "grabbing" | "text";
 type ToolCancelReason = "escape-key" | "tool-switched" | "pointer-lost" | "error";
 interface InputModifiers {
@@ -269,7 +343,7 @@ interface ToolCapabilities {
     };
     /** Session-only geometry — never enters Document/history/persistence/collaboration. */
     preview: {
-        set(scene: BoardScene$1): void;
+        set(scene: BoardScene): void;
         clear(): void;
     };
     /** Constructs, validates, and commits one atomic command; controller derives Ops. */
@@ -279,6 +353,15 @@ interface ToolCapabilities {
         cancel(): void;
     };
 }
+interface ExtensionDiagnostic {
+    extensionId: ExtensionId;
+    phase: "parse" | "migrate" | "describe" | "tool-lifecycle" | "react-companion" | "asset-resolution";
+    toolId?: ToolId;
+    objectId?: string;
+    objectType?: ObjectType;
+    recoverable: boolean;
+    cause: unknown;
+}
 
 /** Who holds a lock. Stored on the item so only they can take it off. */
 interface LockHolder {
@@ -489,7 +572,6 @@ declare function measureTable(table: TableBlock): {
     width: number;
     height: number;
 };
-declare const BOARD_COLOR = "#FFFFFF";
 declare const FOG_COLOR = "#FFFFFF";
 /**
  * An imported image block on the board plane.
@@ -1048,6 +1130,11 @@ interface ExtensionRegistry {
  * isn't in it), Custom objects still export via the standard fallback
  * placeholder (`fallback.bounds`/`label`), never silently dropped.
  *
+ * `backgroundColor` should be the Host's actual resolved `boardTheme.surface`
+ * so an export matches what was on screen; defaults to the theme system's
+ * own light-preset default when the caller doesn't have one on hand. The
+ * board's reference grid, if any, is a screen-only aid and never exported.
+ *
  * `resolvedAssets` (ticket #23) maps an Asset reference to an already-
  * resolved `data:` URI — see `assetExport.ts`'s `exportDocumentSVGWithAssets`,
  * which is the only intended caller that ever passes one. Without it, every
@@ -1055,30 +1142,14 @@ interface ExtensionRegistry {
  * placeholder instead of guessing at a URL; a legacy `src`-backed image is
  * unaffected either way.
  */
-declare function documentToSVG(doc: SerializedDocument, now?: number, registry?: ExtensionRegistry, resolvedAssets?: ReadonlyMap<AssetRef, string>): string;
+declare function documentToSVG(doc: SerializedDocument, now?: number, registry?: ExtensionRegistry, backgroundColor?: string, resolvedAssets?: ReadonlyMap<AssetRef, string>): string;
 
 declare const SDK_PACKAGE_NAME = "@scrawl-board/board";
 declare const SDK_DEVELOPMENT_VERSION = "0.0.0-development";
 
-type BoardBounds = {
-    minX: number;
-    minY: number;
-    maxX: number;
-    maxY: number;
-};
-type ScenePath = {
-    id: string;
-    color: string;
-    width: number;
-    points: readonly BoardPoint[];
-};
-type BoardScene = {
-    bounds: BoardBounds;
-    paths: readonly ScenePath[];
-};
 type BoardStroke = Stroke;
 type SerializedBoardStroke = SerializedStroke;
 type SerializedBoardDocument = CurrentSerializedDocument;
 
-export { AddImageCommand, AddNoteCommand, AddStrokesCommand, AddTableCommand, AddTextCommand, AddTimerCommand, BEACON_INSET, BOARD_COLOR, BoardDocument, CURRENT_DOCUMENT_SCHEMA_VERSION, ClusterStore, DeleteImageCommand, DeleteNoteCommand, DeleteStrokesCommand, DeleteTableCommand, DeleteTextCommand, DeleteTimerCommand, DocumentRecoveryError, END_TAPER, ERASE_THRESHOLD, EraseCommand, FOG_COLOR, HIGHLIGHT_COLORS, History, IDENTITY, INK_COLORS, LockItemsCommand, MIN_WIDTH_FACTOR, NOTE_COLORS, NOTE_DEFAULT_SIZE, NOTE_DEFAULT_Z, NOTE_MAX_Z, NOTE_MIN_Z, NOTE_PEEL_STEP, SDK_DEVELOPMENT_VERSION, SDK_PACKAGE_NAME, STAMPS, STAMP_SIZE, SpatialIndex, TABLE_DEFAULT_CELL_HEIGHT, TABLE_DEFAULT_CELL_WIDTH, TABLE_DEFAULT_FONT_SIZE, TEXT_DEFAULT_SIZE, TIMER_DEFAULT_DURATION_MS, TIMER_DEFAULT_SIZE, TIMER_PRESETS_MS, TransformCommand, UpdateImageCommand, UpdateNoteCommand, UpdateTableCommand, UpdateTextCommand, UpdateTimerCommand, apply, applyItemLock, avgScale, canUnlockItem, changeToOps, cloneImage, cloneNote, cloneStroke, cloneTable, cloneText, cloneTimer, documentId, documentToSVG, formatTimer, invert, isIdentity, isStampKind, loadDocumentBytes, measureTable, measureTextBlock, migrateDocument, mul, pauseTimer, placePresenceBeacon, ribbonEdges, rotationAbout, scalingAbout, searchBoard, serializeDocument, serializeLock, serializeStroke, setTimerDuration, stampDataUrl, startTimer, strokeId, timerExpired, timerRemaining, toggleTimer, translation };
-export type { BBox, BoardBounds, BoardPoint, BoardScene, BoardStroke, ClusterIdFactory, Command, CommandKind, CurrentSerializedDocument, CurrentSerializedStroke, DocumentChange, DocumentId, DocumentLoadResult, DocumentRecoveryCode, ImageBlock, KitchenTimer, LockHolder, LockTarget, Lockable, Mat2x3, NoteVote, Op, OpCollection, PresencePlacement, RibbonEdgePoint, ScenePath, SearchHit, SearchHitKind, SearchableBoard, SearchableComment, SerializedBoardDocument, SerializedBoardStroke, SerializedPoint, SerializedStroke, StampKind, StickyNote, Stroke, StrokeId, StrokePoint, StrokeTool, TableBlock, TextBlock, ViewportInset };
+export { ASSET_CACHE_BYTES_DEFAULT, ASSET_CACHE_BYTES_MAX, ASSET_CACHE_BYTES_MIN, ASSET_EXPORT_MAX_DECODED_MEGAPIXELS, ASSET_EXPORT_MAX_ENCODED_BYTES, ASSET_MAX_CONCURRENT_RESOLUTIONS, ASSET_MAX_DECODED_MEGAPIXELS, ASSET_MAX_DIMENSION_PX, ASSET_MAX_ENCODED_BYTES, ASSET_REF_MAX_BYTES, ASSET_REF_PATTERN, AddImageCommand, AddNoteCommand, AddStrokesCommand, AddTableCommand, AddTextCommand, AddTimerCommand, AssetResolutionError, BEACON_INSET, BoardDocument, CURRENT_DOCUMENT_SCHEMA_VERSION, ClusterStore, DeleteImageCommand, DeleteNoteCommand, DeleteStrokesCommand, DeleteTableCommand, DeleteTextCommand, DeleteTimerCommand, DocumentRecoveryError, END_TAPER, ERASE_THRESHOLD, EraseCommand, FOG_COLOR, HIGHLIGHT_COLORS, History, IDENTITY, INK_COLORS, LockItemsCommand, MIN_WIDTH_FACTOR, NOTE_COLORS, NOTE_DEFAULT_SIZE, NOTE_DEFAULT_Z, NOTE_MAX_Z, NOTE_MIN_Z, NOTE_PEEL_STEP, SDK_DEVELOPMENT_VERSION, SDK_PACKAGE_NAME, STAMPS, STAMP_SIZE, SUPPORTED_ASSET_MEDIA_TYPES, SpatialIndex, TABLE_DEFAULT_CELL_HEIGHT, TABLE_DEFAULT_CELL_WIDTH, TABLE_DEFAULT_FONT_SIZE, TEXT_DEFAULT_SIZE, TIMER_DEFAULT_DURATION_MS, TIMER_DEFAULT_SIZE, TIMER_PRESETS_MS, TransformCommand, UpdateImageCommand, UpdateNoteCommand, UpdateTableCommand, UpdateTextCommand, UpdateTimerCommand, apply, applyItemLock, assetRef, avgScale, canUnlockItem, changeToOps, clampAssetCacheBytes, cloneCustomObject, cloneImage, cloneNote, cloneStroke, cloneTable, cloneText, cloneTimer, documentId, documentToSVG, formatTimer, invert, isAssetRef, isIdentity, isStampKind, loadDocumentBytes, measureTable, measureTextBlock, migrateDocument, mul, pauseTimer, placePresenceBeacon, ribbonEdges, rotationAbout, scalingAbout, searchBoard, serializeDocument, serializeLock, serializeStroke, setTimerDuration, stampDataUrl, startTimer, strokeId, timerExpired, timerRemaining, toggleTimer, translation };
+export type { AssetDiagnostic, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BBox, BoardKeyInput, BoardPoint, BoardPointerInput, BoardScene, BoardStroke, ClusterIdFactory, Command, CommandKind, CurrentSerializedDocument, CurrentSerializedStroke, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DocumentChange, DocumentId, DocumentLoadResult, DocumentRecoveryCode, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, ImageBlock, InputModifiers, JsonObject, JsonValue, KitchenTimer, LockHolder, LockTarget, Lockable, Mat2x3, NoteVote, ObjectDescribeContext, ObjectIntent, ObjectType, Op, OpCollection, PresencePlacement, QueryableBoardObject, ReadonlyCustomObject, RibbonEdgePoint, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlExtension, SearchHit, SearchHitKind, SearchableBoard, SearchableComment, SerializedBoardDocument, SerializedBoardStroke, SerializedPoint, SerializedStroke, StampKind, StickyNote, Stroke, StrokeId, StrokePoint, StrokeTool, SupportedAssetMediaType, TableBlock, TextBlock, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId, ViewportInset };