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

package/dist/react.d.ts

@@ -685,6 +685,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
@@ -895,12 +916,7 @@ interface CreateBoardControllerOptions {
      * 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;
-    };
+    boardTheme?: BoardThemeOptions;
 }
 interface BoardController {
     readonly document: ReadonlyBoardDocument;
@@ -927,13 +943,8 @@ interface BoardController {
         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;
+        /** 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;
@@ -1032,37 +1043,75 @@ type LocalBoard = {
 type ScrawlThemePreset = "light" | "dark";
 type ScrawlDensity = "comfortable" | "compact";
 type ScrawlGridMode = "none" | "line" | "dot";
+type ScrawlSurfaceTexture = "flat" | "textured";
+/**
+ * Every field is optional — anything you don't set falls back to the
+ * chosen `preset` ("light" or "dark", see {@link resolveScrawlTheme}).
+ * Overrides are semantic, board-local runtime configuration: they never
+ * get written into the Document or into exports, so switching themes is
+ * always non-destructive.
+ */
 interface ScrawlTheme {
+    /** UI chrome background — toolbar/panel base surface. Distinct from `boardSurface` (the canvas itself). */
     surface?: string;
+    /** UI chrome background, one step up from `surface` — popovers, dropdowns, elevated panels. */
     surfaceRaised?: string;
+    /** UI chrome background, one step down from `surface` — subtle fills, hover states. */
     surfaceMuted?: string;
+    /** Primary UI text color. Checked for contrast against `surface`. */
     text?: string;
+    /** Secondary/de-emphasized UI text color. Checked for contrast against `surface`. */
     textMuted?: string;
+    /** Borders and dividers between UI chrome elements. */
     edge?: string;
+    /** Focus ring color. Checked for contrast against `surface`. */
     focus?: string;
+    /** Selection highlight color (e.g. selected list items, not board object selection). */
     selection?: string;
+    /** Destructive/error state color (delete confirmations, error text). */
     danger?: string;
+    /** Warning state color. */
     warning?: string;
+    /** Success/confirmation state color. */
     success?: string;
+    /** Font stack for UI chrome (toolbar labels, menus, dialogs). */
     uiFontFamily?: string;
+    /** Font stack for board content and data (e.g. table cell text). */
     dataFontFamily?: string;
+    /** Base UI font size in px. Range: 12–24. */
     baseFontSize?: number;
+    /** Regular UI font weight. Range: 300–900. */
     regularWeight?: number;
+    /** Emphasized UI font weight (headings, active states). Range: 300–900. */
     strongWeight?: number;
+    /** Corner radius for small controls (buttons, inputs) in px. Range: 0–32. */
     controlRadius?: number;
+    /** Corner radius for panels/dialogs in px. Range: 0–32. */
     panelRadius?: number;
+    /** CSS `box-shadow` value for subtle elevation (e.g. toolbar). */
     elevationLow?: string;
+    /** CSS `box-shadow` value for prominent elevation (e.g. modals). */
     elevationHigh?: string;
+    /** UI transition duration in ms. Range: 0–500. */
     motionDuration?: number;
+    /** CSS easing function for UI transitions. */
     motionEasing?: string;
+    /** UI chrome spacing/sizing scale. */
     density?: ScrawlDensity;
     /** The rendered board/canvas surface color — distinct from `surface` (UI chrome panels). */
     boardSurface?: string;
+    /** `"flat"` (default): a plain, uniform board surface. `"textured"`: a subtle "melamine" micro-noise + satin sheen, like a physical whiteboard. */
+    boardSurfaceTexture?: ScrawlSurfaceTexture;
     /** `"none"` (default) keeps the board a plain surface; `"line"`/`"dot"` draw a zoom-adaptive reference grid. */
     gridMode?: ScrawlGridMode;
+    /** Grid line/dot color. Ignored when `gridMode` is `"none"`. */
     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. Range: 0.5–8. A reference aid, so unlike shape/ink strokes it stays this width at any zoom. */
+    gridLineWidth?: number;
+    /** Shape (rectangle, ellipse, arrow, ...) border width, in board units. Range: 0.01–5. Scales with zoom like ink, since it's part of the drawn content. */
+    shapeStrokeWidth?: number;
 }
 type ResolvedScrawlTheme = Required<ScrawlTheme>;
 interface ScrawlThemeDiagnostic {
@@ -1207,4 +1256,4 @@ type ScrawlBoardProps = {
 declare function ScrawlBoard({ documentId, initialDocument, onReady, className, style }: ScrawlBoardProps): react.JSX.Element;
 
 export { AssetResolutionError, DefaultBoardChrome, InlineEditors, MultiplayerCursors, SUPPORTED_ASSET_MEDIA_TYPES, Scrawl, ScrawlBoard, ScrawlCanvas, ScrawlDefaultUI, ScrawlPortal, ScrawlProvider, StyleShelf, assetRef, clampAssetCacheBytes, cloneCustomObject, isAssetRef, resolveScrawlTheme, scrawlThemePresets, useScrawlController, useScrawlSnapshot, useScrawlTheme, validateScrawlTheme };
-export type { AssetDiagnostic, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BoardController, BoardKeyInput, BoardPointerInput, BoardScene, BoardSlotProps, BoardSnapshot, BoardStyle, CommentMarker, CreateBoardControllerOptions, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DefaultBoardChromeProps, DefaultUIRegion, DefaultUISlot, DefaultUISlots, DialogSlotProps, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, InlineEditorsProps, InputModifiers, JsonObject, JsonValue, LocalBoard, LocalBoardSnapshot, Mat2x3, MultiplayerCursorsProps, ObjectDescribeContext, ObjectIntent, ObjectType, PresenceCursor, PresenceUser, PresenceView, QueryableBoardObject, ReadonlyCustomObject, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlBoardProps, ScrawlCanvasProps, ScrawlDefaultUIProps, ScrawlDensity, ScrawlExtension, ScrawlGridMode, ScrawlProps, ScrawlProviderProps, ScrawlResolvedTheme, ScrawlTheme, ScrawlThemeDiagnostic, ScrawlThemePreset, StyleShelfProps, SupportedAssetMediaType, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId };
+export type { AssetDiagnostic, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BoardController, BoardKeyInput, BoardPointerInput, BoardScene, BoardSlotProps, BoardSnapshot, BoardStyle, BoardThemeOptions, CommentMarker, CreateBoardControllerOptions, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DefaultBoardChromeProps, DefaultUIRegion, DefaultUISlot, DefaultUISlots, DialogSlotProps, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, InlineEditorsProps, InputModifiers, JsonObject, JsonValue, LocalBoard, LocalBoardSnapshot, Mat2x3, MultiplayerCursorsProps, ObjectDescribeContext, ObjectIntent, ObjectType, PresenceCursor, PresenceUser, PresenceView, QueryableBoardObject, ReadonlyCustomObject, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlBoardProps, ScrawlCanvasProps, ScrawlDefaultUIProps, ScrawlDensity, ScrawlExtension, ScrawlGridMode, ScrawlProps, ScrawlProviderProps, ScrawlResolvedTheme, ScrawlSurfaceTexture, ScrawlTheme, ScrawlThemeDiagnostic, ScrawlThemePreset, StyleShelfProps, SupportedAssetMediaType, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId };