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

package/dist/index.js

@@ -1,8 +1,10 @@
 import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { createPortal } from "react-dom";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-//#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;
 }
@@ -20,15 +22,26 @@ var AssetResolutionError = class extends Error {
 		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;
@@ -38,7 +51,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) {
@@ -246,7 +259,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,
@@ -330,7 +343,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();
 }
@@ -395,7 +408,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) {
@@ -466,13 +479,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. */
@@ -643,7 +655,7 @@ function clamp$3(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,
@@ -653,7 +665,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 = [
@@ -710,7 +722,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.
@@ -747,7 +759,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
@@ -1306,7 +1318,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) {
@@ -1648,7 +1660,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) {
@@ -1709,7 +1721,7 @@ var History = class {
 	}
 };
 //#endregion
-//#region src/core-internal/ops.ts
+//#region src/core/events/ops.ts
 var ADDED = [
 	["added", "strokes"],
 	["notesAdded", "notes"],
@@ -1763,7 +1775,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) {
@@ -1795,7 +1807,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) {
@@ -1868,7 +1880,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 = [
 	{
@@ -1917,7 +1929,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,
@@ -1953,7 +1965,7 @@ function clamp$2(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,
@@ -1963,12 +1975,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
@@ -1976,7 +1995,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 ?? [];
@@ -1989,7 +2008,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),
@@ -2317,7 +2336,7 @@ function fmt(n) {
 var SDK_PACKAGE_NAME = "@scrawl-board/board";
 var SDK_DEVELOPMENT_VERSION = "0.0.0-development";
 //#endregion
-//#region src/core-internal/sceneGeometry.ts
+//#region src/core/shapes/sceneGeometry.ts
 var EMPTY_BOUNDS = {
 	x: 0,
 	y: 0,
@@ -2381,7 +2400,7 @@ function textCorners(x, y, text, fontSize, align, m) {
 	return rectCorners(x + (align === "center" ? -width / 2 : align === "end" ? -width : 0), y, width, height, m);
 }
 //#endregion
-//#region src/core-internal/customObjects.ts
+//#region src/core/shapes/customObjects.ts
 var FALLBACK_LABEL_MAX_LENGTH = 80;
 function toReadonly(object) {
 	return object;
@@ -2510,7 +2529,7 @@ function extensionIdFromType(type) {
 	return slash === -1 ? type : type.slice(0, slash);
 }
 //#endregion
-//#region src/core-internal/extensionRegistry.ts
+//#region src/core/shapes/extensionRegistry.ts
 function buildExtensionRegistry(extensions) {
 	const list = extensions ?? [];
 	const diagnostics = [];
@@ -2607,7 +2626,7 @@ function isWellFormedNamespacedId(id) {
 	return isWellFormedId(id) && id.includes("/") && !id.startsWith("/") && !id.endsWith("/");
 }
 //#endregion
-//#region src/core-internal/assetValidation.ts
+//#region src/persistence/adapters/assetValidation.ts
 function sniffImageMediaType(bytes) {
 	if (bytes.length >= 8 && bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71 && bytes[4] === 13 && bytes[5] === 10 && bytes[6] === 26 && bytes[7] === 10) return "image/png";
 	if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return "image/jpeg";
@@ -2694,7 +2713,7 @@ function validateDecodedDimensions(width, height) {
 	};
 }
 //#endregion
-//#region src/assetController.ts
+//#region src/persistence/adapters/assetController.ts
 var FAILURE_COALESCE_MS = 4e3;
 var AssetController = class {
 	constructor(resolver, options) {
@@ -2873,7 +2892,7 @@ function toAssetResolutionError(cause, ref) {
 	return new AssetResolutionError("unknown", true, cause instanceof Error ? cause.message : String(cause), ref);
 }
 //#endregion
-//#region src/core-internal/assetExport.ts
+//#region src/persistence/serialization/assetRefCollector.ts
 /** Every unique Asset reference in the document, and which object(s) use it. */
 function collectDocumentAssetRefs(doc, registry) {
 	const refs = /* @__PURE__ */ new Map();
@@ -2900,7 +2919,7 @@ function collectSceneAssetRefs(node, objectId, add) {
 	if (node.kind === "group") for (const child of node.children) collectSceneAssetRefs(child, objectId, add);
 }
 //#endregion
-//#region src/assetExport.ts
+//#region src/persistence/serialization/assetExport.ts
 /** Strict mode's rejection — never contains credentials, a fetchable location, or a raw resolver message. */
 var SvgAssetExportError = class extends Error {
 	constructor(missingAssets) {
@@ -2909,7 +2928,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 = [];
@@ -2945,7 +2964,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
 	};
 }
@@ -2956,7 +2975,7 @@ function toDataUri(bytes, mediaType) {
 	return `data:${mediaType};base64,${btoa(binary)}`;
 }
 //#endregion
-//#region src/assetIngestion.ts
+//#region src/persistence/adapters/assetIngestion.ts
 async function decodeDimensionsWithImageBitmap(bytes, mediaType) {
 	const blob = new Blob([bytes], { type: mediaType });
 	let bitmap;
@@ -35602,7 +35621,7 @@ var WebGLRenderer = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/data/auditEvents.ts
+//#region src/core/events/auditEvents.ts
 var BY_LABEL = {
 	draw: {
 		action: "create",
@@ -35722,7 +35741,7 @@ function lowerFirst(s) {
 	return s.charAt(0).toLowerCase() + s.slice(1);
 }
 //#endregion
-//#region ../../src/scrawl/assets/AssetTextureCache.ts
+//#region src/renderer/shapes/AssetTextureCache.ts
 var AssetTextureCache = class {
 	constructor(assetController) {
 		this.assetController = assetController;
@@ -35813,7 +35832,7 @@ function toDecodeError(cause, ref) {
 	return new AssetResolutionError("decode-failed", false, cause instanceof Error ? cause.message : String(cause), ref);
 }
 //#endregion
-//#region ../../src/scrawl/engine/raycast.ts
+//#region src/renderer/canvas/raycast.ts
 var origin$1 = new Vector3();
 var target = new Vector3();
 function pointerToBoard(clientX, clientY, canvas, camera) {
@@ -35844,7 +35863,7 @@ function pointerToPlane(clientX, clientY, canvas, camera, z) {
 	};
 }
 //#endregion
-//#region ../../src/scrawl/engine/fog.ts
+//#region src/renderer/canvas/fog.ts
 function createFogUniforms(color) {
 	return {
 		uFogColor: { value: new Color(color) },
@@ -35865,7 +35884,28 @@ var FOG_GLSL = `
   }
 `;
 //#endregion
-//#region ../../src/scrawl/engine/boardSurface.ts
+//#region src/renderer/canvas/boardSurface.ts
+var GRID_MODE_CODE = {
+	none: 0,
+	line: 1,
+	dot: 2
+};
+var TEXTURE_CODE = {
+	flat: 0,
+	textured: 1
+};
+/** 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,
+	gridLineWidth: 1,
+	surfaceTexture: "flat"
+};
+/** 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() {
@@ -35879,6 +35919,13 @@ var FRAGMENT = `
   uniform vec3 uFogColor;
   uniform float uFogNear;
   uniform float uFogFar;
+  uniform float uGridMode;
+  uniform vec3 uGridColor;
+  uniform float uGridSpacing;
+  uniform float uWorldPerPixel;
+  uniform float uGridLineWidthPx;
+  uniform float uGridFade;
+  uniform float uSurfaceTexture;
   varying vec3 vWorldPos;
 
   float hash(vec2 p) {
@@ -35897,33 +35944,69 @@ var FRAGMENT = `
 
   ${FOG_GLSL}
 
+  // Distance from p's nearest axis-aligned grid line, in world units.
+  // A crisp, ~uGridLineWidthPx-wide line: full alpha to its half-width, a
+  // ~1px anti-aliased falloff beyond that — not a wide, soft-edged band.
+  float gridLineAlpha(vec2 p) {
+    vec2 cell = mod(p, uGridSpacing);
+    vec2 distToLine = min(cell, uGridSpacing - cell);
+    float halfWidth = 0.5 * uGridLineWidthPx * uWorldPerPixel;
+    float aa = uWorldPerPixel;
+    vec2 lineAlpha2 = 1.0 - smoothstep(halfWidth - aa * 0.5, halfWidth + aa * 0.5, distToLine);
+    return max(lineAlpha2.x, lineAlpha2.y);
+  }
+
+  // Distance from p's nearest grid intersection, in world units. Dot radius
+  // matches the configured line width in pixels, same anti-aliasing.
+  float gridDotAlpha(vec2 p) {
+    vec2 cell = mod(p, uGridSpacing) - uGridSpacing * 0.5;
+    float dist = length(cell);
+    float radius = uGridLineWidthPx * uWorldPerPixel;
+    float aa = uWorldPerPixel;
+    return 1.0 - smoothstep(radius - aa * 0.5, radius + aa * 0.5, dist);
+  }
+
   void main() {
     vec3 col = uColor;
 
-    // Melamine micro-texture: two octaves of value noise, +-1.75% brightness.
-    float n = vnoise(vWorldPos.xy * 2.3) * 0.6 + vnoise(vWorldPos.xy * 9.7) * 0.4;
-    col *= 1.0 + (n - 0.5) * 0.035;
+    if (uSurfaceTexture > 0.5) {
+      // Melamine micro-texture: two octaves of value noise, +-1.75% brightness.
+      float n = vnoise(vWorldPos.xy * 2.3) * 0.6 + vnoise(vWorldPos.xy * 9.7) * 0.4;
+      col *= 1.0 + (n - 0.5) * 0.035;
 
-    // Satin sheen: Fresnel rim + a specular band from the key light. Both are
-    // ~zero in the straight-on working view and bloom as the camera tilts.
-    vec3 V = normalize(cameraPosition - vWorldPos);
-    vec3 N = vec3(0.0, 0.0, 1.0);
-    float fres = pow(1.0 - max(dot(N, V), 0.0), 3.0);
-    vec3 L = normalize(vec3(-0.25, 0.4, 0.88));
-    vec3 H = normalize(L + V);
-    float spec = pow(max(dot(N, H), 0.0), 90.0);
-    col += (fres * 0.18 + spec * 0.06) * vec3(1.0);
+      // Satin sheen: Fresnel rim + a specular band from the key light. Both
+      // are ~zero in the straight-on working view and bloom as the camera tilts.
+      vec3 V = normalize(cameraPosition - vWorldPos);
+      vec3 N = vec3(0.0, 0.0, 1.0);
+      float fres = pow(1.0 - max(dot(N, V), 0.0), 3.0);
+      vec3 L = normalize(vec3(-0.25, 0.4, 0.88));
+      vec3 H = normalize(L + V);
+      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) },
+			uGridLineWidthPx: { value: Math.max(.1, theme.gridLineWidth) },
+			uWorldPerPixel: { value: .05 },
+			uGridFade: { value: 0 },
+			uSurfaceTexture: { value: TEXTURE_CODE[theme.surfaceTexture] },
 			...fog
 		}
 	});
@@ -35931,11 +36014,34 @@ 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/pixel-ratio. */
+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);
+	uniforms.uGridLineWidthPx.value = Math.max(.1, theme.gridLineWidth);
+	uniforms.uSurfaceTexture.value = TEXTURE_CODE[theme.surfaceTexture];
+}
+/** 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.uWorldPerPixel.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;
@@ -36097,9 +36203,9 @@ var CameraRig = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/engine/scene.ts
+//#region src/renderer/canvas/scene.ts
 var SceneRig = class {
-	constructor(canvas) {
+	constructor(canvas, boardTheme) {
 		this.renderer = new WebGLRenderer({
 			canvas,
 			antialias: true
@@ -36109,7 +36215,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";
@@ -36126,9 +36232,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();
@@ -36136,7 +36250,7 @@ var SceneRig = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/ink/inkMaterial.ts
+//#region src/renderer/shapes/inkMaterial.ts
 var VERTEX = `
   attribute float aAlpha;
   varying vec2 vUv;
@@ -36267,7 +36381,7 @@ var InkMaterials = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/ink/ribbonGeometry.ts
+//#region src/renderer/shapes/ribbonGeometry.ts
 /** Ink floats a hair above the board to avoid z-fighting with the surface. */
 var INK_Z = .02;
 /** Highlighter always renders under opaque ink (build prompt §4.1). */
@@ -36318,7 +36432,7 @@ function buildRibbonGeometry(points, baseWidth, z = INK_Z) {
 	return geometry;
 }
 //#endregion
-//#region ../../src/scrawl/ink/strokeRenderer.ts
+//#region src/renderer/shapes/strokeRenderer.ts
 var strokeZ = (stroke) => stroke.tool === "highlighter" ? HIGHLIGHT_Z : INK_Z;
 /**
 * Derives ink meshes from the document by subscription — the document never
@@ -36451,7 +36565,7 @@ function syncMatrix(mesh, stroke) {
 	mesh.matrixWorldNeedsUpdate = true;
 }
 //#endregion
-//#region ../../src/scrawl/scene-objects/markerProp.ts
+//#region src/renderer/shapes/markerProp.ts
 var BODY_LENGTH = 11;
 var BODY_RADIUS = .85;
 var TIP_LENGTH = 1.6;
@@ -36547,7 +36661,7 @@ var MarkerProp = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/scene-objects/noteGeometry.ts
+//#region src/renderer/shapes/noteGeometry.ts
 /**
 * Height of the sheet above the board at (u, v) ∈ [0,1]².
 * v = 1 is the adhesive edge (always 0); u = 1 is the peel corner side.
@@ -36591,7 +36705,7 @@ function applyCurl(geometry, curl, peel) {
 	color.needsUpdate = true;
 }
 //#endregion
-//#region ../../src/scrawl/scene-objects/stickyNotes.ts
+//#region src/renderer/shapes/stickyNotes.ts
 var TEXTURE_SIZE = 512;
 var FOCUS_COLOR$4 = 2450411;
 var CURL = .3;
@@ -43167,7 +43281,7 @@ SYNCABLE_PROPS.forEach((prop) => {
 new Box3();
 new Color();
 //#endregion
-//#region ../../src/scrawl/scene-objects/tables.ts
+//#region src/renderer/shapes/tables.ts
 var FONT_URL$2 = "/fonts/inter-medium.woff";
 var TABLE_Z = .012;
 var HEADER_Z = .014;
@@ -43516,7 +43630,7 @@ var TablesRenderer = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/scene-objects/textBlocks.ts
+//#region src/renderer/text/textBlocks.ts
 var FONT_URL$1 = "/fonts/inter-medium.woff";
 var TEXT_Z = .02;
 var FOCUS_COLOR$2 = 2450411;
@@ -43620,7 +43734,7 @@ var TextBlocksRenderer = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/scene-objects/comments.ts
+//#region src/renderer/shapes/comments.ts
 var PIN_Z = .04;
 var PIN_WIDTH = 3.6;
 var PIN_HEIGHT = 3.6;
@@ -43788,7 +43902,7 @@ function drawBubblePath(ctx, x, y, w, h, r, tailX, tailY, tailW) {
 	ctx.closePath();
 }
 //#endregion
-//#region ../../src/scrawl/scene-objects/images.ts
+//#region src/renderer/shapes/images.ts
 var IMAGE_Z = .015;
 var FRAME_BORDER = .4;
 var FOCUS_COLOR$1 = 2450411;
@@ -43998,7 +44112,7 @@ function applyPlaceholderTexture(visual, label) {
 	visual.imageMesh.material.needsUpdate = true;
 }
 //#endregion
-//#region ../../src/scrawl/scene-objects/kitchenTimers.ts
+//#region src/renderer/shapes/kitchenTimers.ts
 var FACE_SIZE = 256;
 var BODY_COLOR = 14753096;
 var KNOB_COLOR = 16448250;
@@ -44196,7 +44310,7 @@ function renderTimerFace(timer, canvas, now = Date.now()) {
 	return c;
 }
 //#endregion
-//#region ../../src/scrawl/scene-objects/customObjects.ts
+//#region src/renderer/shapes/customObjects.ts
 var FONT_URL = "/fonts/inter-medium.woff";
 var CUSTOM_Z = .02;
 var FOCUS_COLOR = 2450411;
@@ -44558,7 +44672,7 @@ function disposeObject3D(obj) {
 	});
 }
 //#endregion
-//#region ../../src/scrawl/tools/hitTest.ts
+//#region src/interaction/pointer/hitTest.ts
 /** Topmost (most recently added) stroke under the point, or null. */
 function hitStroke(doc, index, p, slop) {
 	const candidates = index.query(p.x - slop, p.y - slop, p.x + slop, p.y + slop);
@@ -44599,7 +44713,7 @@ function distToSegmentSq(p, a, b) {
 	return dx * dx + dy * dy;
 }
 //#endregion
-//#region ../../src/scrawl/tools/eraserTool.ts
+//#region src/interaction/tools/eraserTool.ts
 var DECAY_PER_PASS = .4;
 /** A point can take another decay pass after this long — rubbing works. */
 var REARM_MS = 250;
@@ -44727,7 +44841,7 @@ function partitionByErasure(points) {
 	return runs;
 }
 //#endregion
-//#region ../../src/scrawl/tools/noteDrag.ts
+//#region src/interaction/tools/noteDrag.ts
 /**
 * Drag the focused note in X/Y. The grab is resolved on the note's own
 * z-plane, not the board, so the note doesn't jump under a tilted ray.
@@ -44794,7 +44908,7 @@ var NoteDragState = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/imageDrag.ts
+//#region src/interaction/tools/imageDrag.ts
 /** Drag the focused image in X/Y; one command per drag. */
 var ImageDragState = class {
 	constructor(ctx) {
@@ -44846,7 +44960,7 @@ var ImageDragState = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/timerDrag.ts
+//#region src/interaction/tools/timerDrag.ts
 /** Drag the focused timer in X/Y; one command per drag. */
 var TimerDragState = class {
 	constructor(ctx) {
@@ -44898,7 +45012,7 @@ var TimerDragState = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/shapes.ts
+//#region src/interaction/tools/shapeGeometry.ts
 /** Uniform synthetic pressure; the ink shader supplies the hand-drawn feel. */
 var PRESSURE = .7;
 var MIN_ELLIPSE_SEGMENTS = 24;
@@ -45087,7 +45201,7 @@ function snappedEnd(a, b) {
 	};
 }
 //#endregion
-//#region ../../src/scrawl/tools/shapeTool.ts
+//#region src/interaction/tools/shapeTool.ts
 var MIN_DRAG_PX$1 = 4;
 /** Drag out a shape; live preview through the real ink material. */
 var ShapeTool = class {
@@ -45118,7 +45232,7 @@ var ShapeTool = class {
 			const strokes = this.polylines.map((points) => ({
 				id: crypto.randomUUID(),
 				color: this.ctx.inkColor(),
-				baseWidth: this.ctx.baseWidth(),
+				baseWidth: this.ctx.shapeStrokeWidth(),
 				points
 			}));
 			this.ctx.clusters.assign(strokes[0]);
@@ -45152,13 +45266,13 @@ var ShapeTool = class {
 			this.previews[i].visible = polyline !== void 0;
 			if (polyline) {
 				this.previews[i].geometry.dispose();
-				this.previews[i].geometry = buildRibbonGeometry(polyline, this.ctx.baseWidth());
+				this.previews[i].geometry = buildRibbonGeometry(polyline, this.ctx.shapeStrokeWidth());
 			}
 		}
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/tableDrag.ts
+//#region src/interaction/tools/tableDrag.ts
 function getHandleCursor(handle) {
 	switch (handle) {
 		case "nw":
@@ -45278,7 +45392,7 @@ var TableDragState = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/tableTool.ts
+//#region src/interaction/tools/tableTool.ts
 var MIN_DRAG_PX = 6;
 var TableTool = class {
 	constructor(ctx) {
@@ -45409,7 +45523,7 @@ var TableTool = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/commentTool.ts
+//#region src/interaction/tools/commentTool.ts
 /** Click on the board to drop a new comment pin or open an existing one. */
 var CommentTool = class {
 	constructor(ctx) {
@@ -45444,7 +45558,7 @@ var CommentTool = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/textDrag.ts
+//#region src/interaction/tools/textDrag.ts
 /** Drag the focused text block in X/Y; one command per drag. */
 var TextDragState = class {
 	constructor(ctx) {
@@ -45496,7 +45610,7 @@ var TextDragState = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/fsm.ts
+//#region src/interaction/tools/fsm.ts
 var ToolStateMachine = class {
 	constructor() {
 		this.states = /* @__PURE__ */ new Map();
@@ -45698,7 +45812,7 @@ var IdleState = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/gizmo.ts
+//#region src/renderer/selection/gizmo.ts
 var GIZMO_Z = .05;
 var HANDLE_PX = 9;
 var HANDLE_HIT_PX = 12;
@@ -45929,7 +46043,7 @@ function boxesEqual(a, b) {
 	return a.minX === b.minX && a.minY === b.minY && a.maxX === b.maxX && a.maxY === b.maxY;
 }
 //#endregion
-//#region ../../src/scrawl/ink/pressure.ts
+//#region src/interaction/tools/pressure.ts
 var SIM_MAX = 1;
 var SIM_MIN = .3;
 var SMOOTHING = .25;
@@ -45951,7 +46065,7 @@ function clamp(v, lo, hi) {
 	return Math.min(hi, Math.max(lo, v));
 }
 //#endregion
-//#region ../../src/scrawl/ink/strokeBuilder.ts
+//#region src/interaction/tools/strokeBuilder.ts
 var StrokeBuilder = class {
 	constructor() {
 		this.points = [];
@@ -46001,7 +46115,7 @@ function catmullRom(v0, v1, v2, v3, t) {
 	return .5 * (2 * v1 + (-v0 + v2) * t + (2 * v0 - 5 * v1 + 4 * v2 - v3) * t2 + (-v0 + 3 * v1 - 3 * v2 + v3) * t3);
 }
 //#endregion
-//#region ../../src/scrawl/tools/markerTool.ts
+//#region src/interaction/tools/markerTool.ts
 /** Sample spacing while drawing, in screen pixels. */
 var MIN_SAMPLE_PX = 1.5;
 /** A highlighter is a chisel tip: near-constant width, little pressure play. */
@@ -46104,7 +46218,7 @@ var MarkerTool = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/orbitTool.ts
+//#region src/interaction/tools/orbitTool.ts
 /**
 * Orbit-preview (build prompt §4.2): alt-drag tilts the camera off-axis to
 * read the board's material and depth; releasing eases back to the working
@@ -46139,7 +46253,7 @@ var OrbitTool = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/panTool.ts
+//#region src/interaction/tools/panTool.ts
 /** Grab-pan: content follows the pointer. */
 var PanTool = class {
 	constructor(ctx) {
@@ -46169,7 +46283,7 @@ var PanTool = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/selection.ts
+//#region src/renderer/selection/selection.ts
 /** The set of selected stroke ids. Drops ids the document no longer has. */
 var SelectionManager = class {
 	constructor(doc) {
@@ -46220,7 +46334,7 @@ var SelectionManager = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/tools/selectTool.ts
+//#region src/interaction/tools/selectTool.ts
 var HIT_SLOP_PX = 4;
 var CLICK_TOLERANCE_PX = 3;
 var MIN_SCALE = .05;
@@ -46436,7 +46550,7 @@ function safeRatio(numerator, denominator) {
 	return raw;
 }
 //#endregion
-//#region ../../src/scrawl/tools/customTool.ts
+//#region src/interaction/tools/customTool.ts
 function extensionIdFromToolId(toolId) {
 	const slash = toolId.indexOf("/");
 	return slash === -1 ? toolId : toolId.slice(0, slash);
@@ -46551,12 +46665,19 @@ var ExtensionCommandBatch = class {
 	}
 };
 //#endregion
-//#region ../../src/scrawl/ScrawlEngine.ts
+//#region src/composition/ScrawlEngine.ts
 /** Marker stroke width in board units (~1% of the default view height). */
 var BASE_WIDTH = .5;
 /** Highlighter chisel width — wide enough to cover a line of handwriting. */
 var HIGHLIGHT_WIDTH = 2.2;
 /**
+* Shape (rectangle, ellipse, arrow, ...) border width in board units.
+* Deliberately thinner than BASE_WIDTH: a shape border reads as a crisp,
+* structural line, not an expressive marker stroke — this is also the
+* fallback when no Host theme configures ScrawlTheme.shapeStrokeWidth.
+*/
+var DEFAULT_SHAPE_STROKE_WIDTH = .15;
+/**
 * Identity of a rendered selection badge: which item, its lock state, and
 * where it sits on screen (rounded to the pixel, so sub-pixel camera drift
 * does not churn React).
@@ -46577,9 +46698,11 @@ 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, shapeStrokeWidth = DEFAULT_SHAPE_STROKE_WIDTH) {
 		this.canvas = canvas;
 		this.extensionRegistry = extensionRegistry;
+		this.boardTheme = boardTheme;
+		this.shapeStrokeWidth = shapeStrokeWidth;
 		this.onToolChange = null;
 		this.onZoomChange = null;
 		this.onAuditEvent = null;
@@ -46626,7 +46749,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) => {
@@ -46674,6 +46797,7 @@ var ScrawlEngine = class {
 			setTool: (t) => this.setTool(t),
 			inkColor: () => this.tool === "highlighter" ? this.highlightColor : this.color,
 			baseWidth: () => this.tool === "highlighter" ? HIGHLIGHT_WIDTH : BASE_WIDTH,
+			shapeStrokeWidth: () => this.shapeStrokeWidth,
 			activeTool: () => this.tool,
 			isSpaceHeld: () => this.spaceHeld,
 			pointerToBoard: (e) => pointerToBoard(e.clientX, e.clientY, canvas, this.scene.cameraRig.camera),
@@ -46933,6 +47057,15 @@ 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);
+	}
+	/** Live update of the shape tool's border width (board units). Already-drawn shapes keep the width they were drawn with. */
+	setShapeStrokeWidth(width) {
+		this.shapeStrokeWidth = width;
+	}
 	/**
 	* Snap to a peer's camera. No-op while drawing so pointer-to-board
 	* mapping does not warp the in-progress stroke.
@@ -46951,7 +47084,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
@@ -46987,6 +47120,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;
@@ -46997,6 +47131,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;
@@ -47992,7 +48127,7 @@ var ScrawlEngine = class {
 	}
 };
 //#endregion
-//#region src/controller-internal.ts
+//#region src/composition/controller-internal.ts
 function createBoardController(options) {
 	return createBoardControllerWithEngine(options);
 }
@@ -48006,7 +48141,16 @@ 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,
+		gridLineWidth: options.boardTheme?.gridLineWidth ?? DEFAULT_BOARD_SURFACE_THEME.gridLineWidth,
+		surfaceTexture: options.boardTheme?.surfaceTexture ?? DEFAULT_BOARD_SURFACE_THEME.surfaceTexture
+	};
+	let currentShapeStrokeWidth = options.boardTheme?.shapeStrokeWidth ?? .15;
+	const engine = existingEngine ?? (options.canvas ? new ScrawlEngine(options.canvas, options.document.id, extensionRegistry, assetController, currentBoardTheme, currentShapeStrokeWidth) : null);
 	const document = engine?.document ?? new BoardDocument(documentId(options.document.id));
 	const history = engine?.history ?? new History(document);
 	const createId = options.createId ?? (() => crypto.randomUUID());
@@ -48490,6 +48634,21 @@ 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,
+				gridLineWidth: theme.gridLineWidth ?? currentBoardTheme.gridLineWidth,
+				surfaceTexture: theme.surfaceTexture ?? currentBoardTheme.surfaceTexture
+			};
+			engine?.applyBoardTheme(currentBoardTheme);
+			if (theme.shapeStrokeWidth !== void 0) {
+				currentShapeStrokeWidth = theme.shapeStrokeWidth;
+				engine?.setShapeStrokeWidth(currentShapeStrokeWidth);
+			}
+		} },
 		view: {
 			fit() {
 				assertActive();
@@ -48794,10 +48953,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();
@@ -49259,7 +49418,7 @@ function createLocalBoard(options) {
 	};
 }
 //#endregion
-//#region src/theme.ts
+//#region src/ui/theme.ts
 var scrawlThemePresets = Object.freeze({
 	light: Object.freeze({
 		surface: "#ffffff",
@@ -49284,7 +49443,14 @@ var scrawlThemePresets = Object.freeze({
 		elevationHigh: "0 8px 20px rgba(28, 28, 26, 0.18)",
 		motionDuration: 140,
 		motionEasing: "cubic-bezier(0.2, 0, 0, 1)",
-		density: "comfortable"
+		density: "comfortable",
+		boardSurface: "#f5f5f3",
+		boardSurfaceTexture: "flat",
+		gridMode: "none",
+		gridColor: "#deded8",
+		gridSpacing: 5,
+		gridLineWidth: 1,
+		shapeStrokeWidth: .15
 	}),
 	dark: Object.freeze({
 		surface: "#171816",
@@ -49309,7 +49475,14 @@ var scrawlThemePresets = Object.freeze({
 		elevationHigh: "0 8px 20px rgba(0, 0, 0, 0.38)",
 		motionDuration: 140,
 		motionEasing: "cubic-bezier(0.2, 0, 0, 1)",
-		density: "comfortable"
+		density: "comfortable",
+		boardSurface: "#232420",
+		boardSurfaceTexture: "flat",
+		gridMode: "none",
+		gridColor: "#33352f",
+		gridSpacing: 5,
+		gridLineWidth: 1,
+		shapeStrokeWidth: .15
 	})
 });
 var variableNames = {
@@ -49335,7 +49508,14 @@ var variableNames = {
 	elevationHigh: "--scrawl-elevation-high",
 	motionDuration: "--scrawl-motion-duration",
 	motionEasing: "--scrawl-motion-easing",
-	density: "--scrawl-density"
+	density: "--scrawl-density",
+	boardSurface: "--scrawl-board-surface",
+	boardSurfaceTexture: "--scrawl-board-surface-texture",
+	gridMode: "--scrawl-grid-mode",
+	gridColor: "--scrawl-grid-color",
+	gridSpacing: "--scrawl-grid-spacing",
+	gridLineWidth: "--scrawl-grid-line-width",
+	shapeStrokeWidth: "--scrawl-shape-stroke-width"
 };
 var colorTokens = /* @__PURE__ */ new Set([
 	"surface",
@@ -49348,7 +49528,9 @@ var colorTokens = /* @__PURE__ */ new Set([
 	"selection",
 	"danger",
 	"warning",
-	"success"
+	"success",
+	"boardSurface",
+	"gridColor"
 ]);
 var knownTokens = new Set(Object.keys(scrawlThemePresets.light));
 function validateScrawlTheme(theme) {
@@ -49385,6 +49567,26 @@ function validateScrawlTheme(theme) {
 			token,
 			message: "Expected comfortable or compact"
 		});
+		else if (token === "gridMode" && value !== "none" && value !== "line" && value !== "dot") diagnostics.push({
+			token,
+			message: "Expected none, line, or dot"
+		});
+		else if (token === "boardSurfaceTexture" && value !== "flat" && value !== "textured") diagnostics.push({
+			token,
+			message: "Expected flat or textured"
+		});
+		else if (token === "gridSpacing" && (!finiteNumber(value) || value < .5 || value > 50)) diagnostics.push({
+			token,
+			message: "Expected spacing 0.5-50 board units"
+		});
+		else if (token === "gridLineWidth" && (!finiteNumber(value) || value < .5 || value > 8)) diagnostics.push({
+			token,
+			message: "Expected line width 0.5-8px"
+		});
+		else if (token === "shapeStrokeWidth" && (!finiteNumber(value) || value < .01 || value > 5)) diagnostics.push({
+			token,
+			message: "Expected stroke width 0.01-5 board units"
+		});
 		else if ((token.endsWith("Family") || token.startsWith("elevation") || token === "motionEasing") && (typeof value !== "string" || !value.trim() || /[;{}]/.test(value))) diagnostics.push({
 			token,
 			message: "Expected a safe CSS value"
@@ -49455,12 +49657,12 @@ function luminance(color) {
 	return channels[0] * .2126 + channels[1] * .7152 + channels[2] * .0722;
 }
 function formatValue(token, value) {
-	if (token === "baseFontSize" || token === "controlRadius" || token === "panelRadius") return `${value}px`;
+	if (token === "baseFontSize" || token === "controlRadius" || token === "panelRadius" || token === "gridLineWidth") return `${value}px`;
 	if (token === "motionDuration") return `${value}ms`;
 	return String(value);
 }
 //#endregion
-//#region src/inline-editing.tsx
+//#region src/ui/dialogs/inline-editing.tsx
 /** Inline note, text, and table-cell editors — driven entirely by public controller events and commands. */
 function InlineEditors({ controller, renderPortal }) {
 	const [editor, setEditor] = useState(null);
@@ -49691,7 +49893,7 @@ function InlineEditors({ controller, renderPortal }) {
 	}))] });
 }
 //#endregion
-//#region src/style-shelf.tsx
+//#region src/ui/toolbar/style-shelf.tsx
 var ERASER_RADII = [
 	["Fine", 1],
 	["Medium", 2],
@@ -49854,7 +50056,7 @@ function StyleShelf({ controller, snapshot }) {
 	});
 }
 //#endregion
-//#region src/default-ui.tsx
+//#region src/ui/default-ui.tsx
 var PRIMARY_TOOLS = [
 	{
 		tool: "select",
@@ -50383,7 +50585,7 @@ function download(blob, name) {
 	URL.revokeObjectURL(url);
 }
 //#endregion
-//#region src/presence.tsx
+//#region src/ui/panels/presence.tsx
 var labelStyle = {
 	borderRadius: 999,
 	color: "#fff",
@@ -50540,6 +50742,17 @@ function ScrawlProvider({ controller, children, preset = "light", theme, portalC
 		style
 	]);
 	useEffect(() => reportThemeDiagnostics(resolved.diagnostics, onThemeDiagnostic), [resolved, onThemeDiagnostic]);
+	useEffect(() => {
+		controller.boardTheme.set({
+			surface: resolved.values.boardSurface,
+			surfaceTexture: resolved.values.boardSurfaceTexture,
+			gridMode: resolved.values.gridMode,
+			gridColor: resolved.values.gridColor,
+			gridSpacing: resolved.values.gridSpacing,
+			gridLineWidth: resolved.values.gridLineWidth,
+			shapeStrokeWidth: resolved.values.shapeStrokeWidth
+		});
+	}, [controller, resolved]);
 	useDeferredDisposal(controller, disposeOnUnmount);
 	const value = useMemo(() => ({
 		controller,
@@ -50587,8 +50800,19 @@ function Scrawl({ children, preset, theme, portalContainer, className, style, on
 		try {
 			if (!runtimeRef.current) {
 				const canvas = suppliedCanvas === void 0 ? ownedCanvasRef.current : suppliedCanvas;
+				const resolved = resolveScrawlTheme(preset, theme);
+				const boardTheme = {
+					surface: resolved.values.boardSurface,
+					surfaceTexture: resolved.values.boardSurfaceTexture,
+					gridMode: resolved.values.gridMode,
+					gridColor: resolved.values.gridColor,
+					gridSpacing: resolved.values.gridSpacing,
+					gridLineWidth: resolved.values.gridLineWidth,
+					shapeStrokeWidth: resolved.values.shapeStrokeWidth
+				};
 				controller = createBoardController({
 					...options,
+					boardTheme,
 					...canvas ? { canvas } : {}
 				});
 				runtimeRef.current = {
@@ -50824,4 +51048,4 @@ function ScrawlBoard({ documentId, initialDocument, onReady, className, style })
 	});
 }
 //#endregion
-export { AddImageCommand, AddNoteCommand, AddStrokesCommand, AddTableCommand, AddTextCommand, AddTimerCommand, BEACON_INSET, BOARD_COLOR, BoardDocument, CURRENT_DOCUMENT_SCHEMA_VERSION, ClusterStore, DefaultBoardChrome, DeleteImageCommand, DeleteNoteCommand, DeleteStrokesCommand, DeleteTableCommand, DeleteTextCommand, DeleteTimerCommand, DocumentRecoveryError, END_TAPER, ERASE_THRESHOLD, EraseCommand, FOG_COLOR, HIGHLIGHT_COLORS, History, IDENTITY, INK_COLORS, InlineEditors, LockItemsCommand, MIN_WIDTH_FACTOR, MultiplayerCursors, 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, Scrawl, ScrawlBoard, ScrawlCanvas, ScrawlDefaultUI, ScrawlPortal, ScrawlProvider, SpatialIndex, StyleShelf, 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, createBoardController, createLocalBoard, documentId, documentToSVG, formatTimer, invert, isIdentity, isStampKind, loadDocumentBytes, measureTable, measureTextBlock, migrateDocument, mul, pauseTimer, placePresenceBeacon, resolveScrawlTheme, ribbonEdges, rotationAbout, scalingAbout, scrawlThemePresets, searchBoard, serializeDocument, serializeLock, serializeStroke, setTimerDuration, stampDataUrl, startTimer, strokeId, timerExpired, timerRemaining, toggleTimer, translation, useScrawlController, useScrawlSnapshot, useScrawlTheme, validateScrawlTheme };
+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, DefaultBoardChrome, DeleteImageCommand, DeleteNoteCommand, DeleteStrokesCommand, DeleteTableCommand, DeleteTextCommand, DeleteTimerCommand, DocumentRecoveryError, END_TAPER, ERASE_THRESHOLD, EraseCommand, FOG_COLOR, HIGHLIGHT_COLORS, History, IDENTITY, INK_COLORS, InlineEditors, LockItemsCommand, MIN_WIDTH_FACTOR, MultiplayerCursors, 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, Scrawl, ScrawlBoard, ScrawlCanvas, ScrawlDefaultUI, ScrawlPortal, ScrawlProvider, SpatialIndex, StyleShelf, 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, createBoardController, createLocalBoard, documentId, documentToSVG, formatTimer, invert, isAssetRef, isIdentity, isStampKind, loadDocumentBytes, measureTable, measureTextBlock, migrateDocument, mul, pauseTimer, placePresenceBeacon, resolveScrawlTheme, ribbonEdges, rotationAbout, scalingAbout, scrawlThemePresets, searchBoard, serializeDocument, serializeLock, serializeStroke, setTimerDuration, stampDataUrl, startTimer, strokeId, timerExpired, timerRemaining, toggleTimer, translation, useScrawlController, useScrawlSnapshot, useScrawlTheme, validateScrawlTheme };