Standalone decorator

decorator/.gitignore

@@ -0,0 +1,6 @@
+*.log
+.DS_Store
+node_modules
+dist
+types
+coverage

decorator/README.md

@@ -0,0 +1,131 @@
+# @readium/decorator
+
+Renders visual annotations over text ranges on a page — highlights, underlines, strikethroughs, and more.
+
+## Installation
+
+```ts
+import { DirectCommsChannel, Decorator, DecorationController, DecorationStyleType } from "@readium/decorator";
+```
+
+## Usage
+
+```ts
+// 1. Create the comms channel
+const channel = new DirectCommsChannel();
+
+// 2. Mount the Decorator module on the page
+const decorator = new Decorator();
+decorator.mount(window, channel.frame);
+
+// 3. Create the controller
+const ctrl = new DecorationController(channel.host);
+
+// 4. Check style support before applying (TextColor requires the CSS Highlight API)
+if (ctrl.supportsDecorationStyle(DecorationStyleType.TextColor)) {
+    // safe to use
+}
+
+// 5. Apply decorations — call again with a new array to update, empty array to clear
+ctrl.applyDecorations([
+    {
+        id: "tts-0",
+        locator: /* Locator for the text range to decorate */,
+        style: { type: DecorationStyleType.Highlight, tint: "#FFFF00" },
+    }
+], "tts");
+
+// 6. Cleanup
+decorator.unmount(window, channel.frame);
+ctrl.destroy();
+channel.frame.destroy();
+```
+
+## API
+
+### `DecorationController`
+
+```ts
+class DecorationController {
+    constructor(host: DirectCommsHost, config?: DecorationControllerConfig)
+
+    // Returns true if the given style ID can be rendered.
+    // Returns false for TextColor when the CSS Highlight API is unavailable.
+    // Returns true for any ID registered in config.decorationTemplates.
+    supportsDecorationStyle(styleTypeId: string): boolean
+
+    // Replaces all decorations for a group. Diffs against previous state.
+    applyDecorations(decorations: Decoration[], group: string): void
+
+    // Registers an observer for a group.
+    // Activation is enabled for the group only when the observer declares onDecorationActivated.
+    // Hover tracking is enabled when the observer declares onDecorationPointerEnter or onDecorationPointerLeave.
+    registerDecorationObserver(group: string, observer: DecorationObserver): void
+    unregisterDecorationObserver(observer: DecorationObserver): void
+
+    destroy(): void
+}
+
+interface DecorationControllerConfig {
+    // Named style templates. Register a template here and reference it by ID in decoration styles.
+    decorationTemplates?: Record<string, HTMLDecorationTemplate>;
+}
+```
+
+### `DecorationObserver`
+
+```ts
+interface DecorationObserver {
+    // Called when a decoration is tapped/clicked. Return true to consume the event.
+    // Activation is enabled for the group only when this method is declared.
+    onDecorationActivated?(event: OnDecorationActivatedEvent): boolean;
+
+    // Called when the pointer enters a decoration.
+    // Registering either hover method automatically enables hover tracking for the group.
+    onDecorationPointerEnter?(event: OnDecorationPointerEnterEvent): void;
+
+    // Called when the pointer leaves a decoration.
+    // rect is absent if the decoration was removed from the DOM before leave fired.
+    // point is the current pointer position at the moment of leave.
+    onDecorationPointerLeave?(event: OnDecorationPointerLeaveEvent): void;
+}
+```
+
+### `DirectCommsChannel`
+
+Connects the `DecorationController` to the `Decorator` module in the same process.
+
+```ts
+const channel = new DirectCommsChannel();
+channel.frame  // pass to Decorator.mount
+channel.host   // pass to DecorationController constructor
+```
+
+### `Decorator`
+
+Mounts and unmounts the decoration renderer on a page.
+
+```ts
+class Decorator {
+    mount(wnd: Window, comms: IComms): boolean
+    unmount(wnd: Window, comms: IComms): boolean
+}
+```
+
+## Types
+
+| Name | Notes |
+|------|-------|
+| `Decoration` | `{ id, locator, style, extras? }` |
+| `DecorationStyle` | `BuiltinDecorationStyle \| HTMLDecorationTemplate \| NamedDecorationStyle` |
+| `BuiltinDecorationStyle` | `{ type?, tint?, layout?, width?, enforceContrast?, expand? }` |
+| `HTMLDecorationTemplate` | `{ type: "template", layout, width, element, stylesheet? }` — `element` is a function `(decoration) => string`, resolved to HTML per decoration before rendering |
+| `NamedDecorationStyle` | `{ type: string }` — reference to a style registered in `DecorationControllerConfig.decorationTemplates` |
+| `DecorationStyleType` | `"highlight" \| "highlightUnderline" \| "underline" \| "strikethrough" \| "outline" \| "textColor" \| "mask" \| "template"` |
+| `DecorationLayout` | `"boxes" \| "bounds"` |
+| `DecorationWidth` | `"wrap" \| "viewport" \| "bounds" \| "page"` |
+| `DecorationObserver` | `{ onDecorationActivated?, onDecorationPointerEnter?, onDecorationPointerLeave? }` |
+| `OnDecorationActivatedEvent` | `{ decoration, group, rect, point }` |
+| `OnDecorationPointerEnterEvent` | `{ decoration, group, rect, point }` |
+| `OnDecorationPointerLeaveEvent` | `{ decoration, group, rect?, point? }` — rect absent if decoration removed from DOM before leave fired |
+| `IComms` | Interface for the comms channel module side |

decorator/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@readium/decorator",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Standalone decoration controller for Readium publications",
+  "author": "readium",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/readium/ts-toolkit.git",
+    "directory": "decorator"
+  },
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/readium/ts-toolkit/issues"
+  },
+  "homepage": "https://github.com/readium/ts-toolkit",
+  "main": "./dist/index.umd.cjs",
+  "module": "./dist/index.js",
+  "types": "./types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/src/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.umd.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "types"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "rimraf types dist",
+    "build": "pnpm clean && tsc && vite build"
+  },
+  "devDependencies": {
+    "@readium/helpers": "workspace:*",
+    "@readium/navigator-html-injectables": "workspace:*",
+    "@readium/shared": "workspace:*",
+    "rimraf": "^6.1.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  }
+}

decorator/src/Decoration.ts

@@ -0,0 +1,16 @@
+import type { DecorationActivatedEvent, DecorationPointerEnterData, DecorationPointerLeaveData } from "@readium/navigator-html-injectables";
+import type { Decoration } from "./styles.ts";
+
+export interface OnDecorationActivatedEvent<D = Decoration> extends Omit<DecorationActivatedEvent, "decorationId"> {
+    decoration: D;
+}
+
+export type OnDecorationPointerEnterEvent<D = Decoration> = Omit<DecorationPointerEnterData, "decorationId"> & { decoration: D };
+
+export type OnDecorationPointerLeaveEvent<D = Decoration> = Omit<DecorationPointerLeaveData, "decorationId"> & { decoration: D };
+
+export interface DecorationObserver<D = Decoration> {
+    onDecorationActivated?(event: OnDecorationActivatedEvent<D>): boolean;
+    onDecorationPointerEnter?(event: OnDecorationPointerEnterEvent<D>): void;
+    onDecorationPointerLeave?(event: OnDecorationPointerLeaveEvent<D>): void;
+}

decorator/src/comms/direct.ts

@@ -0,0 +1,93 @@
+import type { IComms, CommsCallback } from "@readium/navigator-html-injectables";
+
+type AckFn = (ok: boolean) => void;
+type EventListener = (data: unknown) => void;
+
+export class DirectCommsChannel {
+    readonly frame: DirectCommsFrame;
+    readonly host: DirectCommsHost;
+
+    constructor() {
+        this.frame = new DirectCommsFrame(this);
+        this.host = new DirectCommsHost(this);
+    }
+}
+
+export class DirectCommsFrame implements IComms {
+    private registrar = new Map<string, { module: string; cb: CommsCallback }[]>();
+
+    constructor(private readonly channel: DirectCommsChannel) {}
+
+    register(key: string | string[], module: string, callback: CommsCallback): void {
+        const keys = Array.isArray(key) ? key : [key];
+        keys.forEach(k => {
+            const listeners = this.registrar.get(k) ?? [];
+            const existing = listeners.find(l => l.module === module);
+            if (existing) throw new Error(`Duplicate callback for "${k}" in module "${module}"`);
+            listeners.push({ module, cb: callback });
+            this.registrar.set(k, listeners);
+        });
+    }
+
+    unregister(key: string | string[], module: string): void {
+        const keys = Array.isArray(key) ? key : [key];
+        keys.forEach(k => {
+            const ls = this.registrar.get(k);
+            if (!ls) return;
+            this.registrar.set(k, ls.filter(l => l.module !== module));
+        });
+    }
+
+    unregisterAll(module: string): void {
+        this.registrar.forEach((ls, k) => {
+            this.registrar.set(k, ls.filter(l => l.module !== module));
+        });
+    }
+
+    _dispatch(key: string, data: unknown, ack: AckFn): void {
+        const ls = this.registrar.get(key);
+        if (!ls?.length) { ack(false); return; }
+        ls.forEach(l => l.cb(data, ack));
+    }
+
+    send(key: string, data: unknown): void {
+        this.channel.host._receive(key, data);
+    }
+
+    log(...data: unknown[]): void {
+        this.channel.host._receive("log", data);
+    }
+
+    readonly ready = true;
+
+    destroy(): void {
+        this.registrar.clear();
+    }
+}
+
+export class DirectCommsHost {
+    private listeners = new Map<string, EventListener[]>();
+
+    constructor(private readonly channel: DirectCommsChannel) {}
+
+    send(key: string, data: unknown, callback?: AckFn): void {
+        this.channel.frame._dispatch(key, data, callback ?? (() => {}));
+    }
+
+    on(key: string, cb: EventListener): void {
+        const ls = this.listeners.get(key) ?? [];
+        ls.push(cb);
+        this.listeners.set(key, ls);
+    }
+
+    off(key: string, cb: EventListener): void {
+        const ls = this.listeners.get(key);
+        if (ls) this.listeners.set(key, ls.filter(l => l !== cb));
+    }
+
+    _receive(key: string, data: unknown): void {
+        this.listeners.get(key)?.forEach(cb => cb(data));
+    }
+
+    readonly ready = true;
+}