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

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 };

package/dist/core.js

@@ -1,10 +1,44 @@
-//#region src/core-internal/assets.ts
+//#region src/core/shapes/assets.ts
 var ASSET_REF_PATTERN = /^asset:[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?:[A-Za-z0-9._~-]+$/;
+/** Hard ceiling on a reference's own wire length — independent of any resource limit below. */
+var ASSET_REF_MAX_BYTES = 512;
 function isAssetRef(value) {
 	return typeof value === "string" && ASSET_REF_PATTERN.test(value) && new TextEncoder().encode(value).length <= 512;
 }
+/** Throws on malformed input; use `isAssetRef` where a boolean is wanted instead. */
+function assetRef(value) {
+	if (!isAssetRef(value)) throw new TypeError(`Not a well-formed AssetRef: ${JSON.stringify(value)}`);
+	return value;
+}
+var AssetResolutionError = class extends Error {
+	constructor(code, retryable, message, ref) {
+		super(message);
+		this.code = code;
+		this.retryable = retryable;
+		this.ref = ref;
+		this.name = "AssetResolutionError";
+	}
+};
+var ASSET_MAX_ENCODED_BYTES = 20 * 1024 * 1024;
+var ASSET_MAX_DIMENSION_PX = 8192;
+var ASSET_MAX_DECODED_MEGAPIXELS = 40;
+var ASSET_MAX_CONCURRENT_RESOLUTIONS = 6;
+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 ASSET_EXPORT_MAX_ENCODED_BYTES = 100 * 1024 * 1024;
+var ASSET_EXPORT_MAX_DECODED_MEGAPIXELS = 100;
+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)));
+}
 //#endregion
-//#region src/core-internal/identifiers.ts
+//#region src/core/document/identifiers.ts
 function documentId(value) {
 	if (!value) throw new TypeError("DocumentId cannot be empty");
 	return value;
@@ -14,7 +48,7 @@ function strokeId(value) {
 	return value;
 }
 //#endregion
-//#region src/document-schema.ts
+//#region src/core/document/document-schema.ts
 var CURRENT_DOCUMENT_SCHEMA_VERSION = 1;
 var DocumentRecoveryError = class extends Error {
 	constructor(code, message, originalBytes, path) {
@@ -222,7 +256,7 @@ function validation(message, path) {
 	return new DocumentRecoveryError("DOCUMENT_VALIDATION_FAILED", message, void 0, path);
 }
 //#endregion
-//#region src/core-internal/affine2d.ts
+//#region src/core/shapes/affine2d.ts
 var IDENTITY = [
 	1,
 	0,
@@ -306,7 +340,7 @@ function avgScale(m) {
 	return (Math.hypot(m[0], m[1]) + Math.hypot(m[2], m[3])) / 2;
 }
 //#endregion
-//#region src/core-internal/boardSearch.ts
+//#region src/core/document/boardSearch.ts
 function hay(s) {
 	return s.toLowerCase();
 }
@@ -371,7 +405,7 @@ function searchBoard(query, board) {
 	return hits;
 }
 //#endregion
-//#region src/core-internal/types.ts
+//#region src/core/shapes/types.ts
 /** Erasure level at which a point counts as fully erased. */
 var ERASE_THRESHOLD = .95;
 function cloneStroke(stroke) {
@@ -442,13 +476,12 @@ 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 };
 }
 //#endregion
-//#region src/core-internal/clusterStore.ts
+//#region src/core/document/clusterStore.ts
 /** A stroke joins a cluster last written to within this window at full reach. */
 var RECENT_MS = 8e3;
 /** Older clusters are still joinable, at half the gap threshold. */
@@ -619,7 +652,7 @@ function clamp$1(v, lo, hi) {
 	return Math.min(hi, Math.max(lo, v));
 }
 //#endregion
-//#region src/core-internal/extensionTypes.ts
+//#region src/core/shapes/extensionTypes.ts
 function cloneCustomObject(object) {
 	return {
 		...object,
@@ -629,7 +662,7 @@ function cloneCustomObject(object) {
 	};
 }
 //#endregion
-//#region src/core-internal/kitchenTimer.ts
+//#region src/core/shapes/kitchenTimer.ts
 var TIMER_DEFAULT_SIZE = 12;
 var TIMER_DEFAULT_DURATION_MS = 300 * 1e3;
 var TIMER_PRESETS_MS = [
@@ -686,7 +719,7 @@ function formatTimer(ms) {
 	return `${Math.floor(total / 60)}:${(total % 60).toString().padStart(2, "0")}`;
 }
 //#endregion
-//#region src/core-internal/itemLock.ts
+//#region src/core/shapes/itemLock.ts
 /**
 * Apply or clear a lock in place. Unlock always drops the holder so a stale
 * name cannot linger on an unlocked item.
@@ -723,7 +756,7 @@ function serializeLock(item) {
 	};
 }
 //#endregion
-//#region src/core-internal/document.ts
+//#region src/core/document/document.ts
 /**
 * The one place a live Stroke becomes its wire representation — in
 * particular, points collapse from {x,y,pressure,erase?} objects into
@@ -1282,7 +1315,7 @@ function computeBBox(stroke) {
 	return world;
 }
 //#endregion
-//#region src/core-internal/commands.ts
+//#region src/core/commands/commands.ts
 /** One drawing action — a marker stroke, or a shape's strokes as one unit. */
 var AddStrokesCommand = class {
 	constructor(strokes) {
@@ -1581,7 +1614,7 @@ var LockItemsCommand = class {
 	}
 };
 //#endregion
-//#region src/core-internal/history.ts
+//#region src/core/history/history.ts
 var LIMIT = 200;
 var History = class {
 	constructor(doc) {
@@ -1642,7 +1675,7 @@ var History = class {
 	}
 };
 //#endregion
-//#region src/core-internal/ops.ts
+//#region src/core/events/ops.ts
 var ADDED = [
 	["added", "strokes"],
 	["notesAdded", "notes"],
@@ -1696,7 +1729,7 @@ function changeToOps(change, restoring = false) {
 	return ops;
 }
 //#endregion
-//#region src/core-internal/ribbonEdges.ts
+//#region src/core/shapes/ribbonEdges.ts
 var MIN_WIDTH_FACTOR = .35;
 var END_TAPER = .55;
 function ribbonEdges(points, baseWidth) {
@@ -1728,7 +1761,7 @@ function ribbonEdges(points, baseWidth) {
 	return out;
 }
 //#endregion
-//#region src/core-internal/spatialIndex.ts
+//#region src/core/document/spatialIndex.ts
 var CELL = 8;
 var SpatialIndex = class {
 	constructor(doc) {
@@ -1801,7 +1834,7 @@ function cellsOf(box) {
 	return keys;
 }
 //#endregion
-//#region src/core-internal/stamps.ts
+//#region src/core/shapes/stamps.ts
 var STAMP_SIZE = 6;
 var STAMPS = [
 	{
@@ -1850,7 +1883,7 @@ function isStampKind(value) {
 	return typeof value === "string" && STAMPS.some((s) => s.kind === value);
 }
 //#endregion
-//#region src/core-internal/presence.ts
+//#region src/collaboration/presence/presence.ts
 /** Keep beacons clear of typical chrome at the top and bottom of the Board. */
 var BEACON_INSET = {
 	top: 72,
@@ -1886,7 +1919,7 @@ function clamp(value, min, max) {
 	return Math.min(max, Math.max(min, value));
 }
 //#endregion
-//#region src/core-internal/svg.ts
+//#region src/persistence/serialization/svg.ts
 /** Matches the key light used by the board shader and note shadows. */
 var LIGHT = {
 	x: -.25,
@@ -1896,12 +1929,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
@@ -1909,7 +1949,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 ?? [];
@@ -1922,7 +1962,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),
@@ -2250,4 +2290,4 @@ function fmt(n) {
 var SDK_PACKAGE_NAME = "@scrawl-board/board";
 var SDK_DEVELOPMENT_VERSION = "0.0.0-development";
 //#endregion
-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 { 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 };