@fieldnotes/core 0.65.0 → 0.66.0

package/dist/index.d.cts

@@ -267,7 +267,7 @@ interface Tool {
     setOptions?(options: object): void;
     onOptionsChange?(listener: () => void): () => void;
 }
-type ToolName = 'hand' | 'select' | 'pencil' | 'eraser' | 'arrow' | 'note' | 'image' | 'text' | 'shape' | 'measure' | 'path' | 'template' | 'laser' | 'ping';
+type ToolName = 'hand' | 'select' | 'pencil' | 'eraser' | 'arrow' | 'note' | 'image' | 'text' | 'shape' | 'measure' | 'path' | 'template' | 'laser' | 'ping' | 'fog';
 
 declare function snapPoint(point: Point, gridSize: number): Point;
 declare function snapToHexCenter(point: Point, cellSize: number, orientation: HexOrientation): Point;
@@ -341,6 +341,61 @@ interface Layer {
     opacity: number;
 }
 
+declare const FOG_STATE_VERSION = 1;
+declare const FOG_TILE_CELLS = 128;
+declare const FOG_MAX_TILES = 256;
+type FogBase = 'covered' | 'revealed';
+interface FogDefinitionV1 {
+    readonly version: 1;
+    readonly generation: string;
+    readonly bounds: Bounds;
+    readonly cellSize: number;
+    readonly tileCells: 128;
+    readonly base: FogBase;
+}
+interface FogTileV1 {
+    readonly x: number;
+    readonly y: number;
+    readonly data: string;
+}
+interface FogStateV1 {
+    readonly definition: FogDefinitionV1;
+    readonly tiles: readonly FogTileV1[];
+}
+type FogViewMode = 'off' | 'editor' | 'player';
+type FogOperation = 'reveal' | 'conceal';
+type FogRegion = {
+    kind: 'brush';
+    points: readonly Point[];
+    radius: number;
+} | {
+    kind: 'rectangle';
+    from: Point;
+    to: Point;
+} | {
+    kind: 'polygon';
+    points: readonly Point[];
+};
+interface FogToolOptions {
+    operation?: FogOperation;
+    shape?: 'brush' | 'rectangle' | 'polygon';
+    radius?: number;
+}
+interface FogPatch {
+    readonly tiles: readonly FogTileV1[];
+}
+interface FogChangeEvent {
+    readonly kind: 'tiles' | 'definition' | 'reset' | 'disable';
+    readonly tiles?: readonly {
+        readonly x: number;
+        readonly y: number;
+    }[];
+    readonly origin?: string;
+}
+interface FogViewEvent {
+    readonly mode: FogViewMode;
+}
+
 interface CanvasState {
     version: number;
     camera: {
@@ -350,6 +405,7 @@ interface CanvasState {
     elements: CanvasElement[];
     layers?: Layer[];
     activeLayerId?: string;
+    fog?: FogStateV1;
 }
 
 interface LayerManagerEvents {
@@ -392,6 +448,55 @@ declare class LayerManager {
     private findFallbackLayer;
 }
 
+interface Command {
+    execute(store: ElementStore): void;
+    undo(store: ElementStore): void;
+}
+
+type FogIdFactory = () => string;
+interface FogManagerOptions {
+    idFactory?: FogIdFactory;
+    onCommand?: (command: Command) => void;
+}
+type ChangeListener = (event: FogChangeEvent) => void;
+type ViewListener = (event: FogViewEvent) => void;
+declare class FogManager {
+    private state;
+    private viewMode;
+    private readonly idFactory;
+    private readonly onCommand;
+    private readonly changeListeners;
+    private readonly viewListeners;
+    constructor(options?: FogManagerOptions);
+    getState(): FogStateV1 | null;
+    getViewMode(): FogViewMode;
+    initialize(options: {
+        bounds: Bounds;
+        base?: FogBase;
+        cellSize?: number;
+    }): FogStateV1;
+    loadState(state: FogStateV1 | null, meta?: {
+        origin?: string;
+    }): void;
+    /** Restores a historical visual state without reusing its causal generation id. */
+    restoreHistoryState(state: FogStateV1 | null): void;
+    setBounds(bounds: Bounds): void;
+    reset(base: FogBase): void;
+    disable(): void;
+    setViewMode(mode: FogViewMode): void;
+    applyRegion(region: FogRegion, operation: FogOperation): void;
+    applyPatchDirect(patch: FogPatch, meta?: {
+        origin?: string;
+    }): void;
+    applyTilesDirect(tiles: readonly FogTileV1[]): void;
+    on(event: 'change', listener: ChangeListener): () => void;
+    on(event: 'view', listener: ViewListener): () => void;
+    dispose(): void;
+    private collectTiles;
+    private notifyChange;
+    private notifyView;
+}
+
 interface StorageAdapter {
     load(key: string): Promise<string | null>;
     save(key: string, value: string): Promise<void>;
@@ -402,6 +507,7 @@ interface AutoSaveOptions {
     key?: string;
     debounceMs?: number;
     layerManager?: LayerManager;
+    fogManager?: FogManager;
     adapter?: StorageAdapter;
     onError?: (error: Error) => void;
 }
@@ -411,6 +517,7 @@ declare class AutoSave {
     private readonly key;
     private readonly debounceMs;
     private readonly layerManager?;
+    private readonly fogManager?;
     private readonly adapter;
     private timerId;
     private unsubscribers;
@@ -502,11 +609,6 @@ declare class ToolManager {
     onRegister(listener: (tool: Tool) => void): () => void;
 }
 
-interface Command {
-    execute(store: ElementStore): void;
-    undo(store: ElementStore): void;
-}
-
 interface HistoryStackOptions {
     maxSize?: number;
 }
@@ -635,6 +737,11 @@ interface ExportImageOptions extends ExportResourceOptions, HtmlExportOptions {
      * a non-fatal `'unsupported'` diagnostic regardless of this flag.
      */
     strictMissingCanvasHtml?: boolean;
+    fog?: {
+        state: FogStateV1;
+        mode: 'editor' | 'player';
+        color?: string;
+    } | false;
 }
 type ExportAssetErrorReason = 'load' | 'timeout' | 'encode';
 interface ExportAssetError {
@@ -660,20 +767,14 @@ interface ExportSvgOptions extends ExportResourceOptions, HtmlExportOptions {
     background?: string;
     filter?: (el: CanvasElement) => boolean;
     rasterScale?: number;
-    /** Registry of canvas-backed html painters, keyed by `htmlType`. When absent (or when
-     *  an element's `htmlType` isn't claimed), html elements fall back to the legacy
-     *  DOM-raster path (`renderHtml`). */
     htmlPainters?: HtmlPainterRegistry;
-    /** `htmlType`s that must route to canvas even before a painter for them is
-     *  registered — lets a host declare intent up front (mirrors `HtmlPainterRegistry.expect`). */
     expectedCanvasTypes?: ReadonlySet<string>;
-    /**
-     * When true, a canvas-routed html element with no active painter throws
-     * `HtmlPainterMissingError` instead of reporting `onHtmlError` and continuing.
-     * DOM-routed html elements are never affected — a missing `renderHtml` stays
-     * a non-fatal `'unsupported'` diagnostic regardless of this flag.
-     */
     strictMissingCanvasHtml?: boolean;
+    fog?: {
+        state: FogStateV1;
+        mode: 'editor' | 'player';
+        color?: string;
+    } | false;
 }
 declare function exportSvg(store: ElementStore, options?: ExportSvgOptions, layerManager?: LayerManager): Promise<string>;
 
@@ -699,6 +800,33 @@ interface RenderStatsSnapshot {
     frameCount: number;
 }
 
+interface FogRendererOptions {
+    editorColor?: string;
+    playerColor?: string;
+}
+declare class FogRenderer {
+    private tileCache;
+    private state;
+    private viewMode;
+    private dirty;
+    private editorColor;
+    private playerColor;
+    constructor(options?: FogRendererOptions);
+    setState(state: FogStateV1 | null): void;
+    setViewMode(mode: FogViewMode): void;
+    getState(): FogStateV1 | null;
+    getViewMode(): FogViewMode;
+    markDirty(): void;
+    isDirty(): boolean;
+    isVisible(): boolean;
+    render(ctx: CanvasRenderingContext2D, camera: Camera, viewportWidth: number, viewportHeight: number, _dpr: number): void;
+    renderForExport(ctx: CanvasRenderingContext2D, state: FogStateV1, mode: 'editor' | 'player', color?: string): void;
+    dispose(): void;
+    private tileRaster;
+    private renderTile;
+    private renderTileForExport;
+}
+
 /**
  * A world-space draw callback rendered above elements on every frame,
  * regardless of which tool is active. The context arrives with the camera
@@ -789,6 +917,11 @@ interface ViewportOptions {
     panInertia?: boolean;
     /** Show an overview minimap (bottom-right) with tap/drag-to-navigate. Default `false`. */
     minimap?: boolean;
+    /** Fog-of-war presentation options. Enables fog rendering and the `fog` accessor. */
+    fog?: {
+        editorColor?: string;
+        playerColor?: string;
+    };
 }
 interface HitTestOptions {
     /** Skip elements on locked layers. Default `true` (selection semantics). */
@@ -825,6 +958,8 @@ declare class Viewport {
     private _smartGuides;
     private readonly _gridSize;
     private readonly renderLoop;
+    private readonly fogManager;
+    private readonly fogRenderer;
     private readonly domNodeManager;
     private readonly interactMode;
     private readonly onHtmlElementMount?;
@@ -850,6 +985,7 @@ declare class Viewport {
     private unsubRecorderEnd;
     constructor(container: HTMLElement, options?: ViewportOptions);
     get ctx(): CanvasRenderingContext2D | null;
+    get fog(): FogManager;
     get snapToGrid(): boolean;
     setSnapToGrid(enabled: boolean): void;
     get smartGuides(): boolean;
@@ -2087,6 +2223,8 @@ declare class MinimapController {
     private readonly renderer;
     private readonly htmlPainters;
     private scene;
+    private fogRenderer;
+    private fogUnsub;
     private frameId;
     private debounceTimer;
     private dragging;
@@ -2094,6 +2232,7 @@ declare class MinimapController {
     private readonly unsubs;
     constructor(viewport: Viewport, canvas: HTMLCanvasElement, options?: MinimapControllerOptions);
     setSize(width: number, height: number): void;
+    setFogRenderer(renderer: FogRenderer | null): void;
     requestDraw(): void;
     /**
      * Invalidates the cached scene bitmap in response to html-painter registry
@@ -3039,6 +3178,43 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.65.0";
+declare function encodeBase64(bytes: Uint8Array): string;
+declare function decodeBase64(str: string): Uint8Array;
+declare function canonicalizeFogTile(tile: FogTileV1, def: FogDefinitionV1): FogTileV1 | null;
+declare function validateFogDefinition(def: unknown): asserts def is FogDefinitionV1;
+declare function validateFogTile(tile: unknown, def: FogDefinitionV1): asserts tile is FogTileV1;
+declare function validateFogState(state: unknown): asserts state is FogStateV1;
+declare function recommendedFogCellSize(bounds: Bounds): number;
+
+declare class FogTool implements Tool {
+    readonly name = "fog";
+    private drawing;
+    private points;
+    private startPoint;
+    private operation;
+    private shape;
+    private radius;
+    private readonly manager;
+    private optionListeners;
+    constructor(manager: FogManager, options?: FogToolOptions);
+    onActivate(ctx: ToolContext): void;
+    onDeactivate(ctx: ToolContext): void;
+    getOptions(): FogToolOptions;
+    setOptions(options: FogToolOptions): void;
+    onOptionsChange(listener: () => void): () => void;
+    onPointerDown(state: PointerState, ctx: ToolContext): void;
+    onPointerMove(state: PointerState, ctx: ToolContext): void;
+    onPointerUp(_state: PointerState, ctx: ToolContext): void;
+    onPointerCancel(_state: PointerState, ctx: ToolContext): void;
+    onKeyDown(event: KeyboardEvent, ctx: ToolContext): boolean;
+    renderOverlay(ctx: CanvasRenderingContext2D): void;
+    private buildRegion;
+    private cancelGesture;
+    private renderBrushPreview;
+    private renderRectanglePreview;
+    private renderPolygonPreview;
+}
+
+declare const VERSION = "0.66.0";
 
-export { AWARENESS_MAX_SELECTION, AWARENESS_PRESENCE_KIND, type ActivationOptions, type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, type AttachAwarenessOptions, AutoSave, type AutoSaveOptions, type AwarenessFields, type AwarenessHandle, type AwarenessIdentity, type AwarenessPresence, type AwarenessViewport, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraAnimationEndReason, CameraAnimator, type CameraAnimatorOptions, type CameraChangeInfo, type CameraOptions, type CameraView, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DiagonalRule, type DistributeAxis, type ElementActivationEvent, type ElementChangeMeta, type ElementRect, type ElementRectMatch, type ElementRectMatchError, ElementRectTracker, type ElementRectTrackerOptions, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, FOCUS_PRESENCE_KIND, type FocusAudience, type FocusPresence, type FocusRole, type FontSizePreset, type Footprint, type FrameScheduler, type GridElement, type GridInfo, type GridMetric, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HitTestOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type HtmlPaintContext, type HtmlPaintDiagnostic, type HtmlPainter, HtmlPainterMissingError, HtmlPainterRegistry, type HtmlRenderTarget, type HtmlRouting, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalAwareness, type LocalAwarenessHost, type LocalAwarenessOptions, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, MinimapController, type MinimapControllerOptions, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PATH_PRESENCE_KIND, PATH_PRESENCE_MAX_POINTS, PEER_COLORS, PING_PRESENCE_KIND, type PathAnchor, type PathDistance, type PathEmission, type PathPresence, type PathRangeBand, type PathSegment, PathTool, type PathToolOptions, type Peer, type PeerLeaveReason, PeerRoster, type PeerRosterOptions, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, type PresenceChannel, type RectTrackerHost, RemoteCursorOverlay, type RemoteCursorOverlayHost, type RemoteCursorOverlayOptions, RemoteFocusReceiver, type RemoteFocusReceiverHost, type RemoteFocusReceiverOptions, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePathOverlay, type RemotePathOverlayHost, type RemotePathOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, RemoteSelectionOverlay, type RemoteSelectionOverlayHost, type RemoteSelectionOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type SelectionStyleDetails, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, applyCameraView, attachAwareness, boundsIntersect, cameraOriginForView, captureCameraView, computeElementRects, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, defaultPeerColor, drawHexPath, elementRectsEqual, exportImage, exportSvg, fitZoomForView, footprintFromSize, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, gridDistanceCells, isAwarenessPresence, isFocusPresence, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPathPresence, isPingPresence, pathDistanceCells, resolveHtmlRouting, setFontSize, smartSnap, snapFootprintCenter, snapPoint, snapToCellCenter, snapToHexCenter, styleToPatch, toFocusPresence, toLaserTrailPresence, toMeasurePresence, toPathPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+export { AWARENESS_MAX_SELECTION, AWARENESS_PRESENCE_KIND, type ActivationOptions, type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, type AttachAwarenessOptions, AutoSave, type AutoSaveOptions, type AwarenessFields, type AwarenessHandle, type AwarenessIdentity, type AwarenessPresence, type AwarenessViewport, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraAnimationEndReason, CameraAnimator, type CameraAnimatorOptions, type CameraChangeInfo, type CameraOptions, type CameraView, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DiagonalRule, type DistributeAxis, type ElementActivationEvent, type ElementChangeMeta, type ElementRect, type ElementRectMatch, type ElementRectMatchError, ElementRectTracker, type ElementRectTrackerOptions, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, FOCUS_PRESENCE_KIND, FOG_MAX_TILES, FOG_STATE_VERSION, FOG_TILE_CELLS, type FocusAudience, type FocusPresence, type FocusRole, type FogBase, type FogChangeEvent, type FogDefinitionV1, type FogIdFactory, FogManager, type FogManagerOptions, type FogOperation, type FogPatch, type FogRegion, FogRenderer, type FogRendererOptions, type FogStateV1, type FogTileV1, FogTool, type FogToolOptions, type FogViewEvent, type FogViewMode, type FontSizePreset, type Footprint, type FrameScheduler, type GridElement, type GridInfo, type GridMetric, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HitTestOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type HtmlPaintContext, type HtmlPaintDiagnostic, type HtmlPainter, HtmlPainterMissingError, HtmlPainterRegistry, type HtmlRenderTarget, type HtmlRouting, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalAwareness, type LocalAwarenessHost, type LocalAwarenessOptions, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, MinimapController, type MinimapControllerOptions, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PATH_PRESENCE_KIND, PATH_PRESENCE_MAX_POINTS, PEER_COLORS, PING_PRESENCE_KIND, type PathAnchor, type PathDistance, type PathEmission, type PathPresence, type PathRangeBand, type PathSegment, PathTool, type PathToolOptions, type Peer, type PeerLeaveReason, PeerRoster, type PeerRosterOptions, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, type PresenceChannel, type RectTrackerHost, RemoteCursorOverlay, type RemoteCursorOverlayHost, type RemoteCursorOverlayOptions, RemoteFocusReceiver, type RemoteFocusReceiverHost, type RemoteFocusReceiverOptions, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePathOverlay, type RemotePathOverlayHost, type RemotePathOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, RemoteSelectionOverlay, type RemoteSelectionOverlayHost, type RemoteSelectionOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type SelectionStyleDetails, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, applyCameraView, attachAwareness, boundsIntersect, cameraOriginForView, canonicalizeFogTile, captureCameraView, computeElementRects, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, defaultPeerColor, drawHexPath, elementRectsEqual, exportImage, exportSvg, fitZoomForView, decodeBase64 as fogDecodeBase64, encodeBase64 as fogEncodeBase64, footprintFromSize, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, gridDistanceCells, isAwarenessPresence, isFocusPresence, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPathPresence, isPingPresence, pathDistanceCells, recommendedFogCellSize, resolveHtmlRouting, setFontSize, smartSnap, snapFootprintCenter, snapPoint, snapToCellCenter, snapToHexCenter, styleToPatch, toFocusPresence, toLaserTrailPresence, toMeasurePresence, toPathPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline, validateFogDefinition, validateFogState, validateFogTile };

package/dist/index.d.ts

@@ -267,7 +267,7 @@ interface Tool {
     setOptions?(options: object): void;
     onOptionsChange?(listener: () => void): () => void;
 }
-type ToolName = 'hand' | 'select' | 'pencil' | 'eraser' | 'arrow' | 'note' | 'image' | 'text' | 'shape' | 'measure' | 'path' | 'template' | 'laser' | 'ping';
+type ToolName = 'hand' | 'select' | 'pencil' | 'eraser' | 'arrow' | 'note' | 'image' | 'text' | 'shape' | 'measure' | 'path' | 'template' | 'laser' | 'ping' | 'fog';
 
 declare function snapPoint(point: Point, gridSize: number): Point;
 declare function snapToHexCenter(point: Point, cellSize: number, orientation: HexOrientation): Point;
@@ -341,6 +341,61 @@ interface Layer {
     opacity: number;
 }
 
+declare const FOG_STATE_VERSION = 1;
+declare const FOG_TILE_CELLS = 128;
+declare const FOG_MAX_TILES = 256;
+type FogBase = 'covered' | 'revealed';
+interface FogDefinitionV1 {
+    readonly version: 1;
+    readonly generation: string;
+    readonly bounds: Bounds;
+    readonly cellSize: number;
+    readonly tileCells: 128;
+    readonly base: FogBase;
+}
+interface FogTileV1 {
+    readonly x: number;
+    readonly y: number;
+    readonly data: string;
+}
+interface FogStateV1 {
+    readonly definition: FogDefinitionV1;
+    readonly tiles: readonly FogTileV1[];
+}
+type FogViewMode = 'off' | 'editor' | 'player';
+type FogOperation = 'reveal' | 'conceal';
+type FogRegion = {
+    kind: 'brush';
+    points: readonly Point[];
+    radius: number;
+} | {
+    kind: 'rectangle';
+    from: Point;
+    to: Point;
+} | {
+    kind: 'polygon';
+    points: readonly Point[];
+};
+interface FogToolOptions {
+    operation?: FogOperation;
+    shape?: 'brush' | 'rectangle' | 'polygon';
+    radius?: number;
+}
+interface FogPatch {
+    readonly tiles: readonly FogTileV1[];
+}
+interface FogChangeEvent {
+    readonly kind: 'tiles' | 'definition' | 'reset' | 'disable';
+    readonly tiles?: readonly {
+        readonly x: number;
+        readonly y: number;
+    }[];
+    readonly origin?: string;
+}
+interface FogViewEvent {
+    readonly mode: FogViewMode;
+}
+
 interface CanvasState {
     version: number;
     camera: {
@@ -350,6 +405,7 @@ interface CanvasState {
     elements: CanvasElement[];
     layers?: Layer[];
     activeLayerId?: string;
+    fog?: FogStateV1;
 }
 
 interface LayerManagerEvents {
@@ -392,6 +448,55 @@ declare class LayerManager {
     private findFallbackLayer;
 }
 
+interface Command {
+    execute(store: ElementStore): void;
+    undo(store: ElementStore): void;
+}
+
+type FogIdFactory = () => string;
+interface FogManagerOptions {
+    idFactory?: FogIdFactory;
+    onCommand?: (command: Command) => void;
+}
+type ChangeListener = (event: FogChangeEvent) => void;
+type ViewListener = (event: FogViewEvent) => void;
+declare class FogManager {
+    private state;
+    private viewMode;
+    private readonly idFactory;
+    private readonly onCommand;
+    private readonly changeListeners;
+    private readonly viewListeners;
+    constructor(options?: FogManagerOptions);
+    getState(): FogStateV1 | null;
+    getViewMode(): FogViewMode;
+    initialize(options: {
+        bounds: Bounds;
+        base?: FogBase;
+        cellSize?: number;
+    }): FogStateV1;
+    loadState(state: FogStateV1 | null, meta?: {
+        origin?: string;
+    }): void;
+    /** Restores a historical visual state without reusing its causal generation id. */
+    restoreHistoryState(state: FogStateV1 | null): void;
+    setBounds(bounds: Bounds): void;
+    reset(base: FogBase): void;
+    disable(): void;
+    setViewMode(mode: FogViewMode): void;
+    applyRegion(region: FogRegion, operation: FogOperation): void;
+    applyPatchDirect(patch: FogPatch, meta?: {
+        origin?: string;
+    }): void;
+    applyTilesDirect(tiles: readonly FogTileV1[]): void;
+    on(event: 'change', listener: ChangeListener): () => void;
+    on(event: 'view', listener: ViewListener): () => void;
+    dispose(): void;
+    private collectTiles;
+    private notifyChange;
+    private notifyView;
+}
+
 interface StorageAdapter {
     load(key: string): Promise<string | null>;
     save(key: string, value: string): Promise<void>;
@@ -402,6 +507,7 @@ interface AutoSaveOptions {
     key?: string;
     debounceMs?: number;
     layerManager?: LayerManager;
+    fogManager?: FogManager;
     adapter?: StorageAdapter;
     onError?: (error: Error) => void;
 }
@@ -411,6 +517,7 @@ declare class AutoSave {
     private readonly key;
     private readonly debounceMs;
     private readonly layerManager?;
+    private readonly fogManager?;
     private readonly adapter;
     private timerId;
     private unsubscribers;
@@ -502,11 +609,6 @@ declare class ToolManager {
     onRegister(listener: (tool: Tool) => void): () => void;
 }
 
-interface Command {
-    execute(store: ElementStore): void;
-    undo(store: ElementStore): void;
-}
-
 interface HistoryStackOptions {
     maxSize?: number;
 }
@@ -635,6 +737,11 @@ interface ExportImageOptions extends ExportResourceOptions, HtmlExportOptions {
      * a non-fatal `'unsupported'` diagnostic regardless of this flag.
      */
     strictMissingCanvasHtml?: boolean;
+    fog?: {
+        state: FogStateV1;
+        mode: 'editor' | 'player';
+        color?: string;
+    } | false;
 }
 type ExportAssetErrorReason = 'load' | 'timeout' | 'encode';
 interface ExportAssetError {
@@ -660,20 +767,14 @@ interface ExportSvgOptions extends ExportResourceOptions, HtmlExportOptions {
     background?: string;
     filter?: (el: CanvasElement) => boolean;
     rasterScale?: number;
-    /** Registry of canvas-backed html painters, keyed by `htmlType`. When absent (or when
-     *  an element's `htmlType` isn't claimed), html elements fall back to the legacy
-     *  DOM-raster path (`renderHtml`). */
     htmlPainters?: HtmlPainterRegistry;
-    /** `htmlType`s that must route to canvas even before a painter for them is
-     *  registered — lets a host declare intent up front (mirrors `HtmlPainterRegistry.expect`). */
     expectedCanvasTypes?: ReadonlySet<string>;
-    /**
-     * When true, a canvas-routed html element with no active painter throws
-     * `HtmlPainterMissingError` instead of reporting `onHtmlError` and continuing.
-     * DOM-routed html elements are never affected — a missing `renderHtml` stays
-     * a non-fatal `'unsupported'` diagnostic regardless of this flag.
-     */
     strictMissingCanvasHtml?: boolean;
+    fog?: {
+        state: FogStateV1;
+        mode: 'editor' | 'player';
+        color?: string;
+    } | false;
 }
 declare function exportSvg(store: ElementStore, options?: ExportSvgOptions, layerManager?: LayerManager): Promise<string>;
 
@@ -699,6 +800,33 @@ interface RenderStatsSnapshot {
     frameCount: number;
 }
 
+interface FogRendererOptions {
+    editorColor?: string;
+    playerColor?: string;
+}
+declare class FogRenderer {
+    private tileCache;
+    private state;
+    private viewMode;
+    private dirty;
+    private editorColor;
+    private playerColor;
+    constructor(options?: FogRendererOptions);
+    setState(state: FogStateV1 | null): void;
+    setViewMode(mode: FogViewMode): void;
+    getState(): FogStateV1 | null;
+    getViewMode(): FogViewMode;
+    markDirty(): void;
+    isDirty(): boolean;
+    isVisible(): boolean;
+    render(ctx: CanvasRenderingContext2D, camera: Camera, viewportWidth: number, viewportHeight: number, _dpr: number): void;
+    renderForExport(ctx: CanvasRenderingContext2D, state: FogStateV1, mode: 'editor' | 'player', color?: string): void;
+    dispose(): void;
+    private tileRaster;
+    private renderTile;
+    private renderTileForExport;
+}
+
 /**
  * A world-space draw callback rendered above elements on every frame,
  * regardless of which tool is active. The context arrives with the camera
@@ -789,6 +917,11 @@ interface ViewportOptions {
     panInertia?: boolean;
     /** Show an overview minimap (bottom-right) with tap/drag-to-navigate. Default `false`. */
     minimap?: boolean;
+    /** Fog-of-war presentation options. Enables fog rendering and the `fog` accessor. */
+    fog?: {
+        editorColor?: string;
+        playerColor?: string;
+    };
 }
 interface HitTestOptions {
     /** Skip elements on locked layers. Default `true` (selection semantics). */
@@ -825,6 +958,8 @@ declare class Viewport {
     private _smartGuides;
     private readonly _gridSize;
     private readonly renderLoop;
+    private readonly fogManager;
+    private readonly fogRenderer;
     private readonly domNodeManager;
     private readonly interactMode;
     private readonly onHtmlElementMount?;
@@ -850,6 +985,7 @@ declare class Viewport {
     private unsubRecorderEnd;
     constructor(container: HTMLElement, options?: ViewportOptions);
     get ctx(): CanvasRenderingContext2D | null;
+    get fog(): FogManager;
     get snapToGrid(): boolean;
     setSnapToGrid(enabled: boolean): void;
     get smartGuides(): boolean;
@@ -2087,6 +2223,8 @@ declare class MinimapController {
     private readonly renderer;
     private readonly htmlPainters;
     private scene;
+    private fogRenderer;
+    private fogUnsub;
     private frameId;
     private debounceTimer;
     private dragging;
@@ -2094,6 +2232,7 @@ declare class MinimapController {
     private readonly unsubs;
     constructor(viewport: Viewport, canvas: HTMLCanvasElement, options?: MinimapControllerOptions);
     setSize(width: number, height: number): void;
+    setFogRenderer(renderer: FogRenderer | null): void;
     requestDraw(): void;
     /**
      * Invalidates the cached scene bitmap in response to html-painter registry
@@ -3039,6 +3178,43 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.65.0";
+declare function encodeBase64(bytes: Uint8Array): string;
+declare function decodeBase64(str: string): Uint8Array;
+declare function canonicalizeFogTile(tile: FogTileV1, def: FogDefinitionV1): FogTileV1 | null;
+declare function validateFogDefinition(def: unknown): asserts def is FogDefinitionV1;
+declare function validateFogTile(tile: unknown, def: FogDefinitionV1): asserts tile is FogTileV1;
+declare function validateFogState(state: unknown): asserts state is FogStateV1;
+declare function recommendedFogCellSize(bounds: Bounds): number;
+
+declare class FogTool implements Tool {
+    readonly name = "fog";
+    private drawing;
+    private points;
+    private startPoint;
+    private operation;
+    private shape;
+    private radius;
+    private readonly manager;
+    private optionListeners;
+    constructor(manager: FogManager, options?: FogToolOptions);
+    onActivate(ctx: ToolContext): void;
+    onDeactivate(ctx: ToolContext): void;
+    getOptions(): FogToolOptions;
+    setOptions(options: FogToolOptions): void;
+    onOptionsChange(listener: () => void): () => void;
+    onPointerDown(state: PointerState, ctx: ToolContext): void;
+    onPointerMove(state: PointerState, ctx: ToolContext): void;
+    onPointerUp(_state: PointerState, ctx: ToolContext): void;
+    onPointerCancel(_state: PointerState, ctx: ToolContext): void;
+    onKeyDown(event: KeyboardEvent, ctx: ToolContext): boolean;
+    renderOverlay(ctx: CanvasRenderingContext2D): void;
+    private buildRegion;
+    private cancelGesture;
+    private renderBrushPreview;
+    private renderRectanglePreview;
+    private renderPolygonPreview;
+}
+
+declare const VERSION = "0.66.0";
 
-export { AWARENESS_MAX_SELECTION, AWARENESS_PRESENCE_KIND, type ActivationOptions, type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, type AttachAwarenessOptions, AutoSave, type AutoSaveOptions, type AwarenessFields, type AwarenessHandle, type AwarenessIdentity, type AwarenessPresence, type AwarenessViewport, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraAnimationEndReason, CameraAnimator, type CameraAnimatorOptions, type CameraChangeInfo, type CameraOptions, type CameraView, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DiagonalRule, type DistributeAxis, type ElementActivationEvent, type ElementChangeMeta, type ElementRect, type ElementRectMatch, type ElementRectMatchError, ElementRectTracker, type ElementRectTrackerOptions, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, FOCUS_PRESENCE_KIND, type FocusAudience, type FocusPresence, type FocusRole, type FontSizePreset, type Footprint, type FrameScheduler, type GridElement, type GridInfo, type GridMetric, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HitTestOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type HtmlPaintContext, type HtmlPaintDiagnostic, type HtmlPainter, HtmlPainterMissingError, HtmlPainterRegistry, type HtmlRenderTarget, type HtmlRouting, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalAwareness, type LocalAwarenessHost, type LocalAwarenessOptions, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, MinimapController, type MinimapControllerOptions, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PATH_PRESENCE_KIND, PATH_PRESENCE_MAX_POINTS, PEER_COLORS, PING_PRESENCE_KIND, type PathAnchor, type PathDistance, type PathEmission, type PathPresence, type PathRangeBand, type PathSegment, PathTool, type PathToolOptions, type Peer, type PeerLeaveReason, PeerRoster, type PeerRosterOptions, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, type PresenceChannel, type RectTrackerHost, RemoteCursorOverlay, type RemoteCursorOverlayHost, type RemoteCursorOverlayOptions, RemoteFocusReceiver, type RemoteFocusReceiverHost, type RemoteFocusReceiverOptions, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePathOverlay, type RemotePathOverlayHost, type RemotePathOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, RemoteSelectionOverlay, type RemoteSelectionOverlayHost, type RemoteSelectionOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type SelectionStyleDetails, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, applyCameraView, attachAwareness, boundsIntersect, cameraOriginForView, captureCameraView, computeElementRects, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, defaultPeerColor, drawHexPath, elementRectsEqual, exportImage, exportSvg, fitZoomForView, footprintFromSize, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, gridDistanceCells, isAwarenessPresence, isFocusPresence, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPathPresence, isPingPresence, pathDistanceCells, resolveHtmlRouting, setFontSize, smartSnap, snapFootprintCenter, snapPoint, snapToCellCenter, snapToHexCenter, styleToPatch, toFocusPresence, toLaserTrailPresence, toMeasurePresence, toPathPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+export { AWARENESS_MAX_SELECTION, AWARENESS_PRESENCE_KIND, type ActivationOptions, type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, type AttachAwarenessOptions, AutoSave, type AutoSaveOptions, type AwarenessFields, type AwarenessHandle, type AwarenessIdentity, type AwarenessPresence, type AwarenessViewport, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraAnimationEndReason, CameraAnimator, type CameraAnimatorOptions, type CameraChangeInfo, type CameraOptions, type CameraView, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DiagonalRule, type DistributeAxis, type ElementActivationEvent, type ElementChangeMeta, type ElementRect, type ElementRectMatch, type ElementRectMatchError, ElementRectTracker, type ElementRectTrackerOptions, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, FOCUS_PRESENCE_KIND, FOG_MAX_TILES, FOG_STATE_VERSION, FOG_TILE_CELLS, type FocusAudience, type FocusPresence, type FocusRole, type FogBase, type FogChangeEvent, type FogDefinitionV1, type FogIdFactory, FogManager, type FogManagerOptions, type FogOperation, type FogPatch, type FogRegion, FogRenderer, type FogRendererOptions, type FogStateV1, type FogTileV1, FogTool, type FogToolOptions, type FogViewEvent, type FogViewMode, type FontSizePreset, type Footprint, type FrameScheduler, type GridElement, type GridInfo, type GridMetric, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HitTestOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type HtmlPaintContext, type HtmlPaintDiagnostic, type HtmlPainter, HtmlPainterMissingError, HtmlPainterRegistry, type HtmlRenderTarget, type HtmlRouting, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalAwareness, type LocalAwarenessHost, type LocalAwarenessOptions, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, MinimapController, type MinimapControllerOptions, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PATH_PRESENCE_KIND, PATH_PRESENCE_MAX_POINTS, PEER_COLORS, PING_PRESENCE_KIND, type PathAnchor, type PathDistance, type PathEmission, type PathPresence, type PathRangeBand, type PathSegment, PathTool, type PathToolOptions, type Peer, type PeerLeaveReason, PeerRoster, type PeerRosterOptions, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, type PresenceChannel, type RectTrackerHost, RemoteCursorOverlay, type RemoteCursorOverlayHost, type RemoteCursorOverlayOptions, RemoteFocusReceiver, type RemoteFocusReceiverHost, type RemoteFocusReceiverOptions, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePathOverlay, type RemotePathOverlayHost, type RemotePathOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, RemoteSelectionOverlay, type RemoteSelectionOverlayHost, type RemoteSelectionOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type SelectionStyleDetails, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, applyCameraView, attachAwareness, boundsIntersect, cameraOriginForView, canonicalizeFogTile, captureCameraView, computeElementRects, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, defaultPeerColor, drawHexPath, elementRectsEqual, exportImage, exportSvg, fitZoomForView, decodeBase64 as fogDecodeBase64, encodeBase64 as fogEncodeBase64, footprintFromSize, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, gridDistanceCells, isAwarenessPresence, isFocusPresence, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPathPresence, isPingPresence, pathDistanceCells, recommendedFogCellSize, resolveHtmlRouting, setFontSize, smartSnap, snapFootprintCenter, snapPoint, snapToCellCenter, snapToHexCenter, styleToPatch, toFocusPresence, toLaserTrailPresence, toMeasurePresence, toPathPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline, validateFogDefinition, validateFogState, validateFogTile };