@ingcreators/annot-core 0.1.0

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

@@ -0,0 +1,212 @@
+import { TextRun } from '../utils/desktop-bridge.js';
+import { TextVariant } from './tool-options.js';
+export declare function stickyBgFor(color: string): string;
+/** In-place text-shape color update.
+ *
+ *  Writes the color to:
+ *    - `data-color` on the wrapper (the cache attr that survives
+ *      save / paste / Office round-trips when the inner `<text>`
+ *      gets re-rendered).
+ *    - `fill` on the inner `<text>` child (what the SVG renderer
+ *      paints).
+ *    - For sticky / callout variants: `fill` on the bg `<rect>`
+ *      and the tail `<path>` derived from `stickyBgFor(color)`,
+ *      so the body tint follows the text color the way it would
+ *      if the wrapper were freshly built.
+ *
+ *  Text-on-shape wrappers (see `isTextOnShape`) carry the user's
+ *  drawn fill on the geometry primitive; the bg fill stays
+ *  untouched here so a deliberate user-set color isn't
+ *  overwritten by the text-color change.
+ *
+ *  Tier B — pure jsdom-friendly element manipulation, no live-
+ *  canvas dependency. Used by both PropertyPanel's textColor
+ *  effect and TextTool's commit path so a sticky's body tint
+ *  stays in lockstep with its text color across both surfaces. */
+export declare function applyTextShapeColor(g: SVGElement, color: string): void;
+/** Plain-text view of a run array — joins runs in order with `\n`
+ *  inserted at every `line_break_after`. Useful when an editor
+ *  wants the unstyled body (e.g. for the contentEditable seed). */
+export declare function runsToPlainText(runs: readonly TextRun[]): string;
+/** Build a uniformly-styled run array from a plain-text string,
+ *  one run per line. Convenience for callers that don't yet emit
+ *  styled runs (Phase 1's TextTool, the contentEditable commit
+ *  before Phase 2's rich-text mapper, …). */
+export declare function plainTextToRuns(text: string): TextRun[];
+/** Horizontal text alignment inside the shape box. Maps onto
+ *  SVG's `text-anchor` (`start` / `middle` / `end`). */
+export type TextAnchor = "start" | "middle" | "end";
+/** Vertical text alignment inside the shape box. SVG has no
+ *  built-in vertical-anchor attribute on `<text>`, so the
+ *  layout pass computes the y-origin from total run height +
+ *  the vanchor value (`top` / `middle` / `bottom`). */
+export type TextVerticalAnchor = "top" | "middle" | "bottom";
+/** Auto-fit policy for a text-bearing shape (matches PowerPoint's
+ *  three radio options under Format Shape → Text Box):
+ *
+ *    "none"   — text is clipped to the box; the user resizes
+ *               the box to make room. Default.
+ *    "shrink" — text shrinks (scales font-size down) when it
+ *               overflows so it always fits. Currently records
+ *               intent only — the layout pass that does the
+ *               actual scaling is a follow-up.
+ *    "resize" — the box grows (height) so the text always fits
+ *               without clipping. Width stays fixed.
+ *
+ *  Stored on the wrapper as `data-text-autofit`. */
+export type TextAutofit = "none" | "shrink" | "resize";
+/** Per-side text-box padding in user-space units. PowerPoint's
+ *  "Text Box → Margins" surface; defaults map to the legacy
+ *  hard-coded inset (10 px on plain & callout, 2 px on plain).
+ *  Stored on the wrapper as `data-text-margin-{l,r,t,b}` so the
+ *  per-side margins survive variant changes / re-edits. */
+export interface TextMargins {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+export interface TextShapeSpec {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    variant: TextVariant;
+    /** Per-run text content + per-character formatting. Use
+     *  `plainTextToRuns(s)` to bridge from plain text. */
+    runs: TextRun[];
+    /** Default font size (px) for runs without a per-run override. */
+    fontSize: number;
+    /** Default font family for runs without a per-run override. */
+    fontFamily: string;
+    /** Default text color for runs without a per-run override. */
+    color: string;
+    /** Horizontal alignment inside the shape box. Defaults to
+     *  `start` for the auto-bg variants (plain / sticky / callout,
+     *  matching the pre-Phase-3 layout) and to `middle` for
+     *  text-on-shape kinds (PowerPoint default). */
+    textAnchor?: TextAnchor;
+    /** Vertical alignment inside the shape box. Defaults to
+     *  `top` for the auto-bg variants, `middle` for text-on-shape. */
+    textVerticalAnchor?: TextVerticalAnchor;
+    /** Callout tail tip in canvas coordinates. If undefined and the
+     *  variant is "callout", a default position (below-left of the box)
+     *  is picked. */
+    tailX?: number;
+    tailY?: number;
+}
+/** Returns true when the wrapper is a text-on-shape variant —
+ *  i.e. the wrapper was promoted from a Shape-tool primitive
+ *  (`rect` / `rounded` / `ellipse`) via `wrapBareRectForText`,
+ *  so the geometry primitive carries the user's drawn fill /
+ *  stroke. The other text-bearing variants (`plain` / `sticky` /
+ *  `callout`) carry an auto-generated bg whose tint follows the
+ *  text color via `stickyBgFor`.
+ *
+ *  Used by:
+ *    - `applyTextShapeColor` (above) to skip the bg-fill refresh
+ *      for user-drawn geometry.
+ *    - `TextTool` to decide whether to hide the wrapper or just
+ *      its `<text>` child during edit, and whether the editor
+ *      overlay should paint its own yellow background or stay
+ *      transparent.
+ *
+ *  Returns false for non-text-shape elements (no `data-type`,
+ *  raw `<rect>`, etc.) so callers can use it as a discriminator
+ *  without an outer `isTextShapeElement` guard. */
+export declare function isTextOnShape(el: Element): boolean;
+/** Returns true when the element is a unified text-bearing shape
+ *  (`<g data-type="shape" data-shape-kind="...">`). */
+export declare function isTextShapeElement(el: Element): boolean;
+export declare function detectTextVariant(g: SVGElement): TextVariant;
+/** Read the spec off an existing text-bearing shape. Used when
+ *  converting variant or re-rendering after an edit. */
+export declare function readTextShapeSpec(g: SVGElement): TextShapeSpec;
+/**
+ * Construct a fresh text-bearing shape group element that matches
+ * the spec. Does NOT insert it into the DOM; caller is responsible.
+ */
+export declare function createTextShape(spec: TextShapeSpec): SVGGElement;
+/**
+ * Translate a text-bearing shape's children (bg `<rect>`, optional
+ * callout tail `<path>` + `data-tail-*` attrs, optional clipPath
+ * `<rect>`, every positioned `<tspan>` inside the inner `<text>`)
+ * by (dx, dy) in world space.
+ *
+ * Phase 2 of `docs/plans/move-bakes-coordinates.md`. The text-shape
+ * skeleton stores positions in child geometry attrs only; the outer
+ * `<g>` carries no x/y of its own. Shifting all those attrs in place
+ * leaves the visual unchanged when the OLD wrapper transform is
+ * removed and the children are re-read at their new world coords —
+ * which is exactly what the move-baker wants for the move-only
+ * case (no rotation / no flip).
+ *
+ * No-op for non-text-shape inputs. The caller is expected to have
+ * confirmed `g.getAttribute("data-type") === "shape"` before
+ * dispatching here.
+ *
+ * Tier B — pure Element manipulation, jsdom-friendly. The path
+ * shifter routes via `translatePathD` (Tier A), which keeps this
+ * helper independent of any browser-only path APIs.
+ */
+export declare function bakeTextShapeTranslate(g: SVGElement, dx: number, dy: number): void;
+/**
+ * Rebuild the callout tail <path> off the current bg <rect> bounds and
+ * the stored data-tail-x / data-tail-y. Call after any change that
+ * affects either input — resize (bg rect changed) or tail-tip drag
+ * (data-tail-* changed) — to keep the visual consistent.
+ *
+ * No-op for non-callout shapes (or callouts missing the tail path).
+ */
+export declare function rebuildCalloutTail(g: SVGElement): void;
+/**
+ * Update a callout's tail-tip position. Writes the new coords to the
+ * data-tail-* attributes and rebuilds the tail <path>. Coords are in
+ * the textbox's LOCAL space — the caller is responsible for subtracting
+ * any group transform (e.g. translate from a previous drag).
+ */
+export declare function setCalloutTail(g: SVGElement, localTailX: number, localTailY: number): void;
+/** Wrap a bare `<rect>` (drawn by ShapeTool — sharp, rounded, or
+ *  highlight) into the unified `<g data-type="shape">` skeleton so
+ *  the user can add text to it. The original geometry element
+ *  becomes the first child of the wrapper unchanged; we layer a
+ *  `<clipPath>` + an initially empty `<text>` on top so the
+ *  TextTool's edit flow reads / writes through the same skeleton
+ *  it uses for plain / sticky / callout textboxes.
+ *
+ *  Text-on-shape entry path — landed in Phase 3 of
+ *  `docs/plans/_done/rich-text-and-shape-text.md`. The wrapper
+ *  REPLACES the original element in its parent; the caller
+ *  should reassign any selection / undo state to the returned
+ *  `<g>`. See `isTextOnShape` for the runtime predicate that
+ *  matches the resulting wrapper kinds.
+ *
+ *  The matching {@link unwrapBareTextShape} reverses this
+ *  transformation when the user cancels a freshly-opened text
+ *  edit without typing. */
+export declare function wrapBareRectForText(rect: SVGRectElement): SVGGElement;
+/** Replace the `<text>` content of an existing text-bearing shape
+ *  in-place. Used by every TextTool re-edit commit and by the
+ *  PropertyPanel's text effects (color / variant / autofit /
+ *  margins). The wrapper's other children (geometry, clipPath,
+ *  callout tail) are left untouched.
+ *
+ *  Tspan layout follows the same anchor / line-height rules as
+ *  `createTextShape`. Layout reads its origin from the FIRST
+ *  `<rect>` direct child (the geometry primitive — the user's
+ *  drawn rect for text-on-shape, or the auto-generated bg for
+ *  the plain / sticky / callout variants). */
+export declare function replaceRunsInPlace(g: SVGElement, runs: readonly TextRun[]): void;
+/** Reverse a {@link wrapBareRectForText} promotion when the user
+ *  cancels a freshly-opened text edit without typing anything.
+ *  Returns the original geometry element after replacing the
+ *  wrapper in its parent. Idempotent on a non-wrapper element. */
+export declare function unwrapBareTextShape(g: SVGElement): SVGElement;
+/**
+ * Convert an existing text-bearing shape to a different variant.
+ * Preserves position, size, runs, and all metadata. Replaces the
+ * old element in the DOM and returns the new element (caller must
+ * update SelectionManager refs via the PropertyPanel's
+ * onTargetReplaced callback).
+ */
+export declare function convertTextVariant(oldG: SVGElement, newVariant: TextVariant): SVGElement;

package/dist/editor/tool-lifecycle.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Minimal contract a host must satisfy for a `ToolBase` subclass to
+ * draw onto its canvas.
+ *
+ * Three operations cover every tool in the editor:
+ *
+ *   - {@link attachDraft} — mount an in-flight element onto the
+ *     canvas without saving history. Used while the user is still
+ *     dragging; the tool keeps a ref so it can mutate attributes
+ *     each pointer-move and either {@link saveHistory} (commit) or
+ *     `el.remove()` (discard) at pointer-up.
+ *
+ *   - {@link addAnnotation} — atomic "append + save" used by
+ *     click-to-create tools (counter, single-click placements) where
+ *     the element is fully formed at attach time.
+ *
+ *   - {@link saveHistory} — push a history snapshot without changing
+ *     children. Used when the tool committed an in-flight element
+ *     via {@link attachDraft} earlier and the gesture is now
+ *     finished, or when an existing element was mutated in place.
+ */
+export interface ToolDOMSurface {
+    attachDraft(el: SVGElement): void;
+    addAnnotation(el: SVGElement): void;
+    saveHistory(): void;
+}
+/**
+ * Test-only surface that records every call so tests can drive a
+ * tool against an inert sink and assert the resulting sequence of
+ * DOM mutations + history saves.
+ *
+ * `attachDraft` and `addAnnotation` BOTH append the element to the
+ * supplied `host` parent so the tool's subsequent attribute
+ * mutations on the element survive across pointer-move callbacks.
+ * `addAnnotation` additionally bumps `saveCount`. The mock therefore
+ * lets a tool's full pointer-event lifecycle execute without ever
+ * touching a real `CanvasManager`.
+ */
+export interface MockToolSurface extends ToolDOMSurface {
+    /** All elements ever attached as drafts (not yet committed). */
+    readonly drafts: readonly SVGElement[];
+    /** All elements ever passed through `addAnnotation` — the
+     *  click-to-create / atomic case. */
+    readonly committed: readonly SVGElement[];
+    /** Total count of `saveHistory` invocations, including those
+     *  implicit in `addAnnotation`. Tests typically assert this hits
+     *  exactly 1 after a successful single-shape gesture. */
+    saveCount: number;
+}
+/**
+ * Build a {@link MockToolSurface} that mounts attached / added
+ * elements into `host`. The host can be any `Element` that accepts
+ * `appendChild` — typically a freshly-created `<g>` SVG group from
+ * `document.createElementNS` under happy-dom.
+ */
+export declare function createMockToolSurface(host: Element): MockToolSurface;

package/dist/editor/tool-options.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Pure type / interface definitions for the editor's tool layer.
+ * Moved out of `tools/tool-base.ts` (now in
+ * `@ingcreators/annot-editor`) as part of Phase 2 of
+ * `docs/plans/three-package-split.md` — these types are shared
+ * between the editor (which contains the runtime `ToolBase`
+ * class + concrete tool classes) and the rest of `core/editor`
+ * (PropertyPanel was a temporary dependent; the helpers in
+ * `gradient-utils`, `redact-utils`, `shape-utils`, `text-utils`,
+ * `property-controls`, `property-panel-helpers` continue to read
+ * variant strings out of these types).
+ *
+ * Lives in core/editor (Tier B subpath) because consumers run
+ * under jsdom for tests and the types are used at the SVG
+ * element manipulation layer.
+ */
+export type ShapeType = "rect" | "rounded" | "ellipse" | "highlight";
+/** Shape preset for the Counter (Marker) tool. Shared vocabulary
+ *  with ShapeType so users see the same "rect / rounded / circle"
+ *  mental model across tools. */
+export type MarkerShape = "circle" | "rect" | "rounded";
+export type ArrowHead = "none" | "end" | "both";
+export type TextVariant = "plain" | "sticky" | "callout";
+export type DrawStyle = "pen" | "highlighter";
+export type RedactStyle = "mosaic" | "solid" | "blur";
+/** Arrow head shapes (per endpoint). Matches PowerPoint's line panel
+ *  exactly — the six OOXML preset types defined in the ECMA-376
+ *  standard:
+ *    none     — no marker
+ *    arrow    — open / outline triangle
+ *    triangle — filled triangle
+ *    stealth  — narrow filled angular arrow
+ *    diamond  — filled diamond
+ *    oval     — filled circle / oval
+ *  Rendering is path-based (see `arrow-markers.ts`): the head is
+ *  baked into the line's `<path>` data, not a separate `<marker>`
+ *  element in `<defs>`. */
+export type ArrowShape = "none" | "arrow" | "triangle" | "stealth" | "diamond" | "oval";
+/** Per-dimension size preset — matches OOXML's `w` / `len` attribute
+ *  granularity (sm / med / lg). Width is perpendicular to the stem,
+ *  length is along the stem. */
+export type ArrowDim = "sm" | "md" | "lg";
+export type LineCap = "butt" | "round" | "square";
+export type LineJoin = "miter" | "round" | "bevel";
+/** Horizontal text alignment inside a text-bearing shape. Mirrors
+ *  the SELECTION-side `data-text-anchor` (start / middle / end)
+ *  exactly; the Text tool seeds new shapes with this value when set. */
+export type TextAnchor = "start" | "middle" | "end";
+/** Vertical text alignment inside a text-bearing shape. Mirrors
+ *  the SELECTION-side `data-text-vanchor` (top / middle / bottom). */
+export type TextVerticalAnchor = "top" | "middle" | "bottom";
+/** A single gradient stop — color + 0..1 position along the gradient,
+ *  optional transparency. The 2-stop case covers the common PowerPoint
+ *  "fade from A to B" workflow; 3+ stops render fine too. */
+export interface GradientStop {
+    color: string;
+    offset: number;
+    opacity?: number;
+}
+/** Linear-gradient stroke descriptor. When set on an element, the
+ *  serializer emits a <linearGradient> into the SVG defs and references
+ *  it via `stroke="url(#...)"`. */
+export interface GradientSpec {
+    type: "linear";
+    stops: GradientStop[];
+    /** Direction in degrees (0 = left→right, 90 = top→bottom, etc). */
+    angle: number;
+}
+export interface ToolOptions {
+    strokeColor: string;
+    fillColor: string;
+    strokeWidth: number;
+    fontSize: number;
+    strokeDasharray: string;
+    fillOpacity: number;
+    /** Subtype for the unified Shape tool ("rect" / "rounded" / "ellipse").
+     *  Ignored by tools that don't have a shape-family choice. */
+    shapeType?: ShapeType;
+    /** Head configuration for the unified Line/Arrow tool.
+     *    "none" = plain line, "end" = arrow at endpoint (default),
+     *    "both" = bi-directional arrow. Ignored by non-line tools. */
+    arrowHead?: ArrowHead;
+    /** Variant for the unified Text tool.
+     *    "plain"   = text only (no background)
+     *    "sticky"  = text with colored background (default, classic sticky note)
+     *    "callout" = text with pointer tail (speech-bubble-like) */
+    textVariant?: TextVariant;
+    /** Font family CSS value for the Text tool. Defaults to "sans-serif"
+     *  when not specified. Stored on the textbox as `data-font-family`
+     *  so it survives save / reopen / Office paste. */
+    fontFamily?: string;
+    /** Horizontal text alignment for newly-drawn Text shapes. Defaults
+     *  to "start" (left-aligned) when not specified. */
+    textAnchor?: TextAnchor;
+    /** Vertical text alignment for newly-drawn Text shapes. Defaults
+     *  to "top" when not specified. */
+    textVerticalAnchor?: TextVerticalAnchor;
+    /** Style for the Draw tool: normal pen vs highlighter. */
+    drawStyle?: DrawStyle;
+    /** Style for the unified Redact tool. */
+    redactStyle?: RedactStyle;
+    /** Per-end arrow head shapes. When set, override the simpler
+     *  `arrowHead` (which only distinguishes none / end / both). */
+    arrowHeadStart?: ArrowShape;
+    arrowHeadEnd?: ArrowShape;
+    /** Per-end arrow widths (perpendicular to stem) — sm / md / lg. */
+    arrowWidthStart?: ArrowDim;
+    arrowWidthEnd?: ArrowDim;
+    /** Per-end arrow lengths (along stem) — sm / md / lg. */
+    arrowLengthStart?: ArrowDim;
+    arrowLengthEnd?: ArrowDim;
+    /** Stroke opacity (0..1). Separate from fill-opacity. */
+    strokeOpacity?: number;
+    /** SVG stroke-linecap: butt / round / square. */
+    strokeLinecap?: LineCap;
+    /** SVG stroke-linejoin for shapes with corners (rect, path). */
+    strokeLinejoin?: LineJoin;
+    /** Optional gradient override for stroke. */
+    strokeGradient?: GradientSpec;
+    /** Optional gradient override for fill. */
+    fillGradient?: GradientSpec;
+    /** Color for the Highlight shape variant. */
+    highlightColor?: string;
+    /** Shape variant for the Counter (Marker) tool. */
+    markerShape?: MarkerShape;
+}

package/dist/editor/tool-panel-adapter.d.ts

@@ -0,0 +1,105 @@
+import { PropertyControlId, PropertyControlOption } from './property-schema.js';
+import { ToolOptions } from './tool-options.js';
+import { ToolPanelExtraControlId } from './tool-registry.js';
+/** Every id a Tool-side `panelControls` entry can reference, plus
+ *  the Tool-only extras. Drives the type of `TOOL_PANEL_ADAPTERS`'s
+ *  key. */
+export type ToolPanelAdapterId = PropertyControlId | ToolPanelExtraControlId;
+/**
+ * Read / write closure pair routing a single Tool-panel control's
+ * value onto the active preset.
+ *
+ * Most adapters genuinely don't need `toolId` — they target a fixed
+ * `ToolOptions` field regardless of which tool's panel is rendering.
+ * The exception is `tool.typeChips`, whose target field varies by
+ * tool (`shape.shapeType`, `arrow.arrowHead`, …) and is resolved
+ * dynamically via `TOOL_REGISTRY[toolId].variantField`. To keep the
+ * adapter shape uniform, every read / write takes `toolId` and the
+ * implementations that don't need it simply ignore the argument.
+ *
+ * Values are typed `unknown` at the registry level (a generic `T`
+ * runs into the contravariant-position assignability problem when
+ * mixed adapters share a single `Record` literal — the same reason
+ * the SELECTION-side `PropertyControlDef` keeps T at its default).
+ * Each adapter narrows internally via a single `String(value)` /
+ * `Number(value)` / `value as Shape` coercion at the write site;
+ * Phase 2's renderer is responsible for passing the right value
+ * type for the id it's dispatching.
+ *
+ * `selectionDef` (Phase 4 wiring): names the matching SELECTION-side
+ * `PropertyControlId` whose `PROPERTY_CONTROLS[…]` entry supplies the
+ * label / options / min / max / step / unit / allowNone metadata.
+ * `null` for Tool-only ids whose metadata has no SELECTION-side
+ * analogue. Phase 2's renderer doesn't read this yet — Phase 4 is
+ * where the metadata reuse lands.
+ */
+export interface ToolPanelAdapter {
+    /** Read the current value off the preset. */
+    read: (preset: ToolOptions, toolId: string) => unknown;
+    /** Mutate the preset in place. Returning the value or anything
+     *  else is ignored — the caller is responsible for persistence
+     *  (re-saving the preset, re-syncing `ctx.options`, etc.). */
+    write: (preset: ToolOptions, value: unknown, toolId: string) => void;
+    /** SELECTION-side def whose metadata (label / options / ranges)
+     *  this adapter borrows. `null` for Tool-only ids. */
+    selectionDef?: PropertyControlId | null;
+}
+/**
+ * Maps every `panelControls` id to its read / write contract.
+ *
+ * Adapter coverage rules (validated by `tool-panel-adapter.test.ts`):
+ * 1. Every `ToolPanelExtraControlId` has an entry.
+ * 2. Every id used by any tool's `panelControls` array has an entry.
+ * 3. Round-trip per adapter is a no-op: with a fully-populated preset,
+ *    `write(preset, read(preset, toolId), toolId)` leaves the preset
+ *    semantically unchanged (every field the adapter touches reads
+ *    back the same value).
+ *
+ * SELECTION-side ids that aren't (yet) used on the Tool side don't
+ * need an adapter; only the ones the registry actually references.
+ */
+export declare const TOOL_PANEL_ADAPTERS: Readonly<Partial<Record<ToolPanelAdapterId, ToolPanelAdapter>>>;
+/** Static metadata an adapter borrows from its SELECTION-side def.
+ *  Phase 4 makes this the single source of truth for option arrays
+ *  (dash / cap / font), labels, number-input ranges, and the
+ *  `allowNone` color-picker flag — so a UX edit to (say)
+ *  `PROPERTY_CONTROLS.strokeStyle.options` flows through to BOTH
+ *  the SELECTION-side panel AND the Tool-side panel without a
+ *  parallel edit.
+ *
+ *  Per-tool divergences (marker's narrower strokeWidth + fontSize
+ *  ranges, redact's `allowNone: false`, shape's "Fill" label
+ *  override) stay in the renderer as documented exceptions on top
+ *  of this metadata — there's no SELECTION-side equivalent to
+ *  override against. */
+export interface ToolPanelAdapterMetadata {
+    /** SELECTION-side label (e.g. "Color", "Width", "Dash type"). */
+    label: string;
+    /** Option list for `select` / `variantPicker` controls. Tool-side
+     *  consumers decorate each option with a per-id preview SVG
+     *  (dash sample, cap sample, etc.) at render time. */
+    options?: ReadonlyArray<PropertyControlOption>;
+    /** Inclusive lower bound for a number input. */
+    min?: number;
+    /** Inclusive upper bound for a number input. */
+    max?: number;
+    /** Spinner / arrow-key step granularity. */
+    step?: number;
+    /** Trailing unit label (e.g. "pt", "%"). */
+    unit?: string;
+    /** Whether a "No fill" sentinel is offered for color pickers. */
+    allowNone?: boolean;
+}
+/** Look up the SELECTION-side metadata an adapter borrows. Returns
+ *  `null` when the adapter has no `selectionDef` (Tool-only ids
+ *  like `tool.typeChips` / `tool.freehandDone`) or when the named
+ *  def doesn't exist (which would be a registry typo — guarded
+ *  defensively rather than throwing).
+ *
+ *  Tier B — pure: no DOM access, no Element-taking; the returned
+ *  metadata is just the static fields off `PROPERTY_CONTROLS`. */
+export declare function selectionDefMetadata(id: ToolPanelAdapterId): ToolPanelAdapterMetadata | null;
+/** Convenience: list of every adapter id present in the registry.
+ *  Used by the test file to enumerate the adapters without depending
+ *  on `Object.keys` order. */
+export declare const TOOL_PANEL_ADAPTER_IDS: ReadonlyArray<ToolPanelAdapterId>;

package/dist/editor/tool-preset-serde.d.ts

@@ -0,0 +1,43 @@
+import { ToolOptions } from './tool-options.js';
+/** Wire format selector. `snake` rewrites camelCase keys to
+ *  snake_case via the table below (matches the Tauri YAML schema in
+ *  `packages/desktop/src-tauri/src/commands/settings.rs` and the
+ *  TypeScript-side `ToolPreset` interface). `camel` passes the keys
+ *  through unchanged (matches the localStorage / chrome.storage
+ *  blobs, which historically just `JSON.stringify`'d the live
+ *  `ToolOptions`). */
+export type PresetWireFormat = "snake" | "camel";
+/**
+ * Convert a preset object to its wire form. Walks `presetFields` and
+ * copies each defined value to the output, optionally rewriting the
+ * key to snake_case. `undefined` values are dropped (matches
+ * `JSON.stringify`'s behaviour, plus keeps the on-disk YAML diff-
+ * friendly).
+ *
+ * Caller decides which fields are part of the wire schema by passing
+ * the tool's `TOOL_REGISTRY[id].presetFields`. Adding a new field to
+ * a tool means one entry in that array — no edit to this file
+ * required (unless the field is brand-new and missing from the
+ * `FIELD_TO_SNAKE` table, in which case `format: "snake"` will fall
+ * through to camelCase for that field).
+ */
+export declare function presetToWire(opts: Partial<ToolOptions>, presetFields: ReadonlyArray<keyof ToolOptions>, format: PresetWireFormat): Record<string, unknown>;
+/**
+ * Inverse of `presetToWire`. Reads each `presetFields` entry off
+ * `record` (looking under the appropriate wire-format key) and
+ * returns a partial `ToolOptions` containing the present values.
+ *
+ * Empty strings on optional fields are treated as "absent" — the old
+ * imperative loader applied `|| undefined` to most variant fields
+ * (`shape_type`, `arrow_head`, …) so a corrupted-empty value didn't
+ * pollute the in-memory preset. We preserve that here uniformly so
+ * the helper is safe to use on every field, not just the ones that
+ * had the explicit `|| undefined` in the old code.
+ */
+export declare function presetFromWire(record: Record<string, unknown>, presetFields: ReadonlyArray<keyof ToolOptions>, format: PresetWireFormat): Partial<ToolOptions>;
+/** Translate a snake_case wire key back to its camelCase
+ *  `ToolOptions` field name, or `undefined` if the key isn't in the
+ *  shared SerDe table. Exposed as a low-level helper for callers
+ *  (e.g. preset-key migration paths) that operate on raw wire
+ *  records without the tool-fields filter. */
+export declare function fieldForSnakeKey(snakeKey: string): keyof ToolOptions | undefined;