@fieldnotes/core 0.57.0 → 0.59.0

package/dist/index.d.cts

@@ -469,6 +469,32 @@ interface ExportImageOptions extends ExportResourceOptions, HtmlExportOptions {
     padding?: number;
     background?: string;
     filter?: (element: CanvasElement) => boolean;
+    /**
+     * Optional world-space crop. When set it replaces the computed content
+     * bounds; `padding` still applies around it. Elements outside the region
+     * clip naturally. A region export with no intersecting elements still
+     * produces a background-filled image.
+     */
+    region?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /**
+     * Output encoding. Defaults to 'png'. JPEG output is opaque — a transparent
+     * `background` renders as black; keep the default `#ffffff` (or any opaque color)
+     * for JPEG exports.
+     */
+    format?: 'png' | 'jpeg';
+    /** Encoder quality in (0, 1]. Only meaningful for 'jpeg'. */
+    quality?: number;
+    /**
+     * 'exact' (default) throws when scale × bounds exceeds maxDimension/maxPixels.
+     * 'fit' reduces the effective scale to the largest value that satisfies both
+     * caps (never above the requested scale).
+     */
+    scaleMode?: 'exact' | 'fit';
 }
 type ExportAssetErrorReason = 'load' | 'timeout' | 'encode';
 interface ExportAssetError {
@@ -610,6 +636,7 @@ declare class Viewport {
     private contextMenu;
     private minimap;
     private readonly htmlRenderers;
+    private readonly resizeListeners;
     constructor(container: HTMLElement, options?: ViewportOptions);
     get ctx(): CanvasRenderingContext2D | null;
     get snapToGrid(): boolean;
@@ -617,6 +644,16 @@ declare class Viewport {
     get smartGuides(): boolean;
     setSmartGuides(enabled: boolean): void;
     fitToContent(padding?: number): void;
+    /** World-space rectangle currently visible through the canvas. */
+    getVisibleRect(): Bounds;
+    /** Centers the camera on a world point without changing zoom. */
+    centerCameraAt(world: Point): void;
+    /**
+     * Notifies after the host container resizes (ResizeObserver-driven). A resize
+     * changes the visible world rect without a camera event; overlays such as the
+     * minimap subscribe to stay current. Returns an idempotent unsubscribe.
+     */
+    onResize(listener: () => void): () => void;
     requestRender(): void;
     /**
      * Registers a world-space overlay drawn above elements on every frame,
@@ -1245,6 +1282,74 @@ declare class PingInput {
     private emit;
 }
 
+interface MinimapControllerOptions {
+    /** Minimap width in CSS pixels. Default `200`. */
+    width?: number;
+    /** Minimap height in CSS pixels. Default `140`. */
+    height?: number;
+    /** Content inset inside the minimap, in minimap pixels. Default `8`. */
+    padding?: number;
+    /** Backdrop fill behind the thumbnail. Default: none (transparent). */
+    background?: string;
+    /** Stroke color of the viewport rectangle. Default `'#3b82f6'`. */
+    viewportStroke?: string;
+    /** Trailing debounce for scene bitmap re-renders. Default `200`. */
+    debounceMs?: number;
+    /** Tap/drag-to-center navigation on the canvas. Default `true`. */
+    interactive?: boolean;
+    /** Frame scheduler; default `requestAnimationFrame`. Injected by tests. */
+    requestFrame?: (cb: () => void) => number;
+    /** Frame canceller; default `cancelAnimationFrame`. Injected by tests. */
+    cancelFrame?: (id: number) => void;
+}
+/**
+ * Thumbnail overview navigator: renders the scene (real element shapes,
+ * downscaled images, per-layer opacity compositing) into a cached offscreen
+ * bitmap, composites it with the live viewport rectangle each frame, and
+ * centers the camera on tap/drag. The cached bitmap and its transform swap
+ * atomically: camera motion never renders the scene, only re-composites.
+ */
+declare class MinimapController {
+    private readonly viewport;
+    private readonly canvas;
+    private width;
+    private height;
+    private readonly padding;
+    private readonly background;
+    private readonly viewportStroke;
+    private readonly debounceMs;
+    private readonly interactive;
+    private readonly requestFrame;
+    private readonly cancelFrame;
+    private readonly renderer;
+    private scene;
+    private frameId;
+    private debounceTimer;
+    private dragging;
+    private disposed;
+    private readonly unsubs;
+    constructor(viewport: Viewport, canvas: HTMLCanvasElement, options?: MinimapControllerOptions);
+    setSize(width: number, height: number): void;
+    requestDraw(): void;
+    dispose(): void;
+    private clearDebounce;
+    private dpr;
+    private applyCanvasSize;
+    private sceneElements;
+    private currentMapping;
+    private onViewChanged;
+    private markSceneDirty;
+    private renderScene;
+    private renderLayerElements;
+    private draw;
+    private navTransform;
+    private navigateFromEvent;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerUp;
+    private onPointerEnd;
+}
+
 interface ActiveFormats {
     bold: boolean;
     italic: boolean;
@@ -1650,6 +1755,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.57.0";
+declare const VERSION = "0.59.0";
 
-export { type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraChangeInfo, type CameraOptions, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementChangeMeta, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, type FontSizePreset, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, 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, boundsIntersect, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPingPresence, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toLaserTrailPresence, toMeasurePresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+export { type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraChangeInfo, type CameraOptions, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementChangeMeta, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, type FontSizePreset, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, MinimapController, type MinimapControllerOptions, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, 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, boundsIntersect, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPingPresence, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toLaserTrailPresence, toMeasurePresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };

package/dist/index.d.ts

@@ -469,6 +469,32 @@ interface ExportImageOptions extends ExportResourceOptions, HtmlExportOptions {
     padding?: number;
     background?: string;
     filter?: (element: CanvasElement) => boolean;
+    /**
+     * Optional world-space crop. When set it replaces the computed content
+     * bounds; `padding` still applies around it. Elements outside the region
+     * clip naturally. A region export with no intersecting elements still
+     * produces a background-filled image.
+     */
+    region?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /**
+     * Output encoding. Defaults to 'png'. JPEG output is opaque — a transparent
+     * `background` renders as black; keep the default `#ffffff` (or any opaque color)
+     * for JPEG exports.
+     */
+    format?: 'png' | 'jpeg';
+    /** Encoder quality in (0, 1]. Only meaningful for 'jpeg'. */
+    quality?: number;
+    /**
+     * 'exact' (default) throws when scale × bounds exceeds maxDimension/maxPixels.
+     * 'fit' reduces the effective scale to the largest value that satisfies both
+     * caps (never above the requested scale).
+     */
+    scaleMode?: 'exact' | 'fit';
 }
 type ExportAssetErrorReason = 'load' | 'timeout' | 'encode';
 interface ExportAssetError {
@@ -610,6 +636,7 @@ declare class Viewport {
     private contextMenu;
     private minimap;
     private readonly htmlRenderers;
+    private readonly resizeListeners;
     constructor(container: HTMLElement, options?: ViewportOptions);
     get ctx(): CanvasRenderingContext2D | null;
     get snapToGrid(): boolean;
@@ -617,6 +644,16 @@ declare class Viewport {
     get smartGuides(): boolean;
     setSmartGuides(enabled: boolean): void;
     fitToContent(padding?: number): void;
+    /** World-space rectangle currently visible through the canvas. */
+    getVisibleRect(): Bounds;
+    /** Centers the camera on a world point without changing zoom. */
+    centerCameraAt(world: Point): void;
+    /**
+     * Notifies after the host container resizes (ResizeObserver-driven). A resize
+     * changes the visible world rect without a camera event; overlays such as the
+     * minimap subscribe to stay current. Returns an idempotent unsubscribe.
+     */
+    onResize(listener: () => void): () => void;
     requestRender(): void;
     /**
      * Registers a world-space overlay drawn above elements on every frame,
@@ -1245,6 +1282,74 @@ declare class PingInput {
     private emit;
 }
 
+interface MinimapControllerOptions {
+    /** Minimap width in CSS pixels. Default `200`. */
+    width?: number;
+    /** Minimap height in CSS pixels. Default `140`. */
+    height?: number;
+    /** Content inset inside the minimap, in minimap pixels. Default `8`. */
+    padding?: number;
+    /** Backdrop fill behind the thumbnail. Default: none (transparent). */
+    background?: string;
+    /** Stroke color of the viewport rectangle. Default `'#3b82f6'`. */
+    viewportStroke?: string;
+    /** Trailing debounce for scene bitmap re-renders. Default `200`. */
+    debounceMs?: number;
+    /** Tap/drag-to-center navigation on the canvas. Default `true`. */
+    interactive?: boolean;
+    /** Frame scheduler; default `requestAnimationFrame`. Injected by tests. */
+    requestFrame?: (cb: () => void) => number;
+    /** Frame canceller; default `cancelAnimationFrame`. Injected by tests. */
+    cancelFrame?: (id: number) => void;
+}
+/**
+ * Thumbnail overview navigator: renders the scene (real element shapes,
+ * downscaled images, per-layer opacity compositing) into a cached offscreen
+ * bitmap, composites it with the live viewport rectangle each frame, and
+ * centers the camera on tap/drag. The cached bitmap and its transform swap
+ * atomically: camera motion never renders the scene, only re-composites.
+ */
+declare class MinimapController {
+    private readonly viewport;
+    private readonly canvas;
+    private width;
+    private height;
+    private readonly padding;
+    private readonly background;
+    private readonly viewportStroke;
+    private readonly debounceMs;
+    private readonly interactive;
+    private readonly requestFrame;
+    private readonly cancelFrame;
+    private readonly renderer;
+    private scene;
+    private frameId;
+    private debounceTimer;
+    private dragging;
+    private disposed;
+    private readonly unsubs;
+    constructor(viewport: Viewport, canvas: HTMLCanvasElement, options?: MinimapControllerOptions);
+    setSize(width: number, height: number): void;
+    requestDraw(): void;
+    dispose(): void;
+    private clearDebounce;
+    private dpr;
+    private applyCanvasSize;
+    private sceneElements;
+    private currentMapping;
+    private onViewChanged;
+    private markSceneDirty;
+    private renderScene;
+    private renderLayerElements;
+    private draw;
+    private navTransform;
+    private navigateFromEvent;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerUp;
+    private onPointerEnd;
+}
+
 interface ActiveFormats {
     bold: boolean;
     italic: boolean;
@@ -1650,6 +1755,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.57.0";
+declare const VERSION = "0.59.0";
 
-export { type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraChangeInfo, type CameraOptions, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementChangeMeta, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, type FontSizePreset, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, 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, boundsIntersect, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPingPresence, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toLaserTrailPresence, toMeasurePresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+export { type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraChangeInfo, type CameraOptions, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementChangeMeta, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, type FontSizePreset, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, MinimapController, type MinimapControllerOptions, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, 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, boundsIntersect, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPingPresence, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toLaserTrailPresence, toMeasurePresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };