@ingcreators/annot-core 0.1.0

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

@@ -0,0 +1,320 @@
+import { PropertyControlId } from './property-schema.js';
+import { ToolOptions } from './tool-options.js';
+/** Tool-side panel sections. The Tool property panel uses the same
+ *  four pp-section buckets as the SELECTION-side property panel, in
+ *  the same visual order (Type → Fill → Line → Label). The renderer
+ *  groups consecutive entries with the same section into a single
+ *  `pp-section` card; section ORDER follows first-encounter in the
+ *  per-tool `panelControls` array. */
+export type ToolPanelSection = "Type" | "Fill" | "Line" | "Label";
+/** Tool-only control ids — affordances the Tool panel renders that
+ *  the SELECTION registry doesn't model. Distinct from
+ *  `PropertyControlId` so the schema-driven renderer in Phase 2 can
+ *  dispatch on whichever id family it sees.
+ *
+ *  `tool.typeChips`
+ *      Type-row chip picker driven by `TOOL_REGISTRY[toolId].variants`.
+ *      ONE entry per tool with a variant flyout. Reads / writes
+ *      `preset[TOOL_REGISTRY[toolId].variantField]` (the only adapter
+ *      that genuinely needs `toolId` at read/write time — every other
+ *      adapter ignores it).
+ *
+ *  `tool.transparencyPercent`
+ *      0..100% inverse of `preset.strokeOpacity` (so "60% transparent"
+ *      reads as 60, not 0.4). The SELECTION-side `strokeOpacity` def
+ *      uses the same convention; the Tool panel always shows percent
+ *      directly without the helper, so this id keeps its own adapter.
+ *
+ *  `tool.fillTransparencyPercent`
+ *      0..100% inverse of `preset.fillOpacity`. Used by Highlight
+ *      (default 0.4 ↔ 60% transparent) where the visual language is
+ *      "transparency" — the larger the number, the see-throughier.
+ *
+ *  `tool.fillOpacityPercent`
+ *      0..100% DIRECT of `preset.fillOpacity`. Used by Shape (default
+ *      1.0 ↔ 100% opaque) where the imperative renderer used the
+ *      "Opacity" label. Distinct from `tool.fillTransparencyPercent`
+ *      so Phase 2 can preserve byte-equivalent DOM (label string +
+ *      number direction) per tool. Whether to unify the two surfaces
+ *      onto a single "Transparency" idiom is a UX decision, not a
+ *      refactor concern — out of scope for this plan.
+ *
+ *  `tool.freehandDone`
+ *      Click-action button that ends the active freehand drawing
+ *      session. No persisted value — the adapter's read/write are
+ *      a no-op pair (read returns null, write does nothing) so the
+ *      shape-invariant test treats it uniformly with the rest. */
+export type ToolPanelExtraControlId = "tool.typeChips" | "tool.transparencyPercent" | "tool.fillTransparencyPercent" | "tool.fillOpacityPercent" | "tool.freehandDone";
+/** Frozen tuple of every `ToolPanelExtraControlId`. Drives the
+ *  shape-invariant test that asserts every extra id has a matching
+ *  adapter. Keep in sync with the union above when adding new ids. */
+export declare const TOOL_PANEL_EXTRA_CONTROL_IDS: ReadonlyArray<ToolPanelExtraControlId>;
+/** A single Tool-side panel control. The renderer (Phase 2, Tier C)
+ *  consumes `panelControls` arrays to produce the per-tool side
+ *  panel. The id either reuses a `PropertyControlId` (when the
+ *  SELECTION registry can supply label / options / min / max
+ *  metadata) or names a Tool-only affordance via
+ *  `ToolPanelExtraControlId`.
+ *
+ *  Plain data — no closures over canvas state, no DOM globals at
+ *  module load. The optional `visibleWhen` predicate runs against
+ *  the CURRENT preset (NOT an SVGElement — this is the Tool side,
+ *  no element exists yet) so a control like Redact's Color row can
+ *  hide unless `preset.redactStyle === "solid"`. */
+export interface ToolPanelControlDef {
+    /** Section header. Renderer batches consecutive entries with the
+     *  same section into one `pp-section`. Order in the registry
+     *  controls visual order. */
+    section: ToolPanelSection;
+    /** Control id. Either a SELECTION-side id (`fillColor`,
+     *  `strokeWidth`, …) where the adapter routes the mutation onto
+     *  the matching `ToolOptions` field, or a Tool-only id
+     *  (`tool.typeChips`, `tool.transparencyPercent`, …) the renderer
+     *  resolves via its Tier C-local table. */
+    id: PropertyControlId | ToolPanelExtraControlId;
+    /** Optional gating predicate against the CURRENT preset. Returning
+     *  `false` tells the renderer to skip this control for the active
+     *  tool (e.g. "Redact Color row only when redactStyle === 'solid'").
+     *
+     *  Pure — no DOM access, no `Toolbar` access. Tier B-safe. */
+    visibleWhen?: (preset: ToolOptions) => boolean;
+}
+/** A single sub-shape pickable from a tool's variant flyout. Mirrors
+ *  the shape of `ToolVariant` in the legacy `toolbar-variants.ts`
+ *  (which becomes a thin re-export once Phase 4 deletes the file).
+ *  `svg` overrides `icon` when present — used for variants where
+ *  Material Symbols glyphs don't read clearly at button scale (rect
+ *  vs. rounded-rect, the three arrow-head variants, etc.). */
+export interface ToolRegistryVariant {
+    /** Value written into `ToolOptions[variantField]` when this variant
+     *  is selected. Also forms the suffix of the preset-storage key
+     *  (`shape.rect`, `arrow.both`, …). */
+    value: string;
+    /** Builtin icon id (registry key from
+     *  `@ingcreators/annot-core/editor/icons/registry`). Rendered via
+     *  the toolbar's `<annot-icon>` element when no `svg` is provided. */
+    icon: string;
+    /** Human-readable label for tooltips + a11y. */
+    label: string;
+    /** Optional inline SVG markup. When present, takes precedence over
+     *  `icon`. Should use `viewBox="0 0 24 24"`, omit explicit
+     *  width/height (so CSS sizes per-context), and use
+     *  `stroke="currentColor"` + `fill="none"` to match the outlined
+     *  Material-Symbols visual weight. */
+    svg?: string;
+}
+/** Tool semantic category. Drives toolbar / right-click menu grouping
+ *  + divider placement.
+ *
+ *    - `"annotation"` (default): tool emits an on-canvas SVG annotation
+ *      (Arrow / Shape / Highlight / Text / Draw / Counter / Redact).
+ *      Non-destructive — the underlying bitmap is untouched.
+ *    - `"image-op"`: tool destructively mutates the underlying
+ *      `ImageRecord` (Crop's `applyCrop` rewrites `originalDataUrl`).
+ *      Visually separated from annotation tools so the divider
+ *      signals "below this line, the tool changes the image itself".
+ *
+ *  Hosts may register additional categories in the future
+ *  (e.g. `"image-filter"` for non-annotation, non-bitmap-rewriting
+ *  tools); the toolbar treats anything other than `"annotation"` as
+ *  "trailing groups, separated by dividers in declaration order". */
+export type ToolCategory = "annotation" | "image-op";
+/** Full metadata for one tool. Plain data — no closures over canvas
+ *  state, no DOM globals at module load.
+ *
+ *  Tools without a variant flyout (Crop) omit `variants` /
+ *  `variantField` / `defaultVariant`; their preset key is just the
+ *  bare tool id.
+ *
+ *  Tools without an element-on-canvas (Crop again) omit
+ *  `variantKeyForElement` — there's no rubber-band style to harvest. */
+export interface ToolRegistryEntry {
+    /** Stable id, matches the registry's record key. Used as the
+     *  `data-tool` attribute on the toolbar button + as the prefix of
+     *  every preset-storage key for this tool. */
+    id: string;
+    /** Tooltip label on the toolbar button. */
+    label: string;
+    /** Material Symbols ligature for the toolbar button's default icon
+     *  (overridden at runtime by the active variant's icon for tools
+     *  with a flyout — see `Toolbar.#syncToolButtonIcon`). */
+    icon: string;
+    /** Semantic category. Drives toolbar group placement + canvas
+     *  right-click toolbox menu divider placement. Defaults to
+     *  `"annotation"` when omitted (matches the legacy behavior — every
+     *  pre-category tool was treated as an annotation tool). */
+    category?: ToolCategory;
+    /** Variant catalog. Empty / absent for tools without sub-variants. */
+    variants?: ReadonlyArray<ToolRegistryVariant>;
+    /** Which `ToolOptions` field discriminates the variant. Used by
+     *  the flyout to show the active chip and by the preset machinery
+     *  to migrate legacy tool-id-keyed entries to the new
+     *  `tool.variant` form. */
+    variantField?: keyof ToolOptions;
+    /** Default variant when no preset exists yet. MUST appear in
+     *  `variants`. */
+    defaultVariant?: string;
+    /** Which `ToolOptions` keys this tool's preset reads / writes.
+     *  Phase 2 makes this the single source of truth for the
+     *  camelCase ↔ snake_case (de)serializer; Phase 5 makes it the
+     *  source of truth for the rubber-band reader / writer. Today
+     *  it's data only — no consumer reads it yet. */
+    presetFields: ReadonlyArray<keyof ToolOptions>;
+    /** Element → preset-storage key extractor. Returns `null` for
+     *  elements this tool doesn't own (so a generic dispatch loop
+     *  can iterate `Object.entries(TOOL_REGISTRY)` and find the
+     *  first non-null match — replacing both `toolIdForElement` and
+     *  `elementKeyFromElement` in a single sweep, Phase 4 / 5).
+     *
+     *  Returns the FULL key (`"shape.rounded"`, `"arrow.both"`, …),
+     *  not just the variant suffix — so the caller doesn't need to
+     *  juggle the toolId prefix separately.
+     *
+     *  Implementations may assume jsdom-friendly Element APIs
+     *  (`tagName`, `getAttribute`, `hasAttribute`, `querySelector`).
+     *  No `document` / `window` access. */
+    variantKeyForElement?: (el: SVGElement) => string | null;
+    /** Tool-side panel control list. Drives the schema-driven renderer
+     *  in `tool-property-renderer-schema.ts` (Phase 2 of
+     *  `docs/plans/tool-property-renderer-schema.md`). Order is render
+     *  order; the renderer groups consecutive entries with the same
+     *  `section` into one `pp-section`.
+     *
+     *  Crop omits this field — its activation is a transient overlay,
+     *  not a per-tool side panel.
+     *
+     *  Today (Phase 1) it's data only — no consumer reads it yet.
+     *  Phase 2 adds the schema-driven renderer alongside the imperative
+     *  one; Phase 3 swaps the live callsite. */
+    panelControls?: ReadonlyArray<ToolPanelControlDef>;
+    /** Tool-specific style reader. Mutates `preset` in place with
+     *  values harvested from `el`'s attributes / children. The
+     *  generic universal-style reader (stroke / fill / stroke-width /
+     *  dasharray / opacity / linecap / linejoin) runs BEFORE this
+     *  hook; the hook only handles tool-specific branches the
+     *  universal reader can't capture (text font + variant on a
+     *  child `<text>`, arrow per-end state, marker bg primitive
+     *  reads, etc.).
+     *
+     *  Phase 5 of `docs/plans/toolbar-schema.md`: the imperative
+     *  `if (toolId === "text") { … } if (toolId === "arrow") { … }`
+     *  cascades in `Toolbar.syncPresetFromElement` collapse to a
+     *  single `TOOL_REGISTRY[toolId]?.extractStyleFromElement?.(el,
+     *  preset)` dispatch.
+     *
+     *  Tier B — implementations live in `tool-registry.ts` itself
+     *  and may only use jsdom-friendly Element APIs. */
+    extractStyleFromElement?: (el: SVGElement, preset: ToolOptions) => void;
+    /** Tool-specific style writer. Inverse of
+     *  `extractStyleFromElement`: writes the preset's style fields
+     *  onto `el` (or its tool-specific child elements — marker's
+     *  bg primitive, textbox's `<text>`, etc.).
+     *
+     *  Deliberately does NOT touch fields that define the element's
+     *  type / variant (shapeType, arrowHead, textVariant) — those
+     *  were already established by the variant-change path that
+     *  invoked the writer.
+     *
+     *  Phase 3 of `docs/plans/toolbar-apply-style-to-element.md`:
+     *  the imperative element-tag cascade in
+     *  `applyPresetStyleAttrs` (in
+     *  `packages/web/src/editor/toolbar-preset-helpers.ts`)
+     *  collapses to a single
+     *  `TOOL_REGISTRY[toolId]?.applyStyleToElement?.(el, preset)`
+     *  dispatch — symmetric with how Phase 5 of
+     *  `_done/toolbar-schema.md` collapsed the read side.
+     *
+     *  Tier B — implementations live in `tool-registry.ts` itself
+     *  and may only use jsdom-friendly Element APIs. The
+     *  `refreshArrowPath` regen for arrow groups is the one
+     *  exception: it lives in `core/editor/arrow-markers.ts`
+     *  (Tier B) so the registry can call it without crossing
+     *  package boundaries. */
+    applyStyleToElement?: (el: SVGElement, preset: ToolOptions) => void;
+    /** How the tool's variant flyout / variant badge / toolbox-menu
+     *  submenu present each variant chip:
+     *    - `"variant"` (default): icon glyph (Material Symbols
+     *      ligature) or inline SVG, matching the chip's
+     *      `icon` / `svg` fields.
+     *    - `"color"`: filled color swatch driven by the chip's
+     *      `chipColorForVariant` accessor (or, for the legacy
+     *      Highlight catalog, the variant's `value` itself when
+     *      it's a hex string).
+     *
+     *  Default is `"variant"` for tools without sub-variants
+     *  (Crop) and for tools whose variants are SHAPE-discriminated
+     *  (shape / arrow / text / freehand / marker / redact).
+     *  Highlight is the lone `"color"` today.
+     *
+     *  Phase 1 of `docs/plans/toolbar-highlight-flyout-kind.md`:
+     *  data only — no consumer reads it yet. Phases 2–4 lift the
+     *  three `if (toolId === "highlight")` callsites in
+     *  `toolbar.ts` + `toolbar-canvas-menu.ts` onto this
+     *  discriminator. */
+    flyoutKind?: "variant" | "color";
+    /** Chip color resolver — only meaningful when
+     *  `flyoutKind === "color"`. Returns the swatch fill color for
+     *  a given variant value. When undefined, callers fall back to
+     *  the variant value itself (the identity case — works for
+     *  Highlight today because the variant value IS the hex
+     *  string). Future tools whose variant value is an opaque id
+     *  (e.g. `"red"` instead of `"#ff0000"`) override to map
+     *  through their palette.
+     *
+     *  Tier B — pure `(string) => string`; no DOM access. */
+    chipColorForVariant?: (variantValue: string) => string;
+    /** Tooltip-label resolver — overrides the default
+     *  `${label} (${variantLabel})` formatter for tools whose
+     *  variant LABEL doesn't render usefully. Receives both the
+     *  raw variant VALUE (e.g. a hex string) and the variant's
+     *  `label` field (which may not match the user-facing name).
+     *
+     *  Highlight uses this to map ad-hoc hexes (saved in legacy
+     *  documents outside the 6-color palette) to an empty string
+     *  so the tooltip falls back to the bare tool name without
+     *  parens, instead of showing "Highlight (#123456)". For
+     *  palette colors it returns the palette label ("Yellow",
+     *  "Green", …) which matches the Selection-side
+     *  "Selected Highlight (Yellow)" formatter.
+     *
+     *  When undefined, the default `${variantLabel}` format
+     *  applies. Tier B — pure `(string, string) => string`; no
+     *  DOM access. */
+    tooltipLabelForVariant?: (variantValue: string, variantLabel: string) => string;
+    /** After the user picks a variant in the FLYOUT (color or
+     *  icon), fix up cross-field invariants on the preset that the
+     *  variantField alone can't capture. The variantField write is
+     *  applied first; this hook then mutates other fields the tool
+     *  needs to render correctly.
+     *
+     *  Today's only consumer: Highlight, which sets
+     *  `shapeType = "highlight"` so the underlying ShapeTool's
+     *  rendering dispatch sees the flag (the Highlight tool is
+     *  internally a ShapeTool with shapeType forced on).
+     *
+     *  Phase 5 of `docs/plans/toolbar-highlight-flyout-kind.md`:
+     *  removes the last `if (toolId === "highlight")` literal from
+     *  `Toolbar.#showColorFlyout`. Tier B — pure
+     *  `(preset, variantValue) => void`; no DOM access. */
+    ensurePresetForVariantChange?: (preset: ToolOptions, variantValue: string) => void;
+}
+/** After a variant switch, fix up the side-fields on `preset` so the
+ *  new variant's invariants hold. Today only `arrow` needs this:
+ *    - `none`: both ends must be "none".
+ *    - `end`:  begin must be "none", end must be non-"none" (default tri).
+ *    - `both`: both ends must be non-"none" (default tri).
+ *
+ *  Mutates `preset` in place; safe to call for tools without a
+ *  relevant invariant (it's a no-op).
+ *
+ *  Tier B — pure (no DOM, no `Toolbar` access). Relocated from
+ *  `packages/web/src/editor/toolbar-preset-helpers.ts` in Phase 5
+ *  of `docs/plans/toolbar-schema.md` so the registry's
+ *  `extractStyleFromElement` callbacks can call it without crossing
+ *  the Tier B → Tier C boundary. */
+export declare function normalizeVariantSideFields(toolId: string, newVariant: string, preset: ToolOptions): void;
+export declare const TOOL_REGISTRY: Readonly<Record<string, ToolRegistryEntry>>;
+/** All tool ids the toolbar exposes. Frozen tuple form for tests
+ *  that assert the registry covers exactly this set. */
+export declare const TOOL_REGISTRY_IDS: readonly ["arrow", "shape", "highlight", "text", "freehand", "marker", "redact", "crop"];
+export type ToolRegistryId = (typeof TOOL_REGISTRY_IDS)[number];

package/dist/editor/tool-style-reader.d.ts

@@ -0,0 +1,36 @@
+import { ToolOptions } from './tool-options.js';
+/** Pick the element whose attributes should be read for the
+ *  universal-style fields. For most elements that's `el` itself;
+ *  for freehand session groups (`<g data-type="freehand">`) it's
+ *  the LAST `<path>` child — the user's most recent stroke,
+ *  which is the natural rubber-band source. Returns `el` unchanged
+ *  when the freehand group has no path children yet (defensive). */
+export declare function resolveStyleReadSource(el: SVGElement): SVGElement;
+/**
+ * Read the universal style attributes off `el` (or its
+ * freehand-group inner stroke) and write them onto `preset`. Field
+ * coverage:
+ *
+ *   - `stroke`         → `strokeColor`
+ *   - `fill`           → `fillColor`
+ *   - `stroke-width`   → `strokeWidth` (only when finite + > 0)
+ *   - `data-dash-key` ?? `stroke-dasharray` → `strokeDasharray`
+ *     (`data-dash-key` wins when present, matching the priority the
+ *      legacy readers settled on)
+ *   - `fill-opacity`   → `fillOpacity` (only when finite)
+ *   - `opacity` ?? `stroke-opacity` → `strokeOpacity` (only when
+ *     finite). Lines / arrow `<g>`s carry transparency via
+ *     `opacity` so SVG-marker arrowheads fade with the stem;
+ *     other shapes use `stroke-opacity`. Reading both — preferring
+ *     `opacity` — captures whichever is set.
+ *   - `stroke-linecap` → `strokeLinecap` (whitelist butt/round/square)
+ *   - `stroke-linejoin` → `strokeLinejoin` (whitelist
+ *     miter/round/bevel)
+ *
+ * Tool-specific extras (text font, marker bg primitive, arrow
+ * per-end state, highlight's `fill → highlightColor` routing) are
+ * handled by the registry's `extractStyleFromElement` callbacks
+ * and intentionally NOT covered here — keep this helper toolId-
+ * agnostic.
+ */
+export declare function readUniversalStyleAttrs(el: SVGElement, preset: ToolOptions): void;

package/dist/editor/tool-style-writer.d.ts

@@ -0,0 +1,33 @@
+import { ToolOptions } from './tool-options.js';
+/**
+ * Write the universal style attributes from `preset` onto `el`.
+ * Field coverage mirrors `readUniversalStyleAttrs`:
+ *
+ *   - `strokeColor`        → `stroke`
+ *   - `strokeWidth`        → `stroke-width`
+ *   - `strokeDasharray`    → `stroke-dasharray` (numeric, via
+ *                            {@link computeDasharray}) AND
+ *                            `data-dash-key` (canonical key) so
+ *                            a subsequent read round-trips
+ *   - `fillColor`          → `fill`
+ *   - `fillOpacity`        → `fill-opacity`
+ *   - `strokeLinecap`      → `stroke-linecap`
+ *   - `strokeLinejoin`     → `stroke-linejoin`
+ *   - `strokeOpacity`      → `opacity` for `<line>` / arrow `<g>`
+ *                            (so SVG-marker arrowheads fade with
+ *                            the stem); `stroke-opacity` for
+ *                            everything else. Mirrors the read-
+ *                            side rule in `readUniversalStyleAttrs`.
+ *
+ * Tool-specific extras (text font + variant on a child `<text>`,
+ * marker's bg primitive walk, arrow's `refreshArrowPath` regen,
+ * highlight's `fillColor → fill` routing) are handled by the
+ * registry's `applyStyleToElement` callbacks and intentionally
+ * NOT covered here — keep this helper toolId-agnostic.
+ *
+ * Each branch is gated on the matching field being present so a
+ * partially-populated preset doesn't clobber attributes the user
+ * hasn't set. Mirrors the conditionals in the legacy
+ * `applyPresetStyleAttrs` generic path.
+ */
+export declare function writeUniversalStyleAttrs(el: SVGElement, preset: ToolOptions): void;

package/dist/editor/toolbar-icons.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Inline-SVG icon catalogues + highlight-color presets shared
+ * between the toolbar (in `@ingcreators/annot-web`) and core's
+ * `PropertyPanel`. Extracted out of `toolbar.ts` as part of
+ * Phase 5a of `docs/plans/_done/lit-migration.md` so the Toolbar
+ * class could relocate to web without dragging core's
+ * PropertyPanel into the cross-package import.
+ *
+ * These are pure data: ASCII strings + arrays + a tiny string
+ * lookup helper. No DOM access, no listeners, no globals.
+ */
+/** Inline SVG icons for the Shape tool's variants — rendered
+ *  as outline strokes so the chip glyphs read as "what shape
+ *  type" without implying any fill color.
+ *
+ *  Why hand-rolled: the Material Symbols `rectangle` /
+ *  `square` ligatures are visually IDENTICAL at 36px button
+ *  scale. `crop_square` (rounded outline) and `square` (sharp
+ *  outline) both render as a square outline in 36px buttons —
+ *  the difference (slight vs. no corner radius) is
+ *  imperceptible. Authoring inline SVG with EXAGGERATED corner
+ *  radius (rx/ry ≈ 1/3 of the side) makes the distinction
+ *  clear, matching what PowerPoint / Google Slides / Keynote /
+ *  Miro all do. */
+export declare const SHAPE_ICON_SVG: {
+    /** Sharp-cornered rectangle outline. Stroke weight tuned to
+     *  match the optical weight of adjacent Material-Symbols
+     *  outlined icons. */
+    readonly rect: "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linejoin=\"miter\" aria-hidden=\"true\"><rect x=\"4\" y=\"4\" width=\"16\" height=\"16\"/></svg>";
+    /** Rounded rectangle with rx=5 on a 16-wide square (≈ 31% —
+     *  above the 20% threshold where humans reliably perceive
+     *  corner rounding at icon scale). */
+    readonly rounded: "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" aria-hidden=\"true\"><rect x=\"4\" y=\"4\" width=\"16\" height=\"16\" rx=\"5\"/></svg>";
+    /** Ellipse / circle outline. Drawn as an <ellipse> with rx=ry
+     *  so it's perfectly circular; using <ellipse> rather than
+     *  <circle> keeps a single element type if future variants
+     *  (e.g. wide ellipse) need different rx/ry. Stroke-width
+     *  matches rect / rounded so the three chips look optically
+     *  equal. */
+    readonly ellipse: "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" aria-hidden=\"true\"><ellipse cx=\"12\" cy=\"12\" rx=\"8\" ry=\"8\"/></svg>";
+};
+/** Inline SVG icons for the Arrow tool's head variants.
+ *  Material Symbols has no icon that accurately depicts a
+ *  single line with arrowheads on both ends (`sync_alt` shows
+ *  TWO parallel lines in opposite directions, which is not the
+ *  same thing). Hand-rolling the three glyphs as a unified set
+ *  — same line length, same stroke weight, only the arrowheads
+ *  change — makes the "this is the same line with different
+ *  ends" narrative visually obvious. */
+export declare const ARROW_ICON_SVG: {
+    /** Plain horizontal line, no arrowheads. */
+    readonly none: "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\"><path d=\"M4 12 H20\"/></svg>";
+    /** Single arrowhead at the right end ("end" variant). */
+    readonly end: "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\"><path d=\"M4 12 H20\"/><path d=\"M16 8 L20 12 L16 16\"/></svg>";
+    /** Arrowheads at BOTH ends ("both" variant). */
+    readonly both: "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\"><path d=\"M4 12 H20\"/><path d=\"M16 8 L20 12 L16 16\"/><path d=\"M8 8 L4 12 L8 16\"/></svg>";
+};
+/** Inline SVG icons for the Counter (marker) shape variants —
+ *  each glyph shows the container shape filled with
+ *  `currentColor` and a "1" cut out to represent the numeric
+ *  label. The cutout uses fill-rule="evenodd" so the "1" reads
+ *  as the panel background showing through, automatically
+ *  adapting to light / dark themes without hard-coded colors. */
+export declare const COUNTER_ICON_SVG: {
+    readonly circle: "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" aria-hidden=\"true\"><ellipse cx=\"12\" cy=\"12\" rx=\"8\" ry=\"8\"/><text x=\"12\" y=\"17\" text-anchor=\"middle\" font-size=\"14\" font-weight=\"800\" font-family=\"system-ui, sans-serif\" fill=\"currentColor\" stroke=\"none\">1</text></svg>";
+    readonly rect: "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linejoin=\"miter\" aria-hidden=\"true\"><rect x=\"4\" y=\"4\" width=\"16\" height=\"16\"/><text x=\"12\" y=\"17\" text-anchor=\"middle\" font-size=\"14\" font-weight=\"800\" font-family=\"system-ui, sans-serif\" fill=\"currentColor\" stroke=\"none\">1</text></svg>";
+    readonly rounded: "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" aria-hidden=\"true\"><rect x=\"4\" y=\"4\" width=\"16\" height=\"16\" rx=\"5\"/><text x=\"12\" y=\"17\" text-anchor=\"middle\" font-size=\"14\" font-weight=\"800\" font-family=\"system-ui, sans-serif\" fill=\"currentColor\" stroke=\"none\">1</text></svg>";
+};
+/** Preset highlight colors — matches common PDF / PowerPoint
+ *  highlighter pen sets. The user can pick any of these from
+ *  the Highlight tool's color-swatch flyout; the chosen color
+ *  is persisted via the preset system so the next click on the
+ *  Highlight button uses it again. */
+export declare const HIGHLIGHT_COLORS: ReadonlyArray<{
+    value: string;
+    label: string;
+}>;
+/** Map a highlight fill hex (case-insensitive) to its palette
+ *  label. Used by the right-panel selection title ("Selected
+ *  Highlight (Yellow)") and by the Type-picker swatch tooltips.
+ *  Falls back to the hex string itself for colors outside the
+ *  preset palette (e.g. legacy documents with custom
+ *  highlightColor values). */
+export declare function highlightColorLabel(fill: string | null | undefined): string;

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

@@ -0,0 +1,127 @@
+/**
+ * transform-utils — composite transform management for annotation
+ * elements (rotation + flip + translate).
+ *
+ * State is persisted as `data-*` attributes on the element so the SVG
+ * is the single source of truth (no parallel JS map). The visual
+ * `transform` attribute is recomputed from those attrs whenever any
+ * piece of state changes.
+ *
+ * Stored state:
+ *   data-rot     ← rotation in degrees (CW positive). Default 0.
+ *   data-flip-h  ← "1" if horizontally flipped. Default unset/0.
+ *   data-flip-v  ← "1" if vertically flipped. Default unset/0.
+ *   data-tx      ← translate x (only used for path/g — for rect/
+ *                  ellipse/etc. position lives in their own attrs).
+ *   data-ty      ← translate y (path/g only).
+ *
+ * Rotation/flip pivot is the element's LOCAL bbox center (computed via
+ * getBBox() which ignores the element's own transform). Re-computed on
+ * every update so the pivot follows resizes naturally.
+ *
+ * Composite math (right-to-left in SVG):
+ *   M = T(tx, ty) * T(cx, cy) * R(rot) * S(sx, sy) * T(-cx, -cy)
+ *
+ * For elements with no rotation and no flip, the function emits a
+ * plain `translate(tx, ty)` (or no transform at all when tx=ty=0) so
+ * existing serialization stays byte-identical for unrotated content.
+ */
+declare function isLineLike(el: Element): boolean;
+/** Return a line/arrow's endpoint + optional control-point coords in
+ *  world space, applying any lingering `data-rot` / `data-flip-*` /
+ *  `data-tx,ty` WITHOUT mutating the element. Used by read-only
+ *  consumers (e.g. PPTX export) and by the mutating `bakeLineTransform`
+ *  below. The control point is included so curved arrows survive the
+ *  transform intact. */
+export declare function getEffectiveLineEndpoints(el: SVGElement): {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    cx: number | null;
+    cy: number | null;
+};
+/** Collapse any rotation/flip/translate state on a line/arrow into
+ *  its endpoints (and control point, for curved arrows), clearing the
+ *  `transform` attribute + data-* state. Idempotent. Call before any
+ *  gesture on a line/arrow to normalize legacy saved content that
+ *  still carries a transform attribute. */
+export declare function bakeLineTransform(el: SVGElement): void;
+/** Translate a line/arrow's endpoints (and arrow control point, if
+ *  curved) by `(dx, dy)` in world space. Bakes any pending
+ *  rotation/flip/translate state into endpoints first via
+ *  `bakeLineTransform` so the result reflects the visual position
+ *  the user sees on screen, not a stale endpoint pair the matrix
+ *  was offsetting at render time.
+ *
+ *  Used by the destructive-crop pipeline (`EditorShell.applyCrop`
+ *  via `bakeAnnotationsTranslate`) to shift line/arrow annotations
+ *  into the cropped image's new origin. The non-line dispatcher
+ *  in `bake-translate.ts:bakeTranslate` covers everything else.
+ *
+ *  No-op for `(0, 0)` and for non-line inputs (the caller is
+ *  expected to dispatch line vs. non-line, but the guard keeps
+ *  the helper safe to call defensively from a generic walker). */
+export declare function bakeLineTranslate(el: SVGElement, dx: number, dy: number): void;
+/** Rotate a line's endpoints (and control point, if curved) by `deg`
+ *  around the midpoint of the two endpoints. */
+export declare function rotateLineEndpointsBy(el: SVGElement, deg: number): void;
+/** Mirror a line's endpoints (and control point) across its midpoint
+ *  on the given axis. */
+export declare function flipLineEndpoints(el: SVGElement, axis: "h" | "v"): void;
+export { isLineLike };
+export interface TransformState {
+    tx: number;
+    ty: number;
+    rotation: number;
+    flipH: boolean;
+    flipV: boolean;
+}
+/** Elements whose position lives in their own geometry attrs (not in
+ *  a translate transform). For these, `tx`/`ty` are always 0; movement
+ *  shifts those geometry attrs directly and the transform only carries
+ *  rotation/flip. */
+export declare function usesGeometryPosition(el: Element): boolean;
+/** Read the current transform state from `data-tx` / `data-ty` /
+ *  `data-rot` / `data-flip-{h,v}`. Geometry-positioned elements
+ *  (`<rect>` / `<ellipse>` / etc.) use their geometry attributes for
+ *  position so `tx` / `ty` stay zero. */
+export declare function readTransformState(el: SVGElement): TransformState;
+/** Recompute the element's `transform` attribute from its current
+ *  data-* state and local geometry. Idempotent — call after any state
+ *  change. */
+export declare function applyTransformState(el: SVGElement, state?: TransformState): void;
+/** Persist a (possibly partial) state update and re-apply the
+ *  composite transform. Callout tails get rebuilt automatically since
+ *  rotation/flip pivots can change as the bbox changes. */
+export declare function writeTransformState(el: SVGElement, patch: Partial<TransformState>): void;
+/** Apply a translation delta. For geometry-positioned elements, the
+ *  caller updates x/y/cx/cy/etc. directly and then calls this with
+ *  dx=dy=0 — the helper still recomputes the transform so the rotation
+ *  pivot tracks the new bbox center. */
+export declare function nudgeTranslate(el: SVGElement, dx: number, dy: number): void;
+/** Toggle a flip axis. For line/arrow elements the flip is baked
+ *  into endpoint coordinates (no transform attribute); for everything
+ *  else the flip is persisted as a data-flip-h/v attribute.
+ *
+ *  The flip acts in SCREEN space: a Flip V on a rect that's currently
+ *  rotated 30° mirrors the visibly-rotated shape across a horizontal
+ *  screen axis through its visible center — it does NOT mirror the
+ *  rect in its pre-rotation local frame (which would visually look
+ *  like the shape just jumped to a new rotation, not like a flip).
+ *
+ *  Composing a screen-space reflection S_screen after the existing
+ *  transform T * R * S * T⁻¹ reduces via the identity S * R(θ) =
+ *  R(−θ) * S to the same transform shape with: rotation negated AND
+ *  the target flip-axis toggled. So the fix is one sign flip on
+ *  rotation + one boolean toggle. */
+export declare function toggleFlip(el: SVGElement, axis: "h" | "v"): void;
+/** Set rotation (degrees, CW positive). Normalized to [-180, 180).
+ *  For line/arrow elements rotation is baked into endpoints: the
+ *  argument is interpreted as the target absolute rotation relative
+ *  to the element's current orientation (i.e. the caller sees a
+ *  stateless rotation — always rotates FROM the current endpoints).
+ *  Because baked lines always report rotation=0 via readTransformState,
+ *  the typical caller pattern `setRotation(el, readRotation() + delta)`
+ *  still works and applies `delta` degrees. */
+export declare function setRotation(el: SVGElement, deg: number): void;