@fieldnotes/core 0.58.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 {
@@ -1729,6 +1755,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.58.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, 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 {
@@ -1729,6 +1755,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.58.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, 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.js

@@ -5753,6 +5753,19 @@ function computeBounds(elements, padding) {
     h: maxY - minY + padding * 2
   };
 }
+function resolveExportBounds(region, elements, padding) {
+  if (!region) return computeBounds(elements, padding);
+  const finite = Number.isFinite(region.x) && Number.isFinite(region.y) && Number.isFinite(region.w) && Number.isFinite(region.h);
+  if (!finite || region.w <= 0 || region.h <= 0) {
+    throw new RangeError("region must have finite coordinates and positive w/h");
+  }
+  return {
+    x: region.x - padding,
+    y: region.y - padding,
+    w: region.w + padding * 2,
+    h: region.h + padding * 2
+  };
+}
 function renderGridForBounds(ctx, grid, bounds) {
   const visibleBounds = {
     minX: bounds.x,
@@ -5795,6 +5808,29 @@ function nonNegativeOption(value, fallback, name) {
   }
   return resolved;
 }
+function fitExportScale(bounds, requestedScale, options) {
+  const maxDimension = positiveOption(options.maxDimension, DEFAULT_MAX_DIMENSION, "maxDimension");
+  const maxPixels = positiveOption(options.maxPixels, DEFAULT_MAX_PIXELS, "maxPixels");
+  const fits = (scale) => {
+    const w = Math.ceil(bounds.w * scale);
+    const h = Math.ceil(bounds.h * scale);
+    return w <= maxDimension && h <= maxDimension && w * h <= maxPixels;
+  };
+  if (fits(requestedScale)) return requestedScale;
+  const analytical = Math.min(
+    maxDimension / Math.max(bounds.w, bounds.h),
+    Math.sqrt(maxPixels) / Math.sqrt(bounds.w) / Math.sqrt(bounds.h)
+  );
+  let hi = Math.min(requestedScale, analytical);
+  if (fits(hi)) return hi;
+  let lo = 0;
+  for (let i = 0; i < 40; i++) {
+    const mid = (lo + hi) / 2;
+    if (fits(mid)) lo = mid;
+    else hi = mid;
+  }
+  return lo;
+}
 function assertExportSize(width, height, options) {
   const maxDimension = positiveOption(options.maxDimension, DEFAULT_MAX_DIMENSION, "maxDimension");
   const maxPixels = positiveOption(options.maxPixels, DEFAULT_MAX_PIXELS, "maxPixels");
@@ -5869,10 +5905,23 @@ function loadImages(elements, options = {}) {
   });
 }
 async function exportImage(store, options = {}, layerManager) {
-  const scale = positiveOption(options.scale, 2, "scale");
+  const requestedScale = positiveOption(options.scale, 2, "scale");
+  const scaleMode = options.scaleMode ?? "exact";
+  if (scaleMode !== "exact" && scaleMode !== "fit") {
+    throw new RangeError(`scaleMode must be 'exact' or 'fit'`);
+  }
   const padding = nonNegativeOption(options.padding, 0, "padding");
   validateExportResourceOptions(options);
   validateHtmlExportOptions(options);
+  const format = options.format ?? "png";
+  if (format !== "png" && format !== "jpeg") {
+    throw new RangeError(`format must be 'png' or 'jpeg'`);
+  }
+  if (options.quality !== void 0) {
+    if (!Number.isFinite(options.quality) || options.quality <= 0 || options.quality > 1) {
+      throw new RangeError("quality must be a finite number in (0, 1]");
+    }
+  }
   const background = options.background ?? "#ffffff";
   const filter = options.filter;
   const allElements = store.getAll();
@@ -5880,8 +5929,9 @@ async function exportImage(store, options = {}, layerManager) {
   if (filter) {
     visibleElements = visibleElements.filter(filter);
   }
-  const bounds = computeBounds(visibleElements, padding);
+  const bounds = resolveExportBounds(options.region, visibleElements, padding);
   if (!bounds) return null;
+  const scale = scaleMode === "fit" ? fitExportScale(bounds, requestedScale, options) : requestedScale;
   const width = Math.ceil(bounds.w * scale);
   const height = Math.ceil(bounds.h * scale);
   assertExportSize(width, height, options);
@@ -5983,8 +6033,9 @@ async function exportImage(store, options = {}, layerManager) {
     renderGridForBounds(ctx, grid, bounds);
     ctx.restore();
   }
+  const mimeType = format === "jpeg" ? "image/jpeg" : "image/png";
   return new Promise((resolve) => {
-    canvas.toBlob((blob) => resolve(blob), "image/png");
+    canvas.toBlob((blob) => resolve(blob), mimeType, options.quality);
   });
 }
 
@@ -12264,7 +12315,7 @@ var PingTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.58.0";
+var VERSION = "0.59.0";
 export {
   ArrowTool,
   AutoSave,