@ingcreators/annot-core 0.1.0

package/dist/utils/assert.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure assertion helpers shared across `@ingcreators/annot-core`,
+ * `@ingcreators/annot-web`, and `@ingcreators/annot-extension`.
+ *
+ * Phase 6 of `docs/plans/source-audit-cleanup.md` introduced the
+ * `assertNonNull` helper as the replacement for the long tail of
+ * silent `value!` non-null assertions: when the assertion is
+ * actually a load-bearing runtime invariant (and not a "the
+ * compiler should have known this" situation), routing through
+ * this helper turns a misleading `Cannot read properties of null`
+ * crash into a meaningful labelled error.
+ *
+ * DOM-free — exported from the headless entry point too.
+ */
+/**
+ * Assert that `v` is neither `null` nor `undefined`. On failure,
+ * throw an `Error` whose message is `Assertion failed: <label>`.
+ *
+ * Prefer this over a bare `value!` whenever:
+ *   - The non-null guarantee depends on a runtime invariant a
+ *     reader can't see at the use site (e.g. "by this point in
+ *     `setupEditor`, `#canvas` has been mounted").
+ *   - The guarantee is fragile (e.g. depends on a Lit element's
+ *     render cycle), and a future refactor could break it.
+ *
+ * Bare `!` stays acceptable for self-evident cases — e.g.
+ * `array.find(...)!` where the search predicate guarantees a hit
+ * by construction. Add a one-line comment if the guarantee
+ * isn't obvious from the surrounding three lines of code.
+ */
+export declare function assertNonNull<T>(v: T | null | undefined, label: string): T;

package/dist/utils/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const JPEG_QUALITY = 0.9;
+export declare const CAPTURE_DELAY_MS = 300;
+export declare const MAX_CANVAS_DIMENSION = 32767;
+export declare const DEFAULT_STROKE_COLOR = "#ff0000";
+export declare const DEFAULT_FILL_COLOR = "none";
+export declare const DEFAULT_STROKE_WIDTH = 3;
+export declare const DEFAULT_FONT_SIZE = 24;
+export declare const MOSAIC_BLOCK_SIZE = 10;
+export declare const REDACT_BLUR_RADIUS = 12;
+export declare const REDACT_SOLID_COLOR = "#111";

package/dist/utils/dash-utils.d.ts

@@ -0,0 +1,6 @@
+/** Dash pattern multipliers (relative to stroke-width), matching Office presets */
+export declare const DASH_MULTIPLIERS: Record<string, number[]>;
+/** Compute SVG stroke-dasharray from a dash key and stroke width */
+export declare function computeDasharray(key: string, strokeWidth: number): string;
+/** Detect dash key from an SVG dasharray string and stroke width */
+export declare function detectDashKey(dasharray: string, strokeWidth: number): string;

package/dist/utils/desktop-bridge.d.ts

@@ -0,0 +1,349 @@
+/**
+ * Desktop IPC bridge — the renderer-side seam every desktop-host
+ * IPC call goes through.
+ *
+ * Production transport is Electron's
+ * `window.electronAPI.invoke(channel, args)` exposed by the
+ * preload script in `packages/desktop/src-electron/preload.ts`.
+ *
+ * **History**: This file's earlier life as `tauri-bridge.ts`
+ * supported a dual Electron / Tauri dispatch during the
+ * Phase 1–8 migration. Phase 9 of
+ * `docs/plans/_done/desktop-electron-migration.md` removed the
+ * Tauri sources + the dual-transport fallback; the bridge now
+ * speaks Electron only. The `isTauri` back-compat alias and the
+ * dynamic `@tauri-apps/api/core` import are gone in this PR
+ * cycle.
+ */
+declare const isDesktop: boolean;
+export { isDesktop };
+/** Library root under the desktop host. Used by `bootstrap.ts`
+ *  to construct `DesktopFs`. */
+export declare function getLibraryRoot(): Promise<string>;
+/** Portable data directory (extension-handoff sweep + legacy-
+ *  data toast). */
+export declare function getPortableDir(): Promise<string>;
+/**
+ * Documentation type for the on-disk tool-preset shape. The
+ * canonical schema — which keys belong to which tool — lives in
+ * `packages/core/src/editor/tool-registry.ts` (`presetFields`
+ * arrays per tool) and `packages/core/src/editor/tool-preset-serde.ts`
+ * (`FIELD_TO_SNAKE` table). The fields enumerated here are the
+ * union of what every tool's `presetFields` resolves to today,
+ * pinned for IDE autocomplete + cross-language schema discoverability.
+ *
+ * History: this interface used to declare a NARROWER schema mirroring
+ * a Rust struct that named only six fields with `#[serde(default = …)]`
+ * — but the Rust struct silently dropped all other fields on save,
+ * orphaning every variant discriminator (shape_type / arrow_head /
+ * shape_kind / draw_style / redact_style / marker_shape /
+ * highlight_color), the per-end arrow shape / width / length, and
+ * stroke opacity / cap / join. The Rust struct is now schema-
+ * transparent (`HashMap<String, serde_yaml::Value>`) and the
+ * Phase 2 Electron port (`src-electron/ipc/settings.ts`) carries
+ * the same property — all keys round-trip through both hosts; this
+ * interface is re-aligned to enumerate the full set toolbar.ts
+ * emits, matching reality.
+ */
+export interface ToolPreset {
+    stroke_color?: string;
+    fill_color?: string;
+    stroke_width?: number;
+    font_size?: number;
+    stroke_dasharray?: string;
+    fill_opacity?: number;
+    /** Subtype for the unified Shape tool (rect / rounded / ellipse). */
+    shape_type?: string;
+    /** Head variant for the unified Line/Arrow tool (none / end / both). */
+    arrow_head?: string;
+    /** Shape kind for text-bearing shapes (plain / sticky / callout). */
+    shape_kind?: string;
+    /** Font family CSS value for the Text tool. */
+    font_family?: string;
+    /** Style for the unified Draw tool (pen / highlighter). */
+    draw_style?: string;
+    /** Style for the unified Redact tool (mosaic / solid / blur). */
+    redact_style?: string;
+    /** Default arrow shapes (per end) — matches OOXML preset types. */
+    arrow_head_start?: string;
+    arrow_head_end?: string;
+    /** Default arrow width / length (per end) — sm / md / lg. */
+    arrow_width_start?: string;
+    arrow_width_end?: string;
+    arrow_length_start?: string;
+    arrow_length_end?: string;
+    /** Selected highlighter color for the Highlight tool. */
+    highlight_color?: string;
+    /** Shape for the Counter (Marker) tool — circle / rect / rounded. */
+    marker_shape?: string;
+    /** Stroke opacity / cap / join. */
+    stroke_opacity?: number;
+    stroke_linecap?: string;
+    stroke_linejoin?: string;
+}
+export interface ToolPresets {
+    /** Preset map. Keys are element keys ("shape.rect", "arrow.end")
+     *  for tools with variants, or bare tool IDs ("crop", "highlight")
+     *  for tools without variants. Legacy files (pre–per-variant
+     *  refactor) may have bare tool IDs like "shape" / "arrow" — the
+     *  loader migrates these to the tool's default variant on read. */
+    tools: Record<string, ToolPreset>;
+    /** Last-used variant per tool. Used to pick which variant's preset
+     *  to activate when the user re-selects the tool. Optional — falls
+     *  back to TOOL_VARIANTS[toolId].fallback when absent. */
+    last_variants?: Record<string, string>;
+}
+export declare function loadToolPresets(): Promise<ToolPresets>;
+export declare function saveToolPresets(presets: ToolPresets): Promise<void>;
+export interface AnnotMetadata {
+    original_image_b64: string;
+    annotations_svg: string;
+    width: number;
+    height: number;
+}
+export declare function saveWithXmp(renderedImageB64: string, originalImageB64: string, annotationsSvg: string, width: number, height: number, filePath: string): Promise<void>;
+export declare function readXmp(filePath: string): Promise<AnnotMetadata | null>;
+export interface CaptureResult {
+    data_url: string;
+    width: number;
+    height: number;
+}
+export interface WindowInfo {
+    /** `desktopCapturer` source id, an opaque string like
+     *  `"window:1234:5"`. The renderer passes it through to
+     *  `capture_window`. */
+    hwnd: string;
+    title: string;
+    class: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare function captureScreen(): Promise<CaptureResult>;
+export declare function listWindows(): Promise<WindowInfo[]>;
+export declare function captureWindow(hwnd: string): Promise<CaptureResult>;
+export declare function captureRegion(x: number, y: number, width: number, height: number): Promise<CaptureResult>;
+export declare function minimizeMainWindow(): Promise<void>;
+export declare function restoreMainWindow(): Promise<void>;
+/**
+ * Unified annotation-shape payload — the input to the shared
+ * OOXML DrawingML builder in `@ingcreators/annot-render`. Used by
+ * both the PPTX export path
+ * (`packages/editor/src/pptx-export.ts`, `ns: "p"`) and the
+ * Office-clipboard path
+ * (`packages/host-ui/src/toolbar.ts:#copyForOffice`,
+ * `ns: "a"`).
+ *
+ * The Electron-side handler
+ * (`packages/desktop/src-electron/ipc/clipboard.ts`) is
+ * packaging-only since
+ * [`office-paste-shared-drawing-builder` phase 3](../../../../docs/plans/_done/office-paste-shared-drawing-builder.md):
+ * the per-shape OOXML is built TS-side and passed to the host as
+ * a pre-assembled drawing XML string. The shape taxonomy below is
+ * what `svgElementToAnnotationShape` produces:
+ *
+ *   type="rect"         Rectangle. Use `corner_radius>0` for rounded
+ *                       variant. Use `redact_style="solid"` for an
+ *                       opaque solid-bar redaction (no outline).
+ *   type="ellipse"      Ellipse.
+ *   type="line" | "arrow"
+ *                       Line. Use `arrow_shape_start / arrow_shape_end`
+ *                       to describe heads (`"none"` or undefined for
+ *                       no head; `"triangle"` / `"arrow"` / `"stealth"`
+ *                       / `"diamond"` / `"oval"` for the OOXML preset
+ *                       head shapes).
+ *   type="text"         Text-bearing shape. `shape_kind` is the
+ *                       discriminator — auto-bg variants (`plain`
+ *                       / `sticky` / `callout`) plus the text-on-
+ *                       shape kinds (`rect` / `rounded` /
+ *                       `ellipse`, see `isTextOnShape`).
+ *                       `runs[]` holds the per-run
+ *                       text content + per-character formatting
+ *                       (bold / italic / underline / mixed font /
+ *                       size / color); for a uniformly-styled
+ *                       textbox `runs` collapses to one entry per
+ *                       line with no formatting flags.
+ *                       `text_bg_color` carries the bg fill;
+ *                       `tail_x` / `tail_y` set for callout (the
+ *                       OOXML emit then uses `wedgeRoundRectCallout`).
+ *   type="freehand"     Freehand path. The SVG path d-string rides
+ *                       on `path_d`. Use `draw_style` for pen vs
+ *                       highlighter; `stroke_opacity_value` carries
+ *                       the semi-transparent highlighter alpha.
+ *   type="mosaic_image" Mosaic-redaction PNG, embedded via data URL
+ *                       in `image_data_url`.
+ *   type="blur_image"   Blur-redaction PNG, same shape as mosaic_image.
+ *   type="marker"       Counter marker; `marker_shape` + `label`.
+ */
+/** A single styled text run inside a text-bearing shape.
+ *
+ * On disk each run corresponds to one `<tspan>` child of the
+ * shape's `<text>` element. Transitions in any of the formatting
+ * fields split the source text into separate runs; runs adjacent
+ * within the same paragraph share an `<a:p>` on the OOXML side,
+ * while `line_break_after === true` ends the paragraph and starts
+ * a new `<a:p>` for the following run.
+ *
+ * Per-run formatting is OPTIONAL — when omitted, the run inherits
+ * the shape-level defaults (`font_size` / `font_family` / `fill`
+ * on the parent `AnnotationShape`). A uniformly-styled textbox
+ * therefore collapses to one run per line with only `text` +
+ * `line_break_after` populated.
+ */
+export interface TextRun {
+    /** Plain text content of this run. Newlines are NOT permitted —
+     *  use `line_break_after` to end a paragraph. */
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    /** Per-run font size override (px). Omit to inherit the shape-
+     *  level `font_size`. */
+    font_size?: number;
+    /** Per-run font family override. */
+    font_family?: string;
+    /** Per-run text color (`#rrggbb`). Omit to inherit the shape-
+     *  level `fill`. */
+    color?: string;
+    /** When true, ends the current paragraph after this run. The
+     *  next run starts in a fresh `<a:p>` on the OOXML side. */
+    line_break_after?: boolean;
+}
+export interface AnnotationShape {
+    type: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    x1?: number;
+    y1?: number;
+    x2?: number;
+    y2?: number;
+    cx?: number;
+    cy?: number;
+    rx?: number;
+    ry?: number;
+    stroke?: string;
+    stroke_width?: number;
+    stroke_dasharray?: string;
+    fill?: string;
+    fill_opacity?: number;
+    /** Corner radius. 0 (or omitted) = sharp; >0 = rounded rectangle. */
+    corner_radius?: number;
+    /** Quadratic-Bezier control-point coordinates for a curved
+     *  arrow, in the same canvas space as `x1/y1/x2/y2`. Both
+     *  populated together; either being absent renders the arrow
+     *  as a straight `<a:prstGeom prst="line">` connector. When
+     *  populated the shared builder swaps to `<a:custGeom>` with a
+     *  `<a:moveTo>` + `<a:quadBezTo>` path so the curve survives
+     *  the paste. */
+    arrow_curve_cx?: number;
+    arrow_curve_cy?: number;
+    /** One entry per `<tspan>` in the source SVG. Style transitions
+     *  split runs; uniformly-styled text collapses to one entry per
+     *  line with no formatting flags. The OOXML emit walks this
+     *  array, opening a new `<a:p>` after each run with
+     *  `line_break_after === true`, otherwise emitting the run as
+     *  one `<a:r>` inside the current paragraph. */
+    runs?: TextRun[];
+    font_size?: number;
+    font_family?: string;
+    /** Discriminator for text-bearing shapes. Phase 1 supports the
+     *  three text-variant values; Phase 3 adds `rect` / `rounded` /
+     *  `ellipse` for text-on-shape. */
+    shape_kind?: "plain" | "sticky" | "callout" | "rect" | "rounded" | "ellipse";
+    /** Sticky / callout background color, in CSS `rgba(...)` or `#rrggbb`
+     *  form. Populated for `shape_kind === "sticky" | "callout"`;
+     *  omitted for plain text. */
+    text_bg_color?: string;
+    /** Horizontal alignment of the run block within the shape. Mirrors
+     *  the wrapper's `data-text-anchor` attribute and flows through to
+     *  OOXML as `<a:pPr algn="…">` per paragraph. Omitted = no
+     *  per-paragraph alignment override (PowerPoint inherits from the
+     *  paragraph default, i.e. left). */
+    text_anchor?: "start" | "middle" | "end";
+    /** Vertical alignment of the run block within the shape. Mirrors
+     *  the wrapper's `data-text-vanchor` attribute and flows through
+     *  to OOXML as `<a:bodyPr anchor="…">`. Omitted = top. */
+    text_vertical_anchor?: "top" | "middle" | "bottom";
+    /** Callout tail-tip coordinates (canvas space). */
+    tail_x?: number;
+    tail_y?: number;
+    /** SVG path d-string for freehand strokes. */
+    path_d?: string;
+    draw_style?: "pen" | "highlighter";
+    /** Discriminator for redactions. A type="rect" + redact_style="solid"
+     *  means an opaque color bar; type="mosaic_image" / "blur_image"
+     *  carry baked-in PNGs. */
+    redact_style?: "solid" | "mosaic" | "blur";
+    /** PNG data URL for mosaic / blur redactions (self-contained). */
+    image_data_url?: string;
+    label?: string;
+    /** Counter background shape. `rounded` is a newer variant — older
+     *  Rust-side consumers that only know `circle`/`rect` will treat
+     *  unknown values as circle (graceful degradation). */
+    marker_shape?: "circle" | "rect" | "rounded";
+    /** Rotation in degrees, CW positive, around the shape's bbox center.
+     *  Omitted (or 0) means no rotation. */
+    rotation_deg?: number;
+    /** Mirrored along the horizontal axis (left/right swap). */
+    flip_h?: boolean;
+    /** Mirrored along the vertical axis (top/bottom swap). */
+    flip_v?: boolean;
+    /** Per-end arrow head shapes — matching OOXML's six preset types
+     *  one-to-one. */
+    arrow_shape_start?: "none" | "arrow" | "triangle" | "stealth" | "diamond" | "oval";
+    arrow_shape_end?: "none" | "arrow" | "triangle" | "stealth" | "diamond" | "oval";
+    /** Per-dimension arrow widths (perpendicular to stem, OOXML `w`). */
+    arrow_width_start?: "sm" | "md" | "lg";
+    arrow_width_end?: "sm" | "md" | "lg";
+    /** Per-dimension arrow lengths (along stem, OOXML `len`). */
+    arrow_length_start?: "sm" | "md" | "lg";
+    arrow_length_end?: "sm" | "md" | "lg";
+    /** Stroke opacity (0..1). Emitted as `<a:alpha val="..."/>` inside
+     *  the stroke's solidFill. */
+    stroke_opacity_value?: number;
+    /** SVG stroke-linecap. Translates to OOXML `<a:ln cap="rnd|sq|flat"/>`. */
+    stroke_linecap?: "butt" | "round" | "square";
+    /** SVG stroke-linejoin. Translates to `<a:miter/>|<a:round/>|<a:bevel/>`. */
+    stroke_linejoin?: "miter" | "round" | "bevel";
+    /** Serialized stroke gradient (JSON). Consumer translates into
+     *  OOXML `<a:gradFill>` inside `<a:ln>`. */
+    stroke_gradient?: {
+        angle: number;
+        stops: Array<{
+            color: string;
+            offset: number;
+            opacity?: number;
+        }>;
+    };
+    /** Serialized fill gradient. */
+    fill_gradient?: {
+        angle: number;
+        stops: Array<{
+            color: string;
+            offset: number;
+            opacity?: number;
+        }>;
+    };
+}
+/** One mosaic / blur image embedded into the GVML clipboard
+ *  package. The caller (TS-side `buildDrawingXml` consumer)
+ *  passes pre-decoded bytes; the host packager writes them at
+ *  `clipboard/media/{filename}` and binds them via the matching
+ *  rId in the drawing rels. */
+export interface MosaicMediaPayload {
+    filename: string;
+    /** Raw image bytes (PNG / JPEG). The IPC adapter JSON-serializes
+     *  this as an array of numbers — fine for the typical mosaic
+     *  payload size (a few KB per patch). */
+    bytes: Uint8Array;
+}
+/**
+ * Office-clipboard copy. The drawing XML + mosaic media list are
+ * pre-built on the TS side; the host's job is to ZIP them up
+ * alongside the screenshot + theme + content_types and push the
+ * result to the OS clipboard.
+ */
+export declare function copyAsOffice(drawingXml: string, mosaicMedia: MosaicMediaPayload[], screenshotData?: string, pngDataUrl?: string): Promise<void>;

package/dist/utils/filename.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Default filename helpers.
+ *
+ * All annot-generated files share a single name shape:
+ *
+ *     annot-YYYYMMDD-HHMMSS-SSS[.annot].<ext>
+ *
+ * Local-time stamping keeps the filename instantly readable for the
+ * user (Drive / GitHub / Finder all show the time the user actually
+ * captured the screen). The matching `createdAt` field on
+ * `ImageRecord` stores the UTC ms epoch separately, so cross-timezone
+ * sync semantics are unaffected.
+ *
+ * Millisecond precision avoids collisions inside the timed-page
+ * capture flow (`pwa-capture` issues frames at 1s+ intervals; even
+ * burst capture stays unique). For the cross-device GitHub / Drive
+ * sync edge case, the existing `uniquifyFilename(Async)` helper
+ * appends a numeric suffix — this format degrades cleanly into
+ * `annot-...-001`, etc.
+ */
+/** Prefix every annot-native default filename with this token. */
+export declare const ANNOT_FILENAME_PREFIX = "annot";
+/**
+ * Format a Date as `YYYYMMDD-HHMMSS-SSS` in local time. Lexicographic
+ * order matches chronological order.
+ */
+export declare function formatLocalTimestamp(date?: Date): string;
+/**
+ * Default filename stem (no extension) for an annot-native capture,
+ * e.g. `annot-20260428-143022-123`.
+ */
+export declare function defaultAnnotFilenameStem(date?: Date): string;
+/**
+ * Default filename for an annot-native image capture, e.g.
+ * `annot-20260428-143022-123.annot.png`. The extension is inferred
+ * from the data URL prefix (`jpg` for `data:image/jpeg`, otherwise
+ * `png`). The `.annot.` infix marks the file as carrying embedded
+ * annotation metadata (XMP for PNG, EXIF for JPG) — used by every
+ * persistent web storage backend (BrowserStore, DeviceStore,
+ * GitHubStore, GoogleDriveStore). The transient extension IDB
+ * deliberately omits the infix; pre-annotation captures aren't
+ * annot-native yet.
+ *
+ * PNG-default for unknown inputs is intentional: every production
+ * caller passes PNG or JPEG, so the fallback only matters for tests
+ * and stray callers — and PNG (lossless) is the safer guess.
+ */
+export declare function defaultAnnotImageFilename(originalDataUrl: string, date?: Date): string;

package/dist/utils/id.d.ts

@@ -0,0 +1,21 @@
+/**
+ * UUIDv7 (RFC 9562) encoded in Base58 (Bitcoin alphabet).
+ *
+ * UUIDv7 layout (128 bits):
+ *   - 48 bits: Unix timestamp in milliseconds (big-endian)
+ *   - 4 bits : version = 0111
+ *   - 12 bits: random (rand_a)
+ *   - 2 bits : variant = 10
+ *   - 62 bits: random (rand_b)
+ *
+ * Base58 uses the Bitcoin alphabet (omits 0, O, I, l) so the resulting
+ * 22-character string is URL-safe and free of visually ambiguous chars.
+ *
+ * The result is time-ordered: IDs minted later compare lexicographically
+ * greater, which is useful for stable filmstrip ordering.
+ */
+/**
+ * Generate a new time-ordered unique ID as a ~22-character Base58 string.
+ * Uses UUIDv7 underneath.
+ */
+export declare function newIdB58(): string;

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+export { assertNonNull } from './assert.js';
+export { DEFAULT_FILL_COLOR, DEFAULT_FONT_SIZE, DEFAULT_STROKE_COLOR, DEFAULT_STROKE_WIDTH, JPEG_QUALITY, MOSAIC_BLOCK_SIZE, REDACT_BLUR_RADIUS, REDACT_SOLID_COLOR, } from './constants.js';
+export { computeDasharray, detectDashKey } from './dash-utils.js';
+export { ANNOT_FILENAME_PREFIX, defaultAnnotFilenameStem, defaultAnnotImageFilename, formatLocalTimestamp, } from './filename.js';
+export { newIdB58 } from './id.js';

package/dist/utils/types.d.ts

@@ -0,0 +1,20 @@
+export interface CaptureRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PageDimensions {
+    scrollWidth: number;
+    scrollHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    devicePixelRatio: number;
+    scrollX: number;
+    scrollY: number;
+}
+export interface CaptureSegment {
+    dataUrl: string;
+    offsetY: number;
+}
+export type CaptureMode = "visible" | "area" | "full";

package/dist/xmp/xmp-browser.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Browser-side XMP metadata embedding for re-editable images.
+ * Mirrors the Rust implementation in src-tauri/src/commands/xmp.rs
+ *
+ * JPEG: XMP in APP1 segment, original image in multiple APP2 segments
+ * PNG:  XMP in iTXt chunk, original image in custom "svGo" chunk
+ */
+export interface EditableImageOptions {
+    /** Rendered image (screenshot + annotations) as Blob */
+    renderedBlob: Blob;
+    /** Original capture image data URL (without annotations) */
+    originalDataUrl: string;
+    /** Annotations-only SVG string */
+    annotationsSvg: string;
+    /** Image dimensions */
+    width: number;
+    height: number;
+    /** Output format */
+    format: "jpg" | "png";
+    /** Key-value tags */
+    tags?: Record<string, string>;
+}
+/**
+ * Create a re-editable image with XMP metadata embedded.
+ * Returns a Blob ready for download.
+ */
+export declare function createEditableImage(opts: EditableImageOptions): Promise<Blob>;
+export interface AnnotMetadata {
+    originalImageDataUrl: string;
+    annotationsSvg: string;
+    width: number;
+    height: number;
+    tags: Record<string, string>;
+}
+/**
+ * Read XMP metadata from a re-editable image file (JPEG or PNG).
+ * Pass the file as an ArrayBuffer or Uint8Array.
+ */
+export declare function readEditableImage(data: Uint8Array): AnnotMetadata | null;

package/dist/zip/zip-builder.d.ts

@@ -0,0 +1,8 @@
+import { buildZipBytes, ZipEntry } from './zip-bytes.js';
+export type { ZipEntry };
+export { buildZipBytes };
+export declare function buildZip(entries: ZipEntry[]): Blob;
+/** Convert a data URL to Uint8Array binary. */
+export declare function dataUrlToBytes(dataUrl: string): Uint8Array;
+/** Detect file extension from data URL mime type. */
+export declare function dataUrlExt(dataUrl: string): string;

package/dist/zip/zip-bytes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tier-A ZIP builder — pure-bytes output, no DOM types.
+ *
+ * Originally lived in `zip-builder.ts` next to a `Blob`-returning
+ * companion. Phase 4 of `desktop-electron-migration.md` introduces
+ * a Node-side caller (`packages/desktop/src-electron/ipc/clipboard.ts`)
+ * whose `tsconfig.json` deliberately omits the DOM lib. Splitting
+ * out this module lets the Node-side import stay DOM-free; the
+ * browser-side `buildZip` continues to wrap `buildZipBytes` in a
+ * `Blob` for callers that want the browser-native shape.
+ *
+ * The output is a Stored-method (uncompressed) ZIP. Images are
+ * already JPEG/PNG-compressed so re-deflating is wasted CPU; the
+ * Office clipboard accepts both Stored and Deflated entries.
+ */
+export interface ZipEntry {
+    /** Filename inside the ZIP (e.g. `"clipboard/drawings/drawing1.xml"`). */
+    name: string;
+    data: Uint8Array;
+}
+/** Build the ZIP and return raw bytes. */
+export declare function buildZipBytes(entries: ZipEntry[]): Uint8Array;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@ingcreators/annot-core",
+  "version": "0.1.0",
+  "description": "Annot SDK — SVG-first screenshot annotation format, storage abstractions, and editor primitives. The foundation shared by the PWA, Chrome extension, Electron desktop, VSCode extension, and the headless annotator.",
+  "license": "Apache-2.0",
+  "author": "ingcreators",
+  "homepage": "https://github.com/ingcreators/annot/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/ingcreators/annot/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ingcreators/annot.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "annotation",
+    "screenshot",
+    "svg",
+    "editor",
+    "storage",
+    "headless",
+    "annot"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./styles/*": "./styles/*"
+  },
+  "files": [
+    "dist",
+    "styles",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/pako": "^2.0.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.13",
+    "vite-plugin-dts": "^5.0.0",
+    "@ingcreators/annot-imagequant": "0.1.0"
+  },
+  "dependencies": {
+    "pako": "^2.1.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  }
+}