@ingcreators/annot-core 0.1.0

package/dist/editor/property-schema.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Coarse property-panel category an SVG element falls into. The
+ * editor's PropertyPanel uses the category to pick which control
+ * set to render; the values intentionally mirror the historical
+ * `if (isTextbox) ... else if (isMarker) ... else ...` chain.
+ */
+export type PropertyCategory = "textbox" | "marker" | "redact-mosaic" | "redact-solid" | "redact-blur" | "highlight" | "group" | "shape";
+/** Stable IDs used both as map keys in the panel and as test
+ *  fixtures so a follow-up "schema-driven render" can swap the
+ *  imperative `#renderXxxControls` chain for a declarative table. */
+export declare const PROPERTY_CONTROL_IDS: {
+    readonly shapeTypePicker: "shapeTypePicker";
+    readonly arrowVariantPicker: "arrowVariantPicker";
+    readonly drawStylePicker: "drawStylePicker";
+    readonly fillColor: "fillColor";
+    readonly strokeColor: "strokeColor";
+    readonly strokeWidth: "strokeWidth";
+    readonly strokeStyle: "strokeStyle";
+    readonly textVariantPicker: "textVariantPicker";
+    readonly textColor: "textColor";
+    readonly fontFamily: "fontFamily";
+    readonly fontSize: "fontSize";
+    /** Per-character bold toggle for the selected textbox. Phase 4
+     *  of `docs/plans/rich-text-and-shape-text.md`. Modelled as a
+     *  two-option `select` ("Off" / "On") so the existing
+     *  `select`-type renderer is reused; future Phase-4-prime work
+     *  can introduce a dedicated `toggle` control type if visual
+     *  polish demands a different affordance. */
+    readonly textBold: "textBold";
+    readonly textItalic: "textItalic";
+    readonly textUnderline: "textUnderline";
+    /** Horizontal text alignment inside the shape — start / middle /
+     *  end. Writes `data-text-anchor` on the wrapper `<g>` and
+     *  re-runs the layout pass. */
+    readonly textAnchor: "textAnchor";
+    /** Vertical text alignment inside the shape — top / middle /
+     *  bottom. Writes `data-text-vanchor` on the wrapper `<g>` and
+     *  re-runs the layout pass. */
+    readonly textVerticalAnchor: "textVerticalAnchor";
+    /** PowerPoint-style autofit policy — none / shrink / resize.
+     *  `resize` extends the wrapper geometry's height so the
+     *  rendered run block fits without clipping; `shrink` records
+     *  the intent (the layout side that scales the font-size is a
+     *  follow-up); `none` lets the box clip to its current
+     *  dimensions. Stored as `data-text-autofit` on the wrapper. */
+    readonly textAutofit: "textAutofit";
+    /** Per-side text-box margin in user-space units (mirrors
+     *  PowerPoint's left / right / top / bottom margins). Stored
+     *  as `data-text-margin-{l,r,t,b}` on the wrapper; the layout
+     *  pass reserves the matching pixel inset around the run
+     *  block. */
+    readonly textMarginLeft: "textMarginLeft";
+    readonly textMarginRight: "textMarginRight";
+    readonly textMarginTop: "textMarginTop";
+    readonly textMarginBottom: "textMarginBottom";
+    readonly redactStylePicker: "redactStylePicker";
+    readonly redactSolidColor: "redactSolidColor";
+    readonly highlightColorPicker: "highlightColorPicker";
+    readonly highlightTransparency: "highlightTransparency";
+    readonly markerShapePicker: "markerShapePicker";
+    readonly markerSize: "markerSize";
+    readonly markerBgFillColor: "markerBgFillColor";
+    readonly markerBgStrokeColor: "markerBgStrokeColor";
+    readonly markerBgStrokeWidth: "markerBgStrokeWidth";
+    readonly markerBgStrokeStyle: "markerBgStrokeStyle";
+    readonly markerLabelValue: "markerLabelValue";
+    readonly fillOpacity: "fillOpacity";
+    readonly strokeOpacity: "strokeOpacity";
+    readonly strokeLinecap: "strokeLinecap";
+    readonly arrowStartShape: "arrowStartShape";
+    readonly arrowStartSize: "arrowStartSize";
+    readonly arrowEndShape: "arrowEndShape";
+    readonly arrowEndSize: "arrowEndSize";
+};
+export type PropertyControlId = (typeof PROPERTY_CONTROL_IDS)[keyof typeof PROPERTY_CONTROL_IDS];
+/**
+ * The (potentially-applicable) controls for each category. Whether
+ * a given control actually shows up still depends on per-element
+ * fine-grained checks (e.g. "Fill is hidden for stroke-only shapes
+ * like <line>"). The shape registry is the upper bound that drives
+ * eventual schema-driven rendering; the panel is free to filter
+ * further at render time.
+ */
+export declare const CATEGORY_CONTROL_SHAPE: Readonly<Record<PropertyCategory, readonly PropertyControlId[]>>;
+/** Discriminator for how the renderer should display a control. The
+ *  values map onto leaf widget families that already exist in
+ *  `@ingcreators/annot-editor` (color pull-buttons, pp-number inputs,
+ *  custom-select dropdowns, prop-choice-chip rows). Sections are
+ *  layout-only and don't appear here — they're a renderer concern,
+ *  not a control. */
+export type PropertyControlType = "color" | "number" | "select" | "variantPicker";
+/**
+ * Identifier for a Tier C-only side-effect a control's mutation requires.
+ *
+ * Several setters (arrow head regeneration, freehand pen↔highlighter
+ * conversion, marker geometry rescale, redact mosaic/blur baking) live
+ * in `@ingcreators/annot-editor` because they either need the live
+ * `<canvas>` for pixel sampling or wrap helpers that grew up co-located
+ * with the tool classes. Tier B can't import those without creating a
+ * reverse package dependency, so the registry references them by
+ * stable id and Phase 2's renderer (in Tier C) supplies the matching
+ * implementations.
+ */
+export declare const PROPERTY_EFFECT_IDS: {
+    /** Switch an arrow's per-end variant (none / end / both) — calls
+     *  `applyArrowHead` from `tools/arrow-tool` which regenerates the
+     *  composed `<path>`'s `d` attribute. */
+    readonly applyArrowVariant: "applyArrowVariant";
+    /** Toggle a freehand element between pen and highlighter — calls
+     *  `applyDrawStyle` from `tools/freehand-tool` which sets stroke
+     *  attrs across the wrapper group's `<path>` children. */
+    readonly applyDrawStyle: "applyDrawStyle";
+    /** Swap a marker's bg primitive (circle ↔ rect ↔ rounded) — calls
+     *  `convertMarkerShape` from `tools/marker-tool` which mutates the
+     *  outer `<g>` in place. */
+    readonly applyMarkerShape: "applyMarkerShape";
+    /** Resize a marker proportionally — calls `resizeMarker` from
+     *  `tools/marker-tool` which scales bg + text together. */
+    readonly resizeMarker: "resizeMarker";
+    /** Convert a redact element between mosaic / solid / blur — calls
+     *  `convertRedactStyle` from `redact-utils`, which is **async** and
+     *  needs `CanvasManager` access to sample the underlying base image
+     *  for mosaic / blur baking. */
+    readonly applyRedactStyle: "applyRedactStyle";
+    /** Set a textbox's text color and (for sticky / callout variants
+     *  whose bg is derived from the text color) regenerate the bg via
+     *  `convertTextVariant`. Plain textboxes get the simple attribute
+     *  write; sticky / callout get a bg-recreation pass that produces
+     *  a fresh element so the per-target `oldEl !== newEl` swap is
+     *  picked up by `onTargetReplaced`. */
+    readonly applyTextColor: "applyTextColor";
+    /** Per-end arrow effect handlers (Phase C). Each updates a single
+     *  field of `detectArrowEnds(el)` and re-applies the spec via
+     *  `applyArrowHead`. Split into 4 ids (rather than one shared
+     *  handler with a diff-object value) so each registry def's
+     *  `effect` field still encodes "which end + which field" without
+     *  the renderer needing to thread extra context to the handler. */
+    readonly applyArrowStartShape: "applyArrowStartShape";
+    readonly applyArrowStartSize: "applyArrowStartSize";
+    readonly applyArrowEndShape: "applyArrowEndShape";
+    readonly applyArrowEndSize: "applyArrowEndSize";
+};
+export type PropertyEffectId = (typeof PROPERTY_EFFECT_IDS)[keyof typeof PROPERTY_EFFECT_IDS];
+/** Display affordance for a single option in a `variantPicker` /
+ *  `select` control. Exactly one of `materialIcon` / `iconSvg` /
+ *  `swatchColor` should be set; the renderer dispatches on whichever
+ *  is present. */
+export interface PropertyControlOption<T = unknown> {
+    value: T;
+    label: string;
+    /** Builtin icon id (e.g. "text_fields"). Rendered via
+     *  `renderIconHtml(builtinIcon(materialIcon))` from the
+     *  `@ingcreators/annot-core/editor/icons` registry. The legacy
+     *  `materialIcon` field name is preserved so `PROPERTY_CONTROLS`
+     *  data tables don't have to be rewritten. */
+    materialIcon?: string;
+    /** Inline SVG markup (already-serialized string). Used when the
+     *  glyph isn't available as a Material Symbol or where the icon
+     *  family needs hand-rolled geometry for clarity (shape / arrow /
+     *  counter pickers). */
+    iconSvg?: string;
+    /** Color swatch — paints `--swatch-color` on the chip's swatch
+     *  element. Used by the highlight color picker, where the variant
+     *  IS the color. */
+    swatchColor?: string;
+}
+/**
+ * Declarative descriptor for a single PropertyPanel control. The
+ * registry below maps every `PropertyControlId` to one of these.
+ *
+ * **Mutation contract:** each def supplies exactly ONE of:
+ *   - `setValue(el, value)` — in-place attribute mutation, Tier B-only
+ *     logic. The renderer calls this directly.
+ *   - `replace(el, value)` — element-replacement (e.g. converting a
+ *     rectangle to an ellipse). Returns the new element, which the
+ *     renderer hands back to PropertyPanel via `onTargetReplaced`.
+ *   - `effect: PropertyEffectId` — Tier C-only operation. The renderer
+ *     looks the id up in its effect-handler table and dispatches.
+ *     Used for arrow / draw-style / marker / redact converters that
+ *     either need `CanvasManager` (redact) or wrap helpers that live
+ *     in `@ingcreators/annot-editor` (the rest).
+ */
+export interface PropertyControlDef<T = unknown> {
+    id: PropertyControlId;
+    type: PropertyControlType;
+    /** Human-readable label shown next to the control (e.g. "Color",
+     *  "Width"). Variant pickers omit a separate label — their chip
+     *  row IS the label, anchored under the section header. */
+    label: string;
+    /** Pure read of the current value off an SVG element. Always
+     *  implemented in Tier B. */
+    getValue: (el: SVGElement) => T;
+    /** In-place mutation. Tier B-only — no `CanvasManager`, no host
+     *  callbacks. Mutually exclusive with `replace` and `effect`. */
+    setValue?: (el: SVGElement, value: T) => void;
+    /** Element replacement. Returns the new element to swap into the
+     *  DOM. Tier B-only. Mutually exclusive with `setValue` and `effect`. */
+    replace?: (el: SVGElement, value: T) => SVGElement;
+    /** Tier C-only side effect; the renderer must supply an
+     *  implementation bound to this id. Mutually exclusive with
+     *  `setValue` and `replace`. */
+    effect?: PropertyEffectId;
+    /** Optional gating predicate. Returning `false` tells the renderer
+     *  to skip this control for the current selection's first element
+     *  (e.g. "Fill is hidden when the element is line-like"). */
+    visibleWhen?: (el: SVGElement) => boolean;
+    /** Optional metadata for variant pickers / select dropdowns. */
+    options?: ReadonlyArray<PropertyControlOption<T>>;
+    /** Dynamically-computed options. When present AND the def's
+     *  `type === "select"` (or future "variantPicker"), the renderer
+     *  calls this with the current sample target instead of reading
+     *  the static `options` field. Lets per-end arrow shape pickers
+     *  filter by the current variant without forcing the registry
+     *  to know about cross-control state. Functions receive the same
+     *  `Element` instance the renderer passes to `getValue` /
+     *  `visibleWhen`. */
+    getOptions?: (el: SVGElement) => ReadonlyArray<PropertyControlOption<T>>;
+    /** Number of columns for the select popup grid. Defaults to 1
+     *  (vertical list). Used by per-end arrow shape (3 cols for the
+     *  6-shape OOXML grid) and size (3 cols for the 3×3 width × length
+     *  grid) selects to match PowerPoint's layout exactly. */
+    selectColumns?: number;
+    /** Width hint (px) for the select popup. Used alongside
+     *  `selectColumns` to size the per-end arrow grids. */
+    selectPopupWidth?: number;
+    /** Inclusive lower bound for a number input. */
+    min?: number;
+    /** Inclusive upper bound for a number input. */
+    max?: number;
+    /** Spinner / arrow-key step granularity for a number input. */
+    step?: number;
+    /** Trailing unit label for a number input (e.g. "pt", "%"). */
+    unit?: string;
+    /** Whether a "No fill" sentinel is offered alongside the palette
+     *  (only applies to `type === "color"` controls — fill paints can
+     *  be unset, strokes generally cannot). */
+    allowNone?: boolean;
+}
+/**
+ * The complete set of declarative control definitions PropertyPanel
+ * renders. Phase 1 of `docs/plans/property-panel-schema.md`: the
+ * data structure, with no consumer yet — the panel still uses the
+ * imperative `#renderXxxControls` chain. Phase 2 builds the renderer;
+ * Phase 3 migrates the panel to use it.
+ */
+export declare const PROPERTY_CONTROLS: Readonly<{
+    [K in PropertyControlId]: PropertyControlDef;
+}>;
+/** Returns the categorical bucket for a single SVG element. */
+export declare function classifyPropertyElement(el: Element): PropertyCategory;
+/**
+ * Coerce a heterogeneous selection to a single category. Returns
+ * `null` when the selection mixes categories — at which point the
+ * panel typically falls back to either an empty render or the
+ * category of the FIRST element. The legacy `show()` always used
+ * the first element; this helper preserves that behaviour while
+ * exposing the "are they all the same?" check for any future
+ * "edit shared properties only" mode.
+ */
+export declare function classifyPropertySelection(elements: readonly Element[]): {
+    category: PropertyCategory | null;
+    uniform: boolean;
+};

package/dist/editor/rich-text-mapper.d.ts

@@ -0,0 +1,8 @@
+import { TextRun } from '../utils/desktop-bridge.js';
+/** Convert a contentEditable subtree into the canonical
+ *  `TextRun[]` representation. Empty input → empty array. */
+export declare function htmlToRuns(root: HTMLElement | DocumentFragment): TextRun[];
+/** Inverse of `htmlToRuns`. Emits an HTML string the
+ *  contentEditable can ingest as `innerHTML` or compose into a
+ *  document fragment for `appendChild`. */
+export declare function runsToHtml(runs: readonly TextRun[]): string;

package/dist/editor/selection-geometry.d.ts

@@ -0,0 +1,66 @@
+/** Plain rectangle shape. Structurally compatible with `DOMRect`, so
+ *  existing callers passing `DOMRect[]` continue to typecheck. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Rotate the point `(px, py)` around the pivot `(cx, cy)` by `rad`
+ * radians (positive = counter-clockwise in screen-space terms,
+ * which matches Math.cos / Math.sin convention).
+ */
+export declare function rotateAround(px: number, py: number, cx: number, cy: number, rad: number): {
+    x: number;
+    y: number;
+};
+/** Pick the appropriate axis-aligned cursor for the angle at which a
+ *  resize handle sits relative to its element's centre.
+ *
+ *  The angle is normalised into `[0, 2π)`, offset by π/8 so cursor
+ *  "centres" align with E/SE/S/SW/W/NW/N/NE, then bucketed into 8
+ *  equal 45° sectors. */
+export declare function cursorForAngle(rad: number): string;
+export interface SnapGuide {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+export interface SnapResult {
+    /** Adjusted drag delta in world units — what the caller should
+     *  apply instead of the raw pointer delta. */
+    dx: number;
+    dy: number;
+    /** World-space line segments to render as dashed guides. Each
+     *  guide is an axis-aligned line through the snap point. */
+    guides: SnapGuide[];
+}
+export interface SnapInput {
+    /** Bounding boxes of the dragged (selected) elements in world
+     *  space, computed BEFORE applying the current delta. */
+    draggedBoxes: readonly Rect[];
+    /** Raw pointer delta the caller wants to apply. */
+    dx: number;
+    dy: number;
+    /** Bounding boxes of NON-dragged elements to snap against. */
+    otherBoxes: readonly Rect[];
+    /** Snap activation radius in world units. Typically 4–6 px. */
+    threshold: number;
+}
+/**
+ * Compute a snapped drag delta and the guide lines to render.
+ *
+ * Snap candidates per axis (for each dragged-bbox edge):
+ *   left   ↔ other's left, center-x, right
+ *   center ↔ same three
+ *   right  ↔ same three
+ * Same six comparisons on Y. That's 18 candidate offsets per
+ * (dragged-union, other) pair; the smallest absolute delta per axis
+ * wins, breaking ties by edge-similarity.
+ *
+ * Returns the raw `dx` / `dy` unmodified when no snap candidate is
+ * within `threshold`.
+ */
+export declare function computeSnap(input: SnapInput): SnapResult;

package/dist/editor/shape-utils.d.ts

@@ -0,0 +1,27 @@
+import { ShapeType } from './tool-options.js';
+/**
+ * Classify an existing SVG element as one of the three Shape variants,
+ * or null if it isn't a shape.
+ */
+export declare function detectShapeType(el: SVGElement): ShapeType | null;
+/**
+ * Return the element's canvas-space bounding box as (x, y, w, h).
+ * Works for both <rect> (x/y/w/h attrs) and <ellipse> (cx/cy/rx/ry).
+ */
+export declare function shapeBBox(el: SVGElement): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Convert a Shape element to a different variant in place. Preserves
+ * the bounding box (same x/y/w/h visual footprint) and common style
+ * attributes (stroke, fill, dash, etc.).
+ *
+ * Returns the NEW element, which has been inserted into the DOM in
+ * the same position as the old one. The old element is removed.
+ * Callers must update any references they hold (SelectionManager,
+ * PropertyPanel targets, etc.) to point at the returned element.
+ */
+export declare function convertShape(oldEl: SVGElement, newType: ShapeType): SVGElement;

package/dist/editor/svg-format.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Annot SVG format version — the lever for evolving the annotation
+ * format while keeping old files readable.
+ *
+ * Every SVG Annot writes carries a `data-annot-version="N"` attribute
+ * on its root. Readers can inspect that attribute to know which schema
+ * a given document was written with and (eventually) run migrations.
+ *
+ * See `docs/svg-format.md` for the full format specification.
+ *
+ * Current version: 1 (initial versioned format — April 2026).
+ *
+ * ## Why a string, not a number
+ *
+ * Treating the version as a string leaves room for "1.1" / "2-rc1" /
+ * "next" style pre-release identifiers if we ever need them, without
+ * requiring consumers to juggle number-vs-string comparisons later.
+ * The value is still compared as an exact string — no implicit
+ * semver parsing — so there's no surprise ordering.
+ *
+ * ## Migration policy
+ *
+ * New writes ALWAYS stamp the CURRENT version. Old writes with
+ * missing attributes are treated as version "0" (the pre-versioning
+ * era) and read best-effort. When / if a breaking change lands, the
+ * reader gains a `migrateFromV0` / `migrateFromV1` branch; until
+ * then we simply stamp + read-through.
+ */
+/** Current Annot SVG format version. Bump only with a migration. */
+export declare const ANNOT_SVG_VERSION = "1";
+/** The pseudo-version returned for documents written before Annot
+ *  started stamping — i.e. any SVG without the
+ *  `data-annot-version` attribute. Readers treat this as "legacy,
+ *  parse leniently". */
+export declare const ANNOT_SVG_VERSION_UNSTAMPED = "0";
+/** DOM attribute name used to carry the version on the SVG root. */
+export declare const ANNOT_SVG_VERSION_ATTR = "data-annot-version";
+/**
+ * Stamp the current Annot format version onto an SVG root element.
+ * Call right before serializing so every written document carries
+ * the version.
+ *
+ * Idempotent — calling twice leaves the attribute with the same
+ * value. Safe to call on an SVG that already has a stamp (e.g. a
+ * clone of the live editor root, which carries the stamp from
+ * `CanvasManager`'s constructor).
+ */
+export declare function stampAnnotVersion(svgRoot: Element): void;
+/**
+ * Read the format version from a parsed SVG root. Returns the
+ * unstamped sentinel (`"0"`) when the attribute is absent — this is
+ * the signal to a reader that the document predates versioning and
+ * should be parsed with legacy tolerance.
+ */
+export declare function readAnnotVersion(svgRoot: Element): string;
+/**
+ * Cheap string-level version probe — reads the first
+ * `data-annot-version="…"` occurrence in the raw SVG text without
+ * instantiating a DOMParser. Useful at storage-layer boundaries
+ * where parsing is expensive and callers only want a quick
+ * "do I need to upgrade this?" check.
+ *
+ * Returns the unstamped sentinel when no match is found; not
+ * defensive against the attribute appearing mid-string in a CDATA
+ * or attribute value (extremely unlikely in practice, since Annot
+ * emits the attribute on the root well before any content).
+ */
+export declare function getAnnotVersionFromString(svgString: string): string;

package/dist/editor/svg-id-utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * SVG id-rewriting helpers.
+ *
+ * SVG references resolve by document-scope id (`url(#id)` for paint /
+ * clip-path / filter / mask, `href="#id"` / `xlink:href="#id"` for
+ * `<use>` / animation links). When an annotation tree is cloned and
+ * inserted into the same document — paste, scratchpad-stamp, future
+ * "duplicate as template" features — naive `cloneNode(true)` keeps
+ * the original ids on every clone. Two elements share an id, the
+ * browser picks the FIRST one in document order, and the second
+ * shape's ref points at the wrong target. Visible symptom for a
+ * sticky / text-on-shape: the pasted text gets clipped against the
+ * ORIGINAL shape's clipPath (located at the source position, not the
+ * paste point), so the text appears blank.
+ *
+ * `freshenInternalIds` walks a cloned subtree, replaces every
+ * descendant `id` with a fresh one, and rewrites every `url(#id)` /
+ * `href="#id"` reference inside the same subtree to point at the new
+ * id. References to ids OUTSIDE the subtree are left intact (the
+ * original document still has them, and the rewrite would otherwise
+ * silently drop the ref).
+ *
+ * Tier B — pure attribute manipulation, jsdom-friendly. No DOM-API
+ * dependencies beyond `getAttribute` / `setAttribute` / `attributes`.
+ */
+/**
+ * Rewrite every internal id in `root` (and its descendants) to a
+ * fresh `${oldId}-<random>` and update every same-subtree `url(#id)`
+ * / `href="#id"` / `xlink:href="#id"` reference accordingly. The
+ * `root` element ITSELF is NOT renamed, since the caller may want
+ * to keep the wrapper's identity stable; descendants are.
+ *
+ * No-op when the subtree carries no ids. Idempotent in the sense
+ * that re-running yields different (but equally fresh) ids — the
+ * caller should call this exactly once per clone.
+ */
+export declare function freshenInternalIds(root: SVGElement): void;

package/dist/editor/svg-to-annotation-shapes.d.ts

@@ -0,0 +1,34 @@
+import { AnnotationShape } from '../utils/desktop-bridge.js';
+/** Apply a group's `transform="translate(tx, ty)"` (or the
+ *  canonical `data-tx` / `data-ty`) when pulling out coordinates,
+ *  so the resulting shape lands at the same visual position the
+ *  user sees in the editor. Reads `data-tx` / `data-ty` first (the
+ *  transform-utils layer writes them when the visual transform
+ *  attribute has been rewritten as a `matrix(...)` for rotation /
+ *  flip support), then falls back to the literal `transform`
+ *  attribute. */
+export declare function translateOf(el: SVGElement): {
+    tx: number;
+    ty: number;
+};
+/** Pull rotation / flip / line-polish state into the AnnotationShape
+ *  partial. Returned only when non-default so the JSON payload stays
+ *  compact for unstyled shapes. */
+export declare function transformOf(el: SVGElement): Partial<AnnotationShape>;
+/**
+ * Convert one annotation `<g>` / leaf element into an
+ * `AnnotationShape`, or `null` for elements that have no
+ * Office-paste mapping (an unrecognised `<g>` wrapper, etc.).
+ *
+ * Mirrors the per-tag dispatch the toolbar's `#copyForOffice`
+ * historically inlined.
+ */
+export declare function svgElementToAnnotationShape(el: SVGElement): AnnotationShape | null;
+/**
+ * Convert all top-level annotation elements under
+ * `annotationsParent` into `AnnotationShape[]`, skipping any node
+ * that doesn't map to a recognised emitter.
+ */
+export declare function svgAnnotationsToShapes(annotationsParent: {
+    childNodes: ArrayLike<Node>;
+}): AnnotationShape[];