@triiiceratops/plugin-annotation-editor 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Flood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/AnnotationManager.svelte.d.ts

@@ -0,0 +1,260 @@
+import type { AnnotationEditorConfig, AnnotationPersistenceOp, DrawingTool } from './types';
+import { AnnotationStore } from './AnnotationStore.svelte';
+import type { ViewerState } from 'triiiceratops';
+/** Every tool the plugin knows how to draw, in default button order. */
+export declare const ALL_TOOLS: DrawingTool[];
+/**
+ * Resolve the effective tool set and default tool from config so the manager
+ * and controller share one source of truth (F8). An empty/absent `tools` list
+ * means "all tools"; `defaultTool` is honored only when it's within `tools`,
+ * otherwise the first available tool wins.
+ */
+export declare function resolveTools(config: {
+    tools?: DrawingTool[];
+    defaultTool?: DrawingTool;
+}): {
+    tools: DrawingTool[];
+    defaultTool: DrawingTool;
+};
+/**
+ * Manages the Annotorious instance and annotation CRUD operations.
+ * Instantiated within the controller component.
+ */
+export declare class AnnotationManager {
+    private static readonly ACTIVE_EDIT_ID_EVENT;
+    private static readonly DEFAULT_POINT_FILL;
+    private static readonly DEFAULT_POINT_STROKE;
+    private static readonly DEFAULT_POINT_STROKE_WIDTH;
+    private static readonly DEFAULT_DRAWING_STYLE;
+    private config;
+    private store;
+    private readonly ownsStore;
+    private readonly viewerState;
+    private annotorious;
+    private osdViewer;
+    private openHandler;
+    private canvasClickHandler;
+    private createOSDAnnotator;
+    private W3CImageFormat;
+    private OSD;
+    private editingPointOrigin;
+    private get currentManifestId();
+    private get currentCanvasId();
+    private activeEditingAnnotationId;
+    private lastHandledCanvasKey;
+    private suppressedEchoIds;
+    private isDrawingEnabled;
+    private activeTool;
+    private selectedAnnotation;
+    private readonly resolvedTools;
+    readonly resolvedDefaultTool: DrawingTool;
+    onSelectionChange?: (annotation: any | null) => void;
+    onAnnotationCreated?: (annotation: any) => void;
+    onAnnotationHydrationChange?: (isHydrating: boolean) => void;
+    onActiveEditingAnnotationChange?: (annotationId: string | null) => void;
+    constructor(config: AnnotationEditorConfig, store?: AnnotationStore, viewerState?: ViewerState);
+    init(viewer: any, canvasId: string | null): void;
+    private initAnnotorious;
+    /**
+     * Create a true IIIF `PointSelector` annotation at the exact click point
+     * (F17). The click is converted click → viewport → image coords → canvas
+     * coords and rounded once to integer canvas pixels (D2) — no synthetic
+     * fragment rectangle, no zoom-dependent geometry, no `point-` id heuristic.
+     * The annotation goes through the same store create path as drawn shapes
+     * (prepareDraft, stamping, display sync); it is already canvas-space, so the
+     * image→canvas transform is skipped. It is then opened for body editing.
+     */
+    private handlePointClick;
+    setEditing(enabled: boolean): void;
+    private updateDrawingMode;
+    /**
+     * A point annotation is one whose target carries a `PointSelector` (F17).
+     * Recurses one level into `selector.item` for wrapped selectors, matching
+     * `annotationAdapter.ts`. No `point-` id heuristic — geometry, not id, is
+     * authoritative.
+     */
+    private isPointAnnotation;
+    private getPointCoordinates;
+    private toPointSelectorTarget;
+    /**
+     * Convert a cached (canvas-space) annotation into the image-space shape
+     * Annotorious edits. Non-points scale straight to image space. A point has
+     * no Annotorious tool, so it becomes a small fragment rectangle centred on
+     * the point and sized in **screen pixels at selection time** (§3.2): the
+     * marker keeps a constant visual size regardless of image resolution or
+     * zoom. The exact point is recorded separately (`editingPointOrigin`) so the
+     * reverse conversion never re-derives it from the rect centre.
+     */
+    private toAnnotoriousTarget;
+    /**
+     * Reverse of {@link toAnnotoriousTarget} for a point being edited: turn the
+     * image-space fragment rect Annotorious holds back into a canvas-space
+     * `PointSelector`. If the rect's centre still maps to the recorded origin
+     * (integer canvas px, D2), the point wasn't dragged and the origin is emitted
+     * verbatim — a bit-identical round-trip. If it moved, the new rect centre is
+     * used (§3.2).
+     */
+    private pointFromEditingRect;
+    private parseFragmentRect;
+    /**
+     * The point editing rectangle's side length in **image units**, derived from
+     * the configured marker diameter (screen px) and the current
+     * image-units-per-screen-pixel. Falls back to treating the diameter as
+     * canvas units (scaled to image space) when the viewport can't be measured
+     * yet — e.g. before the viewer's first render.
+     */
+    private pointEditRectImageSize;
+    /**
+     * Image units spanned by one screen pixel at the current zoom, measured the
+     * way the old point-authoring code did: convert two 1px-apart screen points
+     * to image coordinates and take the delta. Returns null when the viewport
+     * isn't available.
+     */
+    private imageUnitsPerScreenPixel;
+    /**
+     * Annotorious `style` callback: points get the configured marker colours,
+     * every other shape gets the host's drawing style (F9). A point is
+     * identified by having an editing origin recorded for its id.
+     */
+    private styleForAnnotation;
+    private getCurrentCanvasImageDimensions;
+    setTool(tool: DrawingTool): void;
+    get availableTools(): DrawingTool[];
+    /**
+     * The store's current unhandled persistence error for the panel's default
+     * error line, or `null` when there's nothing to show (F20).
+     */
+    get persistenceError(): {
+        op: AnnotationPersistenceOp;
+        annotationId?: string;
+    } | null;
+    /** Dismiss the panel's persistence error line. */
+    dismissPersistenceError(): void;
+    /** Whether an undo is available (reactive; drives the panel button — F6). */
+    get canUndo(): boolean;
+    /** Whether a redo is available (reactive; drives the panel button — F6). */
+    get canRedo(): boolean;
+    /**
+     * Reverse the most recent persisted operation through the store's op stack,
+     * replaying its inverse against the adapter so storage and display stay in
+     * agreement (F6).
+     */
+    undo(): Promise<void>;
+    /** Re-apply the most recently undone operation (F6). */
+    redo(): Promise<void>;
+    private setupEvents;
+    private setActiveEditingAnnotationId;
+    /**
+     * Reset the manager's Annotorious-facing selection fields. Shared by the two
+     * teardown paths: `clearSelectionState()` (also notifies the host, leaves
+     * Annotorious untouched) and `clearAnnotoriousEditingAnnotation()` (also
+     * clears Annotorious's annotation set).
+     */
+    private resetSelectionFields;
+    /**
+     * Tear down the current selection and tell the host it's gone, without
+     * touching Annotorious's own annotation set. Used on the create/delete/
+     * rollback paths where Annotorious's shape is managed separately.
+     */
+    private clearSelectionState;
+    private clearAnnotoriousEditingAnnotation;
+    /**
+     * Clear all annotations from Annotorious, marking each so the resulting
+     * (async) `deleteAnnotation` echo is consumed by handleDeleteAnnotation and
+     * never mistaken for a user-originated deletion (F27). Only ids actually
+     * present are marked, so no stale marks accrue.
+     */
+    private clearAnnotationsSuppressed;
+    handleCanvasChange(manifestId: string | null, canvasId: string | null): Promise<void>;
+    private loadAnnotations;
+    /**
+     * Handles Annotorious's (async) `createAnnotation` lifecycle event. Persists
+     * exactly what the host's prepareDraft/prepareAnnotation produced — not the
+     * raw event payload — so draft enrichment survives create (F2).
+     */
+    private handleCreateAnnotation;
+    /**
+     * Handles Annotorious's (async) `updateAnnotation` lifecycle event. Echoes
+     * we triggered ourselves (e.g. pushing edited bodies back into Annotorious)
+     * are consumed here so they don't double-persist (F3).
+     */
+    private handleUpdateAnnotation;
+    /**
+     * Handles Annotorious's (async) `deleteAnnotation` lifecycle event. Echoes
+     * from our own `clearAnnotations()` teardown are marked and consumed here so
+     * they never reach the adapter. A genuine Annotorious-originated deletion of
+     * a persisted annotation syncs the adapter, cache, and selection state (F27).
+     */
+    private handleDeleteAnnotation;
+    /**
+     * Persist an annotation that arrived in **image space** (Annotorious event
+     * payloads, geometry edits). Transforms to canvas space, forces the target
+     * source, applies beforeSave, then persists.
+     */
+    saveAnnotation(annotation: any): Promise<boolean>;
+    /**
+     * Convert an image-space annotation from Annotorious into canvas space for
+     * the cache/panel/store. An actively-edited point takes the lossless
+     * origin-aware path (§3.2); everything else scales normally, with legacy
+     * fragment-centre read-compat via `toPointSelectorTarget` (D3).
+     */
+    private annotationToCanvasSpace;
+    /**
+     * Persist a freshly created annotation that is already in **canvas space**
+     * (the output of prepareAnnotation). Skips the image→canvas re-transform;
+     * beforeSave still runs last. Returns whether the write succeeded.
+     */
+    private persistCreate;
+    /**
+     * Run a store mutation whose resulting (asynchronous) Annotorious lifecycle
+     * echo for `annotationId` must not be re-persisted.
+     *
+     * NOTE: Annotorious v3 dispatches lifecycle events via `setTimeout(…, 1)`
+     * (verified in @annotorious/core@3.7.19), so a synchronous boolean guard as
+     * originally planned would already be reset by the time the echo fires. We
+     * mark the id and let the echo consume the mark instead. A body-change
+     * update emits exactly one echo, so one mark == one consumed echo.
+     */
+    private withSuppressedEcho;
+    /** Record one more expected self-triggered echo for this id. */
+    private markSuppressedEcho;
+    /**
+     * Consume one expected echo for this id. Returns true (and decrements the
+     * count, deleting the entry at zero) while echoes remain outstanding, so two
+     * concurrent echoes — e.g. a body-save update echo and a teardown delete echo
+     * for the same id — are each matched and neither leaks (F3/F27).
+     */
+    private consumeSuppressedEcho;
+    /**
+     * Always overwrite `target.source` with the current canvas id. Within this
+     * plugin the target is by definition the canvas the user is annotating, so
+     * overwriting is safe regardless of what the Annotorious W3C serializer
+     * stamped at init time (see F1). All other target fields are preserved.
+     */
+    private forceTargetSource;
+    private prepareAnnotation;
+    private applyBeforeSave;
+    private getRuntimeContext;
+    private notifyExtensionSelectionChange;
+    private hydrateAnnotation;
+    deleteAnnotation(annotationId: string): Promise<boolean>;
+    updateAnnotationBodies(annotationId: string, bodies: unknown[] | unknown): Promise<boolean>;
+    /**
+     * React to the store swapping a freshly-created annotation onto its
+     * server-assigned id (F5). If that annotation is the one currently open for
+     * editing, re-open it under the canonical id: this re-adds it to Annotorious,
+     * reselects it, and re-emits the active-edit-id signal with the new id.
+     */
+    private handleIdReconciled;
+    /**
+     * Reconcile the open Annotorious editing session with an undo/redo replay
+     * (F6). Only the annotation currently open is affected: if the replay left
+     * it in storage, re-open it so its geometry and body reflect the restored
+     * state; if the replay removed it (e.g. undoing the create of the annotation
+     * being edited), tear the editing session down.
+     */
+    private handleReplay;
+    selectAnnotationById(annotationId: string): Promise<void>;
+    cancelSelection(): void;
+    destroy(): void;
+}

package/dist/AnnotationStore.svelte.d.ts

@@ -0,0 +1,211 @@
+import type { AnnotationEditorConfig, AnnotationPersistenceOp } from './types';
+import type { W3CAnnotation } from './adapters/types';
+/**
+ * The per-viewer display-sync surface the store writes to (ADR 0001, amended;
+ * ADR 0007). Structurally satisfied by `ViewerState`, injected via
+ * {@link AnnotationStore.setDisplayState} so the store never imports the
+ * page-shared manifest cache — annotations are scoped to the owning viewer.
+ */
+export interface AnnotationDisplayState {
+    setUserAnnotations(manifestId: string, canvasId: string, annotations: W3CAnnotation[]): void;
+    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
+ * 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).
+ */
+export declare class AnnotationStore {
+    private static readonly W3C_CONTEXT;
+    private static readonly DEFAULT_MOTIVATION;
+    private adapter;
+    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.
+     */
+    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.
+     */
+    onReplay?: (affectedId: string, annotation: W3CAnnotation | null) => void;
+    private manifestId;
+    private canvasId;
+    private displayState;
+    private persistedAnnotations;
+    private hydrationState;
+    private saveQueue;
+    private loadSequence;
+    private injectedCanvases;
+    private static readonly UNDO_DEPTH;
+    private undoStack;
+    private redoStack;
+    private replaying;
+    private lastCreateCanonical;
+    private _canUndo;
+    private _canRedo;
+    private _panelError;
+    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.
+     */
+    setDisplayState(displayState: AnnotationDisplayState | null): void;
+    get currentManifestId(): string | null;
+    get currentCanvasId(): string | null;
+    /** Both a manifest and a canvas are known — persistence can run. */
+    get ready(): boolean;
+    /** The adapter can lazily hydrate skeleton bodies. */
+    get hydrateSupported(): boolean;
+    /**
+     * The most recent persistence failure the host didn't handle, for the
+     * panel's default error line. `null` when there's nothing to show or a host
+     * `onPersistenceError` handler took ownership of the failure (F20).
+     */
+    get panelError(): {
+        op: AnnotationPersistenceOp;
+        annotationId?: string;
+    } | null;
+    /** Dismiss the default error line (user clicked the ✕). */
+    dismissError(): void;
+    /** An undo is available (reactive; drives the panel button). */
+    get canUndo(): boolean;
+    /** A redo is available (reactive; drives the panel button). */
+    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.
+     */
+    setCanvas(manifestId: string | null, canvasId: string | null): void;
+    get(id: string): W3CAnnotation | null;
+    has(id: string): boolean;
+    isSkeleton(id: string): boolean;
+    /**
+     * Load the current canvas's annotations from the adapter into the cache.
+     * A newer load (e.g. a canvas change) started while we awaited discards this
+     * stale result so it can't clobber the current canvas (F14).
+     */
+    load(): Promise<W3CAnnotation[]>;
+    /**
+     * Single chokepoint for adapter writes. Decides create-vs-update from the
+     * in-memory cache (no per-save adapter.load round-trip — F4), serializes
+     * writes per annotation id (F4), and updates the cache only after the
+     * adapter call resolves.
+     *
+     * 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
+     * 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,
+     * `false` when the adapter rejected (the failure has been reported).
+     */
+    persist(annotation: W3CAnnotation): Promise<boolean>;
+    /**
+     * Delete an annotation through the adapter and drop it from the cache.
+     * Cache/display are only advanced after the adapter resolves, so a rejected
+     * delete leaves the entry (and its overlay) intact — the "restore the entry"
+     * rollback (F20). Returns `true` on success, `false` when the adapter
+     * rejected (the failure has been reported).
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * 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
+     * uses this to bail if the annotation is no longer being edited).
+     */
+    hydrate(id: string, shouldApply?: () => boolean): Promise<W3CAnnotation | null>;
+    /**
+     * Resolve the full annotation for editing: return the cached copy when it is
+     * already full, hydrate it when the cache holds a skeleton, or reload the
+     * canvas when the id isn't cached at all.
+     */
+    resolve(id: string): Promise<W3CAnnotation | null>;
+    /**
+     * Reverse the most recent persisted operation by replaying its inverse
+     * through the normal write paths (F6): a `create` is deleted, an `update`
+     * restores the previous cached copy, a `delete` re-creates the removed copy.
+     * The reversed operation moves to the redo stack. A failed replay (the
+     * adapter rejected — the error surface fires) leaves the operation on the
+     * undo stack so it is never lost.
+     */
+    undo(): Promise<void>;
+    /**
+     * Re-apply the most recently undone operation through the normal write paths
+     * (F6). The re-applied operation moves back to the undo stack. A failed
+     * replay leaves the operation on the redo stack so it is never lost.
+     */
+    redo(): Promise<void>;
+    destroy(): void;
+    /**
+     * Record a just-committed forward operation for undo (F6). A normal user
+     * operation becomes undoable and invalidates any redo path; while replaying
+     * an undo/redo this is suppressed (the replay pushes onto the opposite stack
+     * itself).
+     */
+    private recordForward;
+    private pushUndo;
+    private pushRedo;
+    /** Return a failed-replay op to the undo stack so it is never lost (F6). */
+    private restoreUndo;
+    /** Return a failed-replay op to the redo stack so it is never lost (F6). */
+    private restoreRedo;
+    private pushCapped;
+    private clearHistory;
+    private refreshUndoRedoFlags;
+    /**
+     * Surface a failed persistence operation (F20). A host `onPersistenceError`
+     * handler takes full ownership of the failure (it gets a `retry` handle);
+     * without one, the store logs and records a dismissible panel error so the
+     * failure is never invisible. The cache/display rollback has already
+     * happened at the call sites (writes only commit on success).
+     */
+    private reportError;
+    /**
+     * 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).
+     */
+    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.
+     */
+    private stampForCreate;
+    /** Refresh `modified` on an updated annotation (F18). */
+    private stampForUpdate;
+    /**
+     * Push the current canvas's cached annotations into the owning viewer's
+     * display state so the read-only overlay reflects storage. The plugin owns
+     * this — adapters are pure storage (F10). Records the canvas key so
+     * `destroy()` can clear it.
+     */
+    private syncDisplay;
+    private cachePersistedAnnotations;
+    /**
+     * Strip plugin-internal bookkeeping markers so they never reach an adapter,
+     * the cache, or the panel.
+     */
+    private stripInternalMarkers;
+}

package/dist/adapters/LocalStorageAdapter.d.ts

@@ -0,0 +1,37 @@
+import type { W3CAnnotation, AdapterLoadResult, AnnotationStorageAdapter } from './types';
+/**
+ * LocalStorage-based annotation adapter — the reference minimal adapter.
+ *
+ * It is pure storage: `localStorage` reads and writes, nothing more. Display
+ * sync (to the owning viewer's state), caching, id reconciliation, and error
+ * handling are all owned by the plugin's `AnnotationStore`, so a custom adapter
+ * only needs to implement these few storage methods (F10). This is the shape
+ * every adapter should aim for.
+ *
+ * ── LocalStorage namespace (FROZEN) ────────────────────────────────────────
+ * 1.0 writes under a new, stable, versioned, package-qualified key:
+ *
+ *     @triiiceratops/plugin-annotation-editor:v1:<manifestId>:<canvasId>
+ *
+ * This key is FROZEN — it is the stable 1.0 contract and must not change without
+ * a `:v2:` bump. The prerelease adapter used a different, unversioned key
+ * (`triiiceratops:annotations:<manifestId>:<canvasId>`). Per SPEC, RC-era data is
+ * neither read, migrated, deleted, nor overwritten: this adapter never touches
+ * the old namespace, so prerelease keys are left byte-identical and untouched
+ * (they are disposable RC data). This is local/single-browser storage — not a
+ * production multi-user adapter.
+ */
+export declare class LocalStorageAdapter implements AnnotationStorageAdapter {
+    readonly id = "localStorage";
+    readonly name = "Local Storage";
+    /** The frozen 1.0 namespace prefix (see the class doc). */
+    private static readonly KEY_PREFIX;
+    private storageKey;
+    load(manifestId: string, canvasId: string): Promise<AdapterLoadResult[]>;
+    hydrate(manifestId: string, canvasId: string, annotationId: string): Promise<AdapterLoadResult | null>;
+    create(manifestId: string, canvasId: string, annotation: W3CAnnotation): Promise<void>;
+    update(manifestId: string, canvasId: string, annotation: W3CAnnotation): Promise<void>;
+    delete(manifestId: string, canvasId: string, annotationId: string): Promise<void>;
+    private loadFromStorage;
+    private saveToStorage;
+}

package/dist/adapters/index.d.ts

@@ -0,0 +1,2 @@
+export type { W3CAnnotation, AnnotationStorageAdapter } from './types';
+export { LocalStorageAdapter } from './LocalStorageAdapter';

package/dist/adapters/types.d.ts

@@ -0,0 +1,78 @@
+import type { W3CAnnotationBody, AnnotationStorageAdapter } from '../types';
+/**
+ * IIIF/W3C media-fragment selector (`xywh=…`, `t=…`). The value carries the
+ * fragment expression.
+ */
+export interface FragmentSelector {
+    type: 'FragmentSelector';
+    conformsTo?: string;
+    value: string;
+    [key: string]: unknown;
+}
+/** IIIF `PointSelector` — a single canvas-space point (integer px per D2). */
+export interface PointSelector {
+    type: 'PointSelector';
+    x: number;
+    y: number;
+    [key: string]: unknown;
+}
+/** W3C `SvgSelector` — an SVG shape (polygon, path, …) as its `value`. */
+export interface SvgSelector {
+    type: 'SvgSelector';
+    value: string;
+    [key: string]: unknown;
+}
+/**
+ * Escape hatch for selector types the plugin doesn't model explicitly (e.g. a
+ * `RangeSelector`, or a host-specific selector). Keeps the union open so a
+ * round-trip never narrows away an unknown selector.
+ */
+export interface UnknownSelector {
+    type: string;
+    [key: string]: unknown;
+}
+/** Open selector union — never narrow away unknown selector types. */
+export type W3CSelector = FragmentSelector | PointSelector | SvgSelector | UnknownSelector;
+/** W3C Web Annotation target (a `SpecificResource` pointing at a canvas). */
+export interface W3CTarget {
+    type?: string;
+    source: string;
+    selector?: W3CSelector | W3CSelector[];
+    [key: string]: unknown;
+}
+/**
+ * W3C Web Annotation structure. Generic over the body shape so a host with a
+ * structured/custom body gets compiler help end-to-end; `TBody` defaults to the
+ * built-in {@link W3CAnnotationBody}. The index signature is an intentional
+ * escape hatch so host-specific fields survive a load → edit → save round-trip
+ * instead of being dropped by the type.
+ */
+export interface W3CAnnotation<TBody = W3CAnnotationBody> {
+    '@context'?: string | string[];
+    id: string;
+    type: 'Annotation';
+    body?: TBody | TBody[];
+    target: W3CTarget | W3CTarget[];
+    creator?: {
+        id?: string;
+        name?: string;
+        [key: string]: unknown;
+    };
+    created?: string;
+    modified?: string;
+    motivation?: string | string[];
+    [key: string]: unknown;
+}
+/**
+ * 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):
+ * `__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}.
+ */
+export type AdapterLoadResult<TBody = W3CAnnotationBody> = W3CAnnotation<TBody> & {
+    __fullBodyLoaded?: boolean;
+    __bodyPreview?: string | null;
+};
+export type { AnnotationStorageAdapter };

package/dist/catalog.d.ts

@@ -0,0 +1,9 @@
+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.
+ */
+export declare const catalog: LocaleCatalog;

package/dist/components/viewerControls.d.ts

@@ -0,0 +1,43 @@
+import { getCanvasId } from 'triiiceratops/image-export';
+export type ChoiceGroup = {
+    canvasId: string;
+    choices: any[];
+    selectedChoiceId: string | undefined;
+    side: 'left' | 'right';
+};
+export type VisibleCanvasEntry = {
+    canvasId: string;
+    canvas: any;
+};
+export type PagedCanvasGroup = {
+    startIndex: number;
+    endIndex: number;
+    entries: VisibleCanvasEntry[];
+};
+export type CanvasNavDirection = 'previous' | 'next';
+export type CanvasNavIcon = 'left' | 'right' | 'up' | 'down';
+export type CanvasNavLayout = {
+    leftButton: CanvasNavDirection;
+    rightButton: CanvasNavDirection;
+    leftIcon: CanvasNavIcon;
+    rightIcon: CanvasNavIcon;
+};
+export declare function shouldUseAbbreviatedChoiceLabels(viewingMode: ViewingMode, visibleChoiceGroups: ChoiceGroup[]): boolean;
+export declare function getCanvasNavLayout(viewingDirection: ViewingDirection): CanvasNavLayout;
+type ViewingMode = 'individuals' | 'paged' | 'continuous';
+type ViewingDirection = 'left-to-right' | 'right-to-left' | 'top-to-bottom' | 'bottom-to-top';
+type VisibleChoiceGroupArgs = {
+    canvases: any[];
+    currentCanvasId: string | null;
+    currentCanvasIndex: number;
+    viewingMode: ViewingMode;
+    pagedOffset: number;
+    viewingDirection: ViewingDirection;
+    getSelectedChoice: (canvasId: string) => string | undefined;
+};
+export { getCanvasId };
+export declare function getCanvasChoices(canvas: any): any;
+export declare function getCanvasBehaviors(canvas: any): string[];
+export declare function getPagedCanvasGroups(canvases: any[], pagedOffset: number): PagedCanvasGroup[];
+export declare function getVisibleCanvasEntries({ canvases, currentCanvasId, currentCanvasIndex, viewingMode, pagedOffset, }: Omit<VisibleChoiceGroupArgs, 'viewingDirection' | 'getSelectedChoice'>): VisibleCanvasEntry[];
+export declare function getVisibleChoiceGroups({ canvases, currentCanvasId, currentCanvasIndex, viewingMode, pagedOffset, viewingDirection, getSelectedChoice, }: VisibleChoiceGroupArgs): ChoiceGroup[];