@ingcreators/annot-core 0.1.0

package/dist/editor/viewport-math.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Default minimum / maximum zoom levels mirroring the historical
+ * `setZoom()` clamp inside `CanvasManager`. Exported so callers can
+ * stay aligned with the editor's published behavior.
+ */
+export declare const DEFAULT_MIN_ZOOM = 0.1;
+export declare const DEFAULT_MAX_ZOOM = 5;
+/**
+ * Padding (in CSS pixels) the editor reserves around the canvas when
+ * computing "Fit to window". Matches the historical magic number in
+ * CanvasManager.fitToView.
+ */
+export declare const FIT_VIEW_PADDING = 40;
+/**
+ * Clamp `z` into the supported zoom range. Pure replacement for the
+ * inline `Math.max(min, Math.min(z, max))` previously embedded in
+ * `CanvasManager.setZoom`.
+ */
+export declare function clampZoom(z: number, min?: number, max?: number): number;
+/**
+ * Compute the "Fit to window" zoom factor for an image of the given
+ * intrinsic size against a container. Padding is subtracted from the
+ * container dimensions before fitting (matching the historical
+ * editor behavior); the result is capped at `maxZoom` so a small
+ * image never scales above 1× in fit mode.
+ *
+ * Returns 0 when either container dimension would be ≤ 0 after
+ * padding, signalling "container not yet laid out — caller should
+ * skip this fit pass". This matches the legacy behavior of
+ * `Math.min(negativeNumber, 1)` becoming a non-positive scale that
+ * the editor effectively ignored when the surrounding container had
+ * not been measured yet.
+ */
+export declare function computeFitZoom(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number, padding?: number, maxZoom?: number): number;
+/**
+ * Compute the rendered pixel size of the canvas at a given zoom,
+ * rounding to integer device pixels (matching what CanvasManager
+ * writes into the `<svg>` element's width/height attributes).
+ */
+export declare function computeRenderedSize(imageWidth: number, imageHeight: number, zoom: number): {
+    width: number;
+    height: number;
+};
+/**
+ * 2D affine matrix expressed as a six-tuple `[a, b, c, d, e, f]`,
+ * applying the transform `(x, y) → (a*x + c*y + e, b*x + d*y + f)`.
+ *
+ * This matches the layout of `DOMMatrix` / `SVGMatrix` in the
+ * browser, so callers can populate it from `getScreenCTM()` via
+ * `[m.a, m.b, m.c, m.d, m.e, m.f]` and feed it to `applyInverse`
+ * without needing a real `DOMMatrix` instance under jsdom / Node.
+ */
+export type AffineMatrix = readonly [number, number, number, number, number, number];
+/**
+ * Apply the inverse of a 2D affine matrix to a client-space point,
+ * yielding the corresponding SVG-space point. This is the pure-math
+ * core of `CanvasManager.svgPoint(e)`:
+ *   1. Read the live `getScreenCTM()` (browser-only, in CanvasManager).
+ *   2. Pass its components to `applyInverseAffine` along with the
+ *      pointer's `clientX/clientY` (here).
+ *
+ * Throws if the matrix is singular (det ≈ 0); the editor never
+ * encounters this in practice because an unrendered `<svg>` returns
+ * `null` from `getScreenCTM()` and CanvasManager skips the call.
+ */
+export declare function applyInverseAffine(matrix: AffineMatrix, clientX: number, clientY: number): {
+    x: number;
+    y: number;
+};

package/dist/encode/index.d.ts

@@ -0,0 +1,4 @@
+import { EncodeOptions, EncodeResult } from './options.js';
+export { computeResizeTarget, DEFAULT_ENCODE_OPTIONS, type EncodeFormat, type EncodeOptions, type EncodeResult, SAVE_SIZE_LABEL, SAVE_SIZE_MAX_WIDTH, type SaveSizePreset, } from './options.js';
+/** Encode a PNG data URL per the given options. */
+export declare function encodeCapture(pngDataUrl: string, options?: EncodeOptions): Promise<EncodeResult>;

package/dist/encode/options.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Encode option types + defaults — split out of `./index.ts` so callers
+ * that only need the data shape (e.g. the web app's preferences
+ * loader) can import this leaf without dragging in the WASM
+ * imagequant binding that `encodeCapture` requires. Keeps the
+ * encoder lazy-loadable as a separate chunk.
+ */
+export type EncodeFormat = "smart" | "png" | "jpeg";
+/**
+ * Save size presets — apply a max-width cap to the image before
+ * encoding so 4K screenshots don't end up as 5–10 MB files.
+ * Values match the spec in
+ * `docs/plans/_done/web-capture-redesign.md`'s "Deferred" item.
+ *
+ * Aspect ratio is preserved; height scales proportionally. Images
+ * narrower than the preset's max-width pass through unscaled (we
+ * never upscale).
+ */
+export type SaveSizePreset = "light" | "standard" | "highQuality" | "original";
+/** Mapping from preset → max-width in pixels (`null` = no resize). */
+export declare const SAVE_SIZE_MAX_WIDTH: Record<SaveSizePreset, number | null>;
+/** Human-readable label for the preset, used by the dialog selector
+ *  + the (future) extension settings UI. Shared so both surfaces
+ *  speak the same language. */
+export declare const SAVE_SIZE_LABEL: Record<SaveSizePreset, string>;
+export interface EncodeOptions {
+    /** "smart" | "png" | "jpeg" */
+    format: EncodeFormat;
+    /** Fallback format used by "smart" mode when the image is photo-heavy. */
+    smartFallback: "png" | "jpeg";
+    /**
+     * Heuristic: if a sampled pixel pass finds more unique RGBA colors than
+     * this threshold, treat the image as photo-heavy and skip PNG-8.
+     * Typical UI screenshots return <5000; photo-heavy pages return >20000.
+     */
+    smartColorThreshold: number;
+    /** JPEG quality 60–100 (%). Used for "jpeg" and smart's JPEG fallback. */
+    jpegPercent: number;
+    /**
+     * Cap the encoded image's max width per
+     * {@link SAVE_SIZE_MAX_WIDTH}. Aspect-preserving down-scale; no
+     * upscale when the source is already narrower.
+     *
+     * Optional on the interface so existing callers that don't
+     * surface this knob (today: the Browser Extension's capture
+     * pipeline at `@ingcreators/annot-capture/shared/encode`) keep
+     * compiling without changes — `encodeCapture` treats `undefined`
+     * as `"original"` (no resize, identical pre-feature behaviour).
+     *
+     * `DEFAULT_ENCODE_OPTIONS` sets it to `"standard"` (1920px),
+     * which the Annot Web app's encode-options loader uses by
+     * default. Future extension settings UI work will wire its own
+     * `Settings.quality.saveSizePreset` field here.
+     */
+    saveSizePreset?: SaveSizePreset;
+}
+export declare const DEFAULT_ENCODE_OPTIONS: EncodeOptions;
+/** Compute the resize target for a given source size + preset.
+ *  Returns the source dimensions unchanged when the preset is
+ *  `"original"` or the source is already narrower than the cap.
+ *  Pure helper — usable by both the encoder (during the
+ *  re-encode pass) and the (future) extension settings UI for
+ *  preview labels. */
+export declare function computeResizeTarget(sourceWidth: number, sourceHeight: number, preset: SaveSizePreset): {
+    width: number;
+    height: number;
+    scaled: boolean;
+};
+export interface EncodeResult {
+    dataUrl: string;
+    /** Actual format chosen (may differ from requested in "smart" mode). */
+    chosen: "png" | "jpeg";
+    /** Human-readable note (e.g. "png-8", "photo-fallback") — useful for logs. */
+    reason?: string;
+    /** Final pixel dimensions of the encoded image. May differ from
+     *  the input when `saveSizePreset` triggered a down-scale. */
+    width?: number;
+    height?: number;
+}

package/dist/encode/png8.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encode a palette + per-pixel indices buffer as a PNG-8 file.
+ *
+ * @param palette  RGBA bytes per palette entry, length = 4 * N (1 ≤ N ≤ 256).
+ * @param indices  One byte per pixel, length = width * height.
+ * @param width    Image width in pixels.
+ * @param height   Image height in pixels.
+ * @param level    DEFLATE compression level 0–9 (default 9 = smallest file).
+ */
+export declare function encodePng8(palette: Uint8Array, indices: Uint8Array, width: number, height: number, level?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9): Uint8Array;

package/dist/headless.d.ts

@@ -0,0 +1,29 @@
+export { coerceToLogicalFamily, cssStackFor, isLogicalFamily, LOGICAL_FAMILIES, type LogicalFamily, ooxmlTypefacesFor, } from './editor/font-registry.js';
+export { createHistoryCore, DEFAULT_HISTORY_DEPTH, type HistoryCore, type HistoryHooks, } from './editor/history-core.js';
+export { BUILTIN_ICON_IDS, BUILTIN_ICONS, type BuiltinIconId, resolveBuiltinIcon, } from './editor/icons/registry.js';
+export { renderIconElement, renderIconHtml } from './editor/icons/render.js';
+export { sanitizeIconSvg } from './editor/icons/sanitize.js';
+export { translatePathD } from './editor/path-utils.js';
+export { CATEGORY_CONTROL_SHAPE, classifyPropertyElement, classifyPropertySelection, PROPERTY_CONTROL_IDS, PROPERTY_CONTROLS, PROPERTY_EFFECT_IDS, type PropertyCategory, type PropertyControlDef, type PropertyControlId, type PropertyControlOption, type PropertyControlType, type PropertyEffectId, } from './editor/property-schema.js';
+export { computeSnap, cursorForAngle, type Rect, rotateAround, type SnapGuide, type SnapInput, type SnapResult, } from './editor/selection-geometry.js';
+export { ANNOT_SVG_VERSION, ANNOT_SVG_VERSION_ATTR, ANNOT_SVG_VERSION_UNSTAMPED, getAnnotVersionFromString, readAnnotVersion, stampAnnotVersion, } from './editor/svg-format.js';
+export { createMockToolSurface, type MockToolSurface, type ToolDOMSurface, } from './editor/tool-lifecycle.js';
+export { selectionDefMetadata, TOOL_PANEL_ADAPTER_IDS, TOOL_PANEL_ADAPTERS, type ToolPanelAdapter, type ToolPanelAdapterId, type ToolPanelAdapterMetadata, } from './editor/tool-panel-adapter.js';
+export { fieldForSnakeKey, type PresetWireFormat, presetFromWire, presetToWire, } from './editor/tool-preset-serde.js';
+export { normalizeVariantSideFields, TOOL_PANEL_EXTRA_CONTROL_IDS, TOOL_REGISTRY, TOOL_REGISTRY_IDS, type ToolPanelControlDef, type ToolPanelExtraControlId, type ToolPanelSection, type ToolRegistryEntry, type ToolRegistryId, type ToolRegistryVariant, } from './editor/tool-registry.js';
+export { readUniversalStyleAttrs, resolveStyleReadSource, } from './editor/tool-style-reader.js';
+export { writeUniversalStyleAttrs } from './editor/tool-style-writer.js';
+export { type AffineMatrix, applyInverseAffine, clampZoom, computeFitZoom, computeRenderedSize, DEFAULT_MAX_ZOOM, DEFAULT_MIN_ZOOM, FIT_VIEW_PADDING, } from './editor/viewport-math.js';
+export { builtinIcon, type IconSpec, isBuiltinIcon, isSvgIcon, isUrlIcon, svgIcon, urlIcon, } from './icons/types.js';
+export { StorageConflictError, StorageError, type StorageErrorCode, StorageNotFoundError, StoragePermissionError, StorageQuotaError, } from './storage/errors.js';
+export { type ListingEntry, type ListingEntryKind, type MetadataCache, MetadataCacheError, MetadataCacheQuotaError, type StorageWithMetadataCache, supportsMetadataCache, } from './storage/metadata-cache.js';
+export { ancestorPaths, getFilename, getParentPath, isDescendantOrSame, joinPath, ROOT_PATH, rewritePathPrefix, splitExt, splitPath, uniquifyFilename, uniquifyFilenameAsync, validateName, } from './storage/path.js';
+export { type CachedThumbnail, type ThumbnailCache, ThumbnailCacheError, type ThumbnailCacheGetRequest, ThumbnailCacheQuotaError, } from './storage/thumbnail-cache.js';
+export type { DocumentRecord, DocumentRecordUpdate, FolderRecord, ImageRecord, ImageRecordUpdate, PageElement, PageMetadata, StorageProvider, StorageWithDocuments, StorageWithForceRefresh, StorageWithInit, StorageWithRateLimit, StorageWithResync, StorageWithTokenRefresher, } from './storage/types.js';
+export { supportsDocuments, supportsForceRefresh, supportsInit, supportsRateLimit, supportsResync, supportsTokenRefresher, } from './storage/types.js';
+export { assertNonNull } from './utils/assert.js';
+export { DEFAULT_FILL_COLOR, DEFAULT_FONT_SIZE, DEFAULT_STROKE_COLOR, DEFAULT_STROKE_WIDTH, JPEG_QUALITY, MOSAIC_BLOCK_SIZE, } from './utils/constants.js';
+export { computeDasharray, detectDashKey } from './utils/dash-utils.js';
+export { ANNOT_FILENAME_PREFIX, defaultAnnotFilenameStem, defaultAnnotImageFilename, formatLocalTimestamp, } from './utils/filename.js';
+export { newIdB58 } from './utils/id.js';
+export { buildZip, dataUrlExt, dataUrlToBytes } from './zip/zip-builder.js';

package/dist/icons/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@ingcreators/annot-core/icons` — Tier-A icon types + value-level
+ * helpers + the narrow `BuiltinIconId` union from the Tier-B
+ * registry.
+ *
+ * Plugin authors and host code that need autocomplete on builtin
+ * ids import from here. The barrel intentionally pulls in the
+ * registry so consumers get a SINGLE narrow `BuiltinIconId` —
+ * earlier phases used a broad `string` alias for the type while
+ * the registry was being scaffolded; with Phase 2 in, the broad
+ * alias from `./types` is shadowed by the narrow one from the
+ * registry below.
+ */
+export { BUILTIN_ICON_IDS, BUILTIN_ICONS, type BuiltinIconId, resolveBuiltinIcon, } from '../editor/icons/registry.js';
+export { builtinIcon, type IconSpec, isBuiltinIcon, isSvgIcon, isUrlIcon, svgIcon, urlIcon, } from './types.js';

package/dist/icons/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Tier A icon types for `@ingcreators/annot-core`.
+ *
+ * Phase 1 of `docs/plans/svg-icons-and-plugin-icon-spec.md`.
+ *
+ * `IconSpec` is the public, plugin-facing handle for "render this
+ * icon here". Hosts (the toolbar, the sidebar, every panel header)
+ * and plugins (storage backend chips, sidebar tabs, drawer
+ * external-link rows) all describe their icons via the same
+ * discriminated-union shape so the renderer routes builtins,
+ * plugin-supplied SVG, and bundled image assets uniformly.
+ *
+ * This file is **pure types + value-level constructor helpers** —
+ * no DOM access, no Element imports, no module-level side
+ * effects. Importable in pure Node, jsdom, or the browser
+ * unchanged. The Tier B registry in
+ * `@ingcreators/annot-core/editor/icons/registry` (Phase 2) is
+ * what binds `BuiltinIconId` to concrete SVG strings; this Tier A
+ * file declares only the broad shape so downstream consumers
+ * that don't want the registry as a value-level dependency
+ * (rare; primarily plugin authors who only ever produce
+ * `kind: "svg"` icons) can still type-check against `IconSpec`.
+ *
+ * The narrow union `BuiltinIconId = keyof typeof BUILTIN_ICONS` is
+ * exported FROM the registry module, and re-exported by the icons
+ * subpath barrel (`@ingcreators/annot-core/icons`) so plugin
+ * authors who DO want compile-time autocomplete on builtin ids
+ * can import it without dragging the registry's data graph in
+ * unnecessarily — the registry's value side is tree-shakeable.
+ */
+/**
+ * Identity of a host-shipped icon. The narrow string-literal union
+ * is exported from `@ingcreators/annot-core/editor/icons/registry`
+ * via `keyof typeof BUILTIN_ICONS`; this Tier A alias keeps the
+ * structural shape (a string) so non-registry consumers can name
+ * the type without importing the registry's data.
+ *
+ * Plugin authors should prefer the narrow union exported from the
+ * `@ingcreators/annot-core/icons` subpath (which re-exports the
+ * registry's `BuiltinIconId`) for compile-time autocomplete — at
+ * runtime the two are identical (both are `string`).
+ */
+export type BuiltinIconId = string;
+/**
+ * Plugin-friendly icon descriptor. Discriminated on `kind`:
+ *
+ * - `"builtin"` — refers to a host-provided registry icon by id.
+ *   Cheapest at runtime (no parsing, no sanitisation); recommended
+ *   whenever a suitable host icon exists. Plugins cross-check the
+ *   available ids by importing `BUILTIN_ICON_IDS` from the
+ *   registry; passing an id that isn't in the registry is treated
+ *   as "no icon" by the renderer (returns the empty string / null).
+ *
+ * - `"svg"` — raw inline SVG markup. Use for plugin-owned
+ *   logomarks not present in the host registry. Sanitised at
+ *   render time (Phase 3 allow-list walker — see
+ *   `docs/plans/svg-icons-and-plugin-icon-spec.md`). Plugin
+ *   authors MUST author stand-alone `<svg>` elements (no
+ *   surrounding HTML); the renderer refuses anything that doesn't
+ *   parse as a single SVG root.
+ *
+ * - `"url"` — same-origin or `data:` URL pointing at an SVG asset.
+ *   Used by plugins that ship their logomark as a static asset
+ *   bundled with the plugin's JS. The host renders this via
+ *   `<img src=…>` so the SVG is sandboxed (no CSS / script access
+ *   to the host page). External-origin URLs are rejected at
+ *   render time.
+ */
+export type IconSpec = {
+    readonly kind: "builtin";
+    readonly id: BuiltinIconId;
+} | {
+    readonly kind: "svg";
+    readonly svg: string;
+} | {
+    readonly kind: "url";
+    readonly url: string;
+};
+/** `IconSpec` constructor for a host registry id. Equivalent to
+ *  writing `{ kind: "builtin", id }` inline; the helper makes
+ *  call sites less noisy when an `IconSpec` is built dynamically
+ *  (e.g. mapping a list of names to specs). */
+export declare function builtinIcon(id: BuiltinIconId): IconSpec;
+/** `IconSpec` constructor for raw plugin-supplied SVG markup. The
+ *  string is NOT validated here — sanitisation happens at render
+ *  time (Phase 3). */
+export declare function svgIcon(svg: string): IconSpec;
+/** `IconSpec` constructor for a same-origin or `data:` URL. The
+ *  URL is NOT validated here — the renderer enforces same-origin
+ *  / `data:`-only at render time. */
+export declare function urlIcon(url: string): IconSpec;
+/** Type guard for the `"builtin"` arm. Useful in renderer / plugin
+ *  code that needs to pick a different rendering strategy per
+ *  kind. */
+export declare function isBuiltinIcon(spec: IconSpec): spec is {
+    readonly kind: "builtin";
+    readonly id: BuiltinIconId;
+};
+/** Type guard for the `"svg"` arm. */
+export declare function isSvgIcon(spec: IconSpec): spec is {
+    readonly kind: "svg";
+    readonly svg: string;
+};
+/** Type guard for the `"url"` arm. */
+export declare function isUrlIcon(spec: IconSpec): spec is {
+    readonly kind: "url";
+    readonly url: string;
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './headless.js';