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

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
@@ -676,6 +689,27 @@ interface BoardView {
     y: number;
     zoom: number;
 }
+/**
+ * The rendered board surface's color, reference grid, and shape stroke
+ * width — the subset of {@link ScrawlTheme} that reaches the rendering
+ * engine directly (everything else is UI-chrome-only, applied as CSS). Any
+ * field left unset keeps its current value.
+ */
+interface BoardThemeOptions {
+    /** The board/canvas background color — distinct from UI chrome panels. */
+    surface?: string;
+    /** `"flat"` (default): a plain, uniform board surface. `"textured"`: a subtle "melamine" micro-noise + satin sheen, like a physical whiteboard. */
+    surfaceTexture?: "flat" | "textured";
+    /** `"none"` (default) keeps the board a plain surface; `"line"`/`"dot"` draw a zoom-adaptive reference grid. */
+    gridMode?: "none" | "line" | "dot";
+    gridColor?: string;
+    /** Grid spacing in board units at 100% zoom. Ignored when `gridMode` is `"none"`. */
+    gridSpacing?: number;
+    /** On-screen grid line/dot width in CSS pixels — stays this width at any zoom, since the grid is a reference aid, not content. */
+    gridLineWidth?: number;
+    /** Shape (rectangle, ellipse, arrow, ...) border width, in board units — scales with zoom like ink, since it's part of the drawn content. */
+    shapeStrokeWidth?: number;
+}
 /**
  * A Host-owned comment, summarized for Board-side search and marker
  * rendering. Comments are not Document content — they carry no undo
@@ -867,22 +901,26 @@ 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?: BoardThemeOptions;
 }
 interface BoardController {
     readonly document: ReadonlyBoardDocument;
@@ -908,6 +946,10 @@ interface BoardController {
         undo(): void;
         redo(): void;
     };
+    readonly boardTheme: {
+        /** Live update of the board surface color/grid/shape-stroke-width — the controller's identity stays fixed across theme changes. */
+        set(theme: BoardThemeOptions): void;
+    };
     readonly view: {
         fit(): void;
         zoomTo(value: number): void;
@@ -1008,5 +1050,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, BoardThemeOptions, 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 };