@triiiceratops/plugin-annotation-editor 1.0.0-rc.7 → 1.0.0

package/README.md

@@ -0,0 +1,332 @@
+# @triiiceratops/plugin-annotation-editor
+
+Annotation editing for the [Triiiceratops](https://triiiceratops.org/)
+IIIF viewer.
+
+Core renders and selects the annotations a manifest publishes; it writes none.
+This plugin adds the writing half: a **drawing layer** over the image with
+rectangle, ellipse, polygon, point and whole-canvas tools, a panel with a body
+editor and persistence-aware undo/redo, and an `AnnotationStorageAdapter` seam so
+annotations persist wherever your institution keeps them. Every tool is operable
+from the keyboard, for creation as well as editing.
+
+The drawing layer is built on core's own published primitives — an overlay layer
+for its DOM, `canvasToScreen`/`screenToCanvas` for projection, `subscribeFrame`
+for reprojection — so no third party's object model sits between the editor and
+the viewer. Annotations are persisted as W3C Web Annotations targeting canvas
+coordinates: `FragmentSelector` (`xywh=`) for a rectangle, `SvgSelector` with a
+`<polygon>` for an ellipse or a polygon, `PointSelector` for a point, and no
+selector at all for a whole-canvas note.
+
+## Install
+
+```bash
+pnpm add @triiiceratops/plugin-annotation-editor
+```
+
+`triiiceratops`, `@triiiceratops/plugin-sdk` and `svelte` are peers. The plugin
+declares a core floor (`coreRange: '>=1.0.0-rc.36'`) — the first core that ships
+overlay-layer registration — and refuses to activate against anything older,
+loudly, on core's plugin-error channel rather than mounting a button that does
+nothing.
+
+## Registering it
+
+### As a module (any bundler)
+
+```ts
+import {
+    AnnotationEditorPlugin,
+    createAnnotationEditorPlugin,
+    LocalStorageAdapter,
+} from '@triiiceratops/plugin-annotation-editor';
+```
+
+`AnnotationEditorPlugin` is the preconfigured plugin: every tool, rectangle
+armed by default, and the built-in `LocalStorageAdapter`. Use
+`createAnnotationEditorPlugin(config)` for anything else. Hand either to the
+viewer the way you hand it any other plugin — the `plugins` prop in Svelte,
+React and Vue, or the `.plugins` **property** (never an attribute) on the
+`<triiiceratops-viewer>` custom element:
+
+```ts
+const annotations = createAnnotationEditorPlugin({
+    adapter: new LocalStorageAdapter(),
+    user: { id: 'user-123', name: 'Jane Doe' },
+});
+
+document.querySelector('triiiceratops-viewer').plugins = [annotations];
+```
+
+### As a script tag (IIFE)
+
+```html
+<script src="/assets/triiiceratops-element.iife.js"></script>
+<script src="/assets/plugin-annotation-editor/iife.js"></script>
+
+<triiiceratops-viewer id="viewer"></triiiceratops-viewer>
+<script>
+    // Loading the script only registers a factory; activation is per-viewer.
+    document.getElementById('viewer').plugins = [
+        window.Triiiceratops.plugins.get(
+            '@triiiceratops/plugin-annotation-editor',
+        ),
+    ];
+</script>
+```
+
+Either script order works — the registry is bootstrapped order-independently —
+and this bundle carries its own Svelte runtime, so it shares nothing private
+with core. The IIFE path uses the built-in `LocalStorageAdapter`; a custom
+adapter needs the module entry.
+
+## Drawing
+
+Drawing is **modal**: the reader arms a tool from the panel, and for as long as
+it is armed the drawing layer takes pointer events across the whole image, so a
+drag draws instead of panning. One tool, one gesture — nothing ever has to guess
+whether a press was a click or a drag.
+
+| Tool         | Gesture                                        | Persisted target          |
+| ------------ | ---------------------------------------------- | ------------------------- |
+| Rectangle    | drag a bounding box                            | `FragmentSelector`        |
+| Ellipse      | drag a bounding box                            | `SvgSelector` `<polygon>` |
+| Polygon      | click per vertex; Enter or double-click closes | `SvgSelector` `<polygon>` |
+| Point        | single click                                   | `PointSelector`           |
+| Whole canvas | activate the tool                              | no selector               |
+
+A region smaller than a few canvas pixels in either dimension is discarded
+rather than committed, so hand jitter does not litter an annotation set with
+two-pixel shapes.
+
+An **ellipse is a creation affordance only**. It persists as a 64-point polygon
+inscribed in the dragged box, and edits afterwards as the polygon it is —
+nothing records that it was once an ellipse. This is deliberate; see
+[ADR 0022](../../docs/adr/0022-an-ellipse-persists-as-a-polygon.md).
+
+What still works while a tool is armed:
+
+- **Wheel zoom**, unchanged — place a vertex precisely without disarming.
+- **Keyboard zoom and arrow-key panning**, unchanged.
+- **Hold Space to pan by dragging.** The layer drops its own pointer events for
+  as long as Space is held and the viewer's ordinary panning takes over
+  underneath; a Space-pan never commits a shape.
+
+Pointer-drag panning is the one thing arming suppresses, and Space is its escape
+hatch.
+
+A tool is armed only while the panel that explains it is on screen. There are
+two exits and both cancel rather than commit: Escape, and **closing the
+panel** — which gives the image straight back.
+
+## Keyboard
+
+Creation from the keyboard is **place-then-shape**: arming a tool drops a
+default-sized shape at the centre of the current view, which the ordinary
+editing verbs then move and size. Creation and editing share one set of verbs.
+
+| Key             | Effect                                                                                   |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| Arrows          | nudge the focused handle, vertex or whole shape by 1 canvas pixel                        |
+| Shift + arrows  | the larger step, 10 canvas pixels                                                        |
+| Tab / Shift+Tab | cycle the shape's handles and vertices                                                   |
+| Enter           | commit; for a polygon in progress, close the outline                                     |
+| Escape          | cancel the keyboard shape or edit in progress, else discard any pointer draft and disarm |
+| Delete          | remove the selected annotation                                                           |
+| `i`             | insert a vertex after the focused polygon vertex                                         |
+| `x`             | remove the focused polygon vertex                                                        |
+
+Nudges are in **canvas** pixels, not screen pixels, so one press moves a vertex
+the same distance across the folio at fit zoom as at 8×.
+
+Every persisted annotation stays a focusable, labelled element while the editor
+is open — those targets are core's, and the drawing layer draws only the one
+annotation currently under edit, its handles and the in-progress preview.
+
+## Storage: the adapter seam
+
+An adapter is **pure storage**. It knows nothing about how a shape is displayed;
+the plugin's store owns display sync, caching, id reconciliation, creator
+stamping, hydration and error handling around it.
+
+```ts
+import type {
+    AnnotationStorageAdapter,
+    W3CAnnotation,
+} from '@triiiceratops/plugin-annotation-editor';
+
+const adapter: AnnotationStorageAdapter = {
+    id: 'my-server',
+    name: 'Institutional annotation server',
+
+    async load(manifestId, canvasId) {
+        const res = await fetch(url(manifestId, canvasId));
+        return res.json();
+    },
+
+    // Return the canonical annotation (or just its id) when your server mints
+    // its own IRI — the plugin reconciles the id everywhere. `void` keeps the
+    // client-generated one.
+    async create(manifestId, canvasId, annotation) {
+        const res = await fetch(url(manifestId, canvasId), {
+            method: 'POST',
+            body: JSON.stringify(annotation),
+        });
+        return (await res.json()) as W3CAnnotation;
+    },
+
+    async update(manifestId, canvasId, annotation) {
+        /* … */
+    },
+    async delete(manifestId, canvasId, annotationId) {
+        /* … */
+    },
+};
+```
+
+`load` may return **skeleton** entries — annotations whose bodies have not been
+fetched — marked `__fullBodyLoaded: false`; implement the optional `hydrate` and
+the plugin fetches a full body when one is opened. Optional `destroy` is called
+on teardown.
+
+A failed write **rolls back** the plugin's optimistic changes and then calls
+`config.onPersistenceError` with the operation, the annotation id and a `retry()`
+that re-runs the exact failed call. Omit the handler and the plugin logs and
+shows a dismissible error line in the panel, so a failure is never invisible.
+
+The conformance suite the built-in adapter passes is exported for yours to run
+against:
+
+```ts
+import { runAdapterContractTests } from '@triiiceratops/plugin-annotation-editor/testing';
+
+runAdapterContractTests(() => new MyAdapter(), {
+    supportsIdReconciliation: true,
+    supportsHydrate: true,
+});
+```
+
+`LocalStorageAdapter` is the built-in default and persists under a frozen
+`@triiiceratops/plugin-annotation-editor:v1` namespace, keyed by manifest and
+canvas.
+
+## Replacing the body editor
+
+The built-in body editor edits W3C bodies — a value, a format, a language and a
+purpose from the W3C vocabulary — and leaves structured bodies it does not
+understand untouched across a save. To edit your own metadata model in place,
+pass `bodyEditor`: either a Svelte `component` taking an `api` prop, or a
+framework-neutral `render(container, api)` returning its own cleanup.
+
+```ts
+createAnnotationEditorPlugin({
+    bodyEditor: {
+        render(container, api) {
+            const input = document.createElement('textarea');
+            input.value = String(api.bodies[0]?.value ?? '');
+            input.onchange = () =>
+                api.save([{ type: 'TextualBody', value: input.value }]);
+            container.append(input);
+            return () => input.remove();
+        },
+    },
+});
+```
+
+`api` carries the full `annotation` in canvas space, its `bodies` normalised to
+an array, the runtime `context` (manifest, canvas, user, host context),
+`isHydrating`, and `save` / `cancel` / `requestDelete`. The plugin owns the
+geometry and the persistence; the body editor owns only the bodies.
+
+`extension` is the other seam, for host applications rather than for a different
+body shape: gate creation (`canCreate`, `getCreateDisabledReason`), prefill a
+draft (`prepareDraft`), transform on the way out (`beforeSave`), or observe
+selection (`onSelectionChange`).
+
+## Configuration
+
+| Option                                                                | Default          | Notes                                                                                     |
+| --------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
+| `adapter`                                                             | —                | Storage. `LocalStorageAdapter` on the preconfigured plugin.                               |
+| `user`                                                                | —                | `{ id, name? }`, stamped onto new annotations as creator.                                 |
+| `tools`                                                               | all five         | Which tools the panel offers.                                                             |
+| `defaultTool`                                                         | first in `tools` | Honoured only if it is within `tools`.                                                    |
+| `defaultMotivation`                                                   | `'commenting'`   | Never overwrites a motivation the host already set.                                       |
+| `target`                                                              | `'panel'`        | Where the plugin chrome renders.                                                          |
+| `ui`                                                                  | —                | `showModeToggle`, `startInCreateMode`, `showUndoRedo`, `purposes`, `allowMultipleBodies`. |
+| `bodyEditor`, `extension`, `onPersistenceError`                       | —                | See above.                                                                                |
+| `prepareAnnotation`, `canCreateAnnotation`, `getCreateDisabledReason` | —                | Flat equivalents of the matching `extension` hooks.                                       |
+
+## Styling
+
+The drawing layer is DOM and SVG, so CSS styles it — theming follows the
+viewer's `--tri-` custom properties like everything else. There is no styling
+**option**; set these on the viewer or any ancestor.
+
+| Property                             | Default                                         |
+| ------------------------------------ | ----------------------------------------------- |
+| `--tri-annotation-draw-stroke`       | `var(--tri-color-primary)`                      |
+| `--tri-annotation-draw-stroke-width` | `2px`                                           |
+| `--tri-annotation-draw-fill`         | 20% `--tri-color-primary`, mixed to transparent |
+| `--tri-annotation-draw-cursor`       | `crosshair`                                     |
+| `--tri-annotation-edit-move-cursor`  | `move`                                          |
+| `--tri-annotation-handle-size`       | `10px`                                          |
+| `--tri-annotation-handle-fill`       | `var(--tri-color-primary)`                      |
+| `--tri-annotation-handle-stroke`     | `var(--tri-color-base-100)`                     |
+| `--tri-annotation-point-fill`        | `var(--tri-annotation-color)`                   |
+| `--tri-annotation-point-stroke`      | `var(--tri-annotation-color)`                   |
+
+Point markers are the exception: they are core's, not this layer's. Their size is
+`--tri-annotation-point-size` and their colour `--tri-annotation-color`, the same
+two tokens core's read-only overlay draws and measures a marker from, so a point
+looks the same open for editing as it does at rest and one declaration restyles
+both. This plugin declares neither of its own, deliberately — a second setting
+could only disagree with the first, and a point would change under the reader the
+moment it was opened. `--tri-annotation-point-fill` and
+`--tri-annotation-point-stroke` still override the colour for this layer alone,
+which is the only way to make the two disagree on purpose.
+
+## Upgrading from `1.0.0-rc.7`
+
+`rc.7` was the last published version, and its editing surface was
+[Annotorious](https://annotorious.dev/). Annotorious and OpenSeadragon are gone;
+the drawing layer is first-party. Four configuration changes, all visible at the
+call site:
+
+- **`drawingStyle` is removed.** It was typed with an Annotorious type and only
+  ever read inside the deleted Annotorious binding. Style the drawing layer with
+  the CSS custom properties above instead.
+- **`requiredCapabilities` is gone.** Compatibility is now the `coreRange` floor
+  alone — overlay layers are not optional in core, so there was nothing to
+  require.
+- **`user` keeps its `{ id, name }` shape** but is a locally declared type
+  rather than an Annotorious one. No call-site change; replace an `import type
+{ User } from '@annotorious/openseadragon'` with `AnnotationEditorUser` from
+  this package.
+- **`pointStyle` is removed from this plugin's config.** It only ever styled the
+  Annotorious marker, which is why it goes the way `drawingStyle` does. Nothing
+  replaces it in configuration: a marker is theming now, and both core's
+  read-only marker and this editor read the same two tokens —
+  `--tri-annotation-point-size` and `--tri-annotation-color` — which is what
+  makes a point the same size and colour selected and not.
+
+Nothing about persisted data changed. The v1 LocalStorage namespace and the W3C
+annotation format are the same, so annotations written by `rc.7` load and edit
+without migration — an ellipse simply was not drawable before.
+
+Everything that was never the Annotorious binding is carried forward unchanged:
+the store, the adapter seam and `LocalStorageAdapter`, display sync, stamping, id
+reconciliation, hydration, persistence-aware undo/redo, the body editor and its
+replacement hook, the extension hooks, the i18n catalog, and the adapter
+conformance suite on the `/testing` subpath.
+
+## Design records
+
+- [ADR 0020](../../docs/adr/0020-modal-drawing-swallows-pointer-events-in-the-dom.md)
+  — why arming a tool takes pointer events in the DOM instead of claiming input
+  at the gesture arbiter.
+- [ADR 0021](../../docs/adr/0021-the-editing-surface-is-first-party.md) — why the
+  editing surface is first-party, and why the editor draws one annotation while
+  core draws the set.
+- [ADR 0022](../../docs/adr/0022-an-ellipse-persists-as-a-polygon.md) — why an
+  ellipse is stored as a polygon.

package/dist/AnnotationStore.svelte.d.ts

@@ -11,17 +11,14 @@ export interface AnnotationDisplayState {
     clearUserAnnotations(manifestId: string, canvasId: string): void;
 }
 /**
- * Plugin-internal persistence core. Owns everything the manager used to do "to
- * storage": the annotation cache, per-annotation hydration state, create-vs-update
+ * Plugin-internal persistence core. Owns everything "to storage": the
+ * annotation cache, per-annotation hydration state, create-vs-update
  * resolution, the per-id save queue, the load-race token, and the raw adapter.
  *
- * `AnnotationManager` talks only to this store for persistence and keeps the
- * Annotorious/OpenSeadragon mechanics (selection, tools, coordinate transforms).
- * The store deals exclusively in **canvas-space** W3C annotations — transforms
- * live at the manager/store boundary.
- *
- * This class is a refactor of code previously inlined in `AnnotationManager`
- * (issues 01–04); behavior is intentionally unchanged (issue 05).
+ * The drawing layer talks only to this store for persistence and keeps the
+ * geometry (selection, tools, coordinate transforms). The store deals
+ * exclusively in **canvas-space** W3C annotations — transforms live at the
+ * drawing-layer/store boundary.
  */
 export declare class AnnotationStore {
     private static readonly W3C_CONTEXT;
@@ -30,16 +27,17 @@ export declare class AnnotationStore {
     private config;
     /**
      * Notified when a `create` reconciles an annotation onto a server-assigned
-     * id (F5), so the manager can re-open it in Annotorious under the canonical
-     * id and re-emit the active-edit-id signal. Set by the manager; the loader
-     * leaves it unset.
+     * id (F5), so the drawing layer can follow its in-flight create onto the
+     * canonical id and open the body editor on the id the annotation was
+     * actually stored under. Set by the drawing layer; the loader leaves it
+     * unset.
      */
     onReconcileId?: (oldId: string, canonical: W3CAnnotation) => void;
     /**
-     * Notified after an undo/redo replay so the manager can reconcile the open
-     * Annotorious editing session with the new storage state (F6): `annotation`
-     * is the annotation now in the cache under `affectedId`, or `null` when the
-     * replay removed it. Set by the manager; the loader leaves it unset.
+     * Notified after an undo/redo replay so the drawing layer can reconcile the
+     * open editing session with the new storage state (F6): `annotation` is the
+     * annotation now in the cache under `affectedId`, or `null` when the replay
+     * removed it. Set by the drawing layer; the loader leaves it unset.
      */
     onReplay?: (affectedId: string, annotation: W3CAnnotation | null) => void;
     private manifestId;
@@ -61,8 +59,9 @@ export declare class AnnotationStore {
     constructor(config: AnnotationEditorConfig);
     /**
      * Point display sync at the owning viewer's display state (ADR 0001,
-     * amended). Called by the loader (and the manager) when the viewer is known.
-     * Idempotent — re-attaching the same viewer is harmless.
+     * amended). Called by the mount seam when the viewer is known, and by the
+     * loader for a store it drives on its own. Idempotent — re-attaching the
+     * same viewer is harmless.
      */
     setDisplayState(displayState: AnnotationDisplayState | null): void;
     get currentManifestId(): string | null;
@@ -88,8 +87,8 @@ export declare class AnnotationStore {
     get canRedo(): boolean;
     /**
      * Point the store at a canvas and drop the previous canvas's cache. Does
-     * not load — the manager drives load timing (and, from issue 06, display
-     * sync) around this call.
+     * not load — the caller drives load timing and display sync around this
+     * call.
      */
     setCanvas(manifestId: string | null, canvasId: string | null): void;
     get(id: string): W3CAnnotation | null;
@@ -109,12 +108,12 @@ export declare class AnnotationStore {
      *
      * On create the store stamps a complete W3C/IIIF annotation (F18) and, if the
      * adapter returns a canonical annotation or id, reconciles the cache/display
-     * onto the server-assigned id and notifies the manager (F5). On update it
+     * onto the server-assigned id and notifies its owner (F5). On update it
      * refreshes `modified` and adopts a server-normalized copy when returned.
      *
      * Cache and display are only advanced *after* the adapter resolves, so a
      * rejected write leaves both at their pre-operation state — the rollback the
-     * manager relies on to re-signal selection (F20). Returns `true` on success,
+     * drawing layer relies on to re-signal selection (F20). Returns `true` on success,
      * `false` when the adapter rejected (the failure has been reported).
      */
     persist(annotation: W3CAnnotation): Promise<boolean>;
@@ -130,7 +129,7 @@ export declare class AnnotationStore {
      * Fetch a skeleton annotation's full body from the adapter and cache it.
      * Returns the full annotation, or null when there is nothing to do (no
      * hydrate support), the fetch came back empty, the canvas changed while
-     * awaiting (F14), or `shouldApply` vetoes committing the result (the manager
+     * awaiting (F14), or `shouldApply` vetoes committing the result (the caller
      * uses this to bail if the annotation is no longer being edited).
      */
     hydrate(id: string, shouldApply?: () => boolean): Promise<W3CAnnotation | null>;
@@ -183,14 +182,14 @@ export declare class AnnotationStore {
     /**
      * Commit a created annotation to the cache under its canonical id. When the
      * adapter returns a server-assigned annotation or id string, the cache key is
-     * swapped from the local id to the canonical one, and the manager is notified
-     * so it can re-open the annotation under the new id (F5).
+     * swapped from the local id to the canonical one, and `onReconcileId` fires
+     * so the owner can follow the annotation onto the new id (F5).
      */
     private reconcileCreate;
     /**
      * Stamp a complete, valid W3C/IIIF annotation before create without
      * clobbering host-provided values (F18). `extension.beforeSave` has already
-     * run (in the manager) and therefore still wins — stamping only fills gaps.
+     * run by the caller and therefore still wins — stamping only fills gaps.
      */
     private stampForCreate;
     /** Refresh `modified` on an updated annotation (F18). */

package/dist/adapters/types.d.ts

@@ -66,7 +66,7 @@ export interface W3CAnnotation<TBody = W3CAnnotationBody> {
 /**
  * Shape an adapter's `load()`/`hydrate()` may return. Beyond a stored
  * annotation it may carry the internal skeleton markers the plugin reads exactly
- * once and strips before anything enters the cache or Annotorious (ticket 03):
+ * once and strips before anything enters the cache:
  * `__fullBodyLoaded: false` signals a skeleton whose body must be fetched via
  * `hydrate()`. These markers are NOT part of the stored annotation contract —
  * they never round-trip — so they live here rather than on {@link W3CAnnotation}.

package/dist/catalog.d.ts

@@ -1,9 +1,8 @@
 import type { LocaleCatalog } from '@triiiceratops/plugin-sdk';
 /**
  * The plugin's package-owned localization catalog (CONTEXT.md **Active locale**).
- * These strings previously lived in core's `messages/en.json` / `messages/de.json`;
- * migrating the plugin out of core moves them here so the catalog ships with (and
- * evolves with) the plugin, and core's catalogs carry no plugin keys. `en` is the
- * required fallback; a missing key resolves to `en` and then to the key itself.
+ * The catalog ships with (and evolves with) the plugin, so core's catalogs carry
+ * no plugin keys. `en` is the required fallback; a missing key resolves to `en`
+ * and then to the key itself.
  */
 export declare const catalog: LocaleCatalog;

package/dist/contextKey.d.ts

@@ -3,8 +3,8 @@
  *
  * `VIEWER_STATE_KEY` carries the owning viewer's state (the live `ViewerState`,
  * or the reactive mirror `view.mount` builds so the plugin's own Svelte runtime
- * tracks cross-realm state changes) to the controller. It replaces core's
- * internal `VIEWER_STATE_KEY` (the plugin no longer imports core internals); the
- * controller reads it with `getContext(VIEWER_STATE_KEY)` exactly as before.
+ * tracks cross-realm state changes) to the controller, which reads it with
+ * `getContext(VIEWER_STATE_KEY)`. Package-local so the plugin never imports
+ * core internals.
  */
 export declare const VIEWER_STATE_KEY: unique symbol;

package/dist/drawingLayer.d.ts

@@ -0,0 +1,22 @@
+import type { PluginContext } from '@triiiceratops/plugin-sdk';
+import type { AnnotationStore } from './AnnotationStore.svelte';
+import type { DrawingSession } from './drawingSession.svelte';
+import type { TFn } from './i18n.svelte';
+import type { MirroredViewerState } from './viewerMirror.svelte';
+/** Marks the container so a spec can find it. */
+export declare const DRAWING_LAYER_CLASS = "tri-annotation-drawing-layer";
+/** The layer's name within this plugin's id namespace. */
+export declare const DRAWING_LAYER_NAME = "drawing";
+/**
+ * Register the drawing layer with the owning viewer. Returns the registry's
+ * idempotent dispose, which is a no-op if the registration was refused.
+ *
+ * One layer, not several: cross-plugin ordering cannot be coordinated, so
+ * internal stacking is `z-index` on this container's own children.
+ */
+export declare function registerDrawingLayer(context: PluginContext, surface: {
+    session: DrawingSession;
+    store: AnnotationStore;
+    viewerState: MirroredViewerState;
+    t: TFn;
+}): () => void;

package/dist/drawingSession.svelte.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The arming state the panel and the drawing layer share.
+ *
+ * The two live in different component trees — the panel is mounted into core's
+ * plugin surface, the layer into the overlay-layer container — so the tool the
+ * reader armed reaches the layer through this object rather than through props.
+ * Reactive so the layer's `pointer-events` follow the panel's mode toggle
+ * without either side polling.
+ */
+import type { W3CAnnotation } from './adapters/types';
+import type { DrawingTool } from './types';
+export declare class DrawingSession {
+    /**
+     * The armed tool, or `null` while the reader is in edit mode — arming is
+     * modal, and this is what the layer's whole-surface `pointer-events: auto`
+     * is gated on.
+     */
+    armedTool: DrawingTool | null;
+    /**
+     * The persisted annotation open for editing, or `null`. The panel decides
+     * it — a tap on a shape reaches core's edit bus, which the controller owns
+     * — and the drawing layer draws its shape and its handles, which is what
+     * makes core's own rendering of that one annotation stand down.
+     */
+    editingAnnotationId: string | null;
+    /**
+     * Set by the controller when an edit was opened by TAPPING the shape on the
+     * image, and cleared by the drawing layer once focus is on it.
+     *
+     * A tap leaves focus wherever it was — core's own shape is removed the
+     * instant the editor takes the rendering over, so the document is left
+     * focused on nothing. Every keyboard verb the open shape has (nudge,
+     * commit, delete, the vertex keys) is bound on the shape, so until focus
+     * reaches it a reader who taps a shape has no keyboard at all.
+     *
+     * Only the tap. Selecting the annotation from the panel's LIST opens the
+     * same edit, and pulling focus out of the list onto the image would take
+     * the reader off the control they are actually working in.
+     */
+    focusOnEdit: boolean;
+    /**
+     * Set by the controller so a committed shape opens its body editor. Not
+     * reactive state: it is wiring, replaced only when the controller mounts.
+     */
+    onCreated: ((annotation: W3CAnnotation) => void) | null;
+    /**
+     * The host's `extension.prepareDraft` / `prepareAnnotation` hook, applied
+     * to a NEW annotation before its first save. Set by the controller, which
+     * is where the config and the runtime context the hook is handed live;
+     * called by the drawing layer, which is where a shape becomes an
+     * annotation.
+     */
+    prepareDraft: ((annotation: W3CAnnotation) => W3CAnnotation) | null;
+    /**
+     * The host's `extension.beforeSave` hook, applied to every annotation on
+     * its way to the store — a create, a reshape and a body save alike, so a
+     * host that rewrites annotations sees all three.
+     */
+    beforeSave: ((annotation: W3CAnnotation) => Promise<W3CAnnotation>) | null;
+    /**
+     * Create a whole-canvas annotation on the store's current canvas. Set by
+     * the drawing layer, called by the controller: the whole-canvas tool has no
+     * gesture, so the panel activating it IS the create, but the create itself
+     * belongs beside every other one so id reconciliation and the handoff to
+     * the body editor are not written twice.
+     */
+    createWholeCanvasAnnotation: (() => void) | null;
+    /**
+     * Place a tool's default shape at the centre of the current view, ready for
+     * the ordinary editing verbs to move and size. Set by the drawing layer,
+     * called by the controller when a tool is activated from the KEYBOARD.
+     *
+     * Creation is place-then-shape: a keyboard user has no cursor to describe a
+     * region with, so the tool supplies a starting geometry rather than the
+     * layer growing a second, keyboard-only creation path.
+     */
+    placeDefaultShape: ((tool: DrawingTool) => void) | null;
+    /**
+     * Delete the annotation open for editing — the Delete key's counterpart to
+     * the panel's own delete button, and the same confirmation with it. Set by
+     * the controller, called by the drawing layer.
+     */
+    requestDelete: (() => void) | null;
+    /**
+     * Escape's way back out of an open edit — the only way out there is, since
+     * the body editor offers no cancel of its own. Set by the controller for the
+     * same reason as {@link requestDisarm}: the open edit is DERIVED from the
+     * panel's selection, so the layer clearing `editingAnnotationId` itself
+     * would be overwritten by the next change to that selection.
+     */
+    requestCancelEdit: (() => void) | null;
+    /**
+     * Escape's way back out of the armed state. The layer cannot simply clear
+     * `armedTool`: arming is DERIVED in the controller from create mode and the
+     * selected tool, so a write here would be overwritten by the next change to
+     * either, and the panel would meanwhile still show the tool lit. Disarming
+     * has to happen at the state the panel renders from, which is the
+     * controller's.
+     */
+    requestDisarm: (() => void) | null;
+}