@readium/decorator 1.0.0

package/README.md

@@ -0,0 +1,172 @@
+# @readium/decorator
+
+Renders visual annotations over text ranges in HTML content — highlights, underlines, strikethroughs, and more. Works on any HTML document.
+
+## Installation
+
+```sh
+npm install @readium/decorator
+```
+
+`@readium/decorator` depends on [`@readium/shared`](https://www.npmjs.com/package/@readium/shared) (for the `Locator` type, which identifies *where* a decoration goes) and `@readium/navigator-html-injectables` (the DOM renderer it wraps). Both are installed automatically as dependencies.
+
+### Requirements
+
+- A browser environment. The renderer (`Decorator`) mounts on a real `Window`/`document` and uses `ResizeObserver` and `MutationObserver` to keep decorations positioned as the page reflows — there's no server-side/Node rendering path.
+
+## Concepts
+
+- **Comms**: `DecorationController` (your app logic) and `Decorator` (the DOM renderer) talk over a small message-passing interface, handled for you by `DirectCommsChannel` (below).
+- **Groups**: every decoration belongs to a `group` (an arbitrary string you choose — `"tts"`, `"search-results"`, `"annotations"`, etc). `applyDecorations` replaces *all* decorations for one group at a time, diffing against that group's previous state. Separate groups don't interfere with each other, and each can independently opt into activation (tap/click) and hover tracking depending on which callbacks its `DecorationObserver` declares.
+- **Locators**: each decoration's `locator` is a `Locator` instance from `@readium/shared`, identifying the text range (or other target) to decorate within a resource.
+
+## Usage
+
+```ts
+import { Locator, LocatorLocations } from "@readium/shared";
+import { DirectCommsChannel, Decorator, DecorationController, DecorationStyleType } from "@readium/decorator";
+
+// 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
+const locator = new Locator({
+    href: "chapter1.xhtml",
+    type: "application/xhtml+xml",
+    locations: new LocatorLocations({ /* e.g. fragments, progression, ... */ }),
+});
+ctrl.applyDecorations([
+    {
+        id: "tts-0",
+        locator,
+        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 JS context (e.g. controller and renderer sharing one `window`). For a controller and renderer split across a real iframe boundary, implement `IComms` yourself (e.g. over `postMessage`) instead.
+
+```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 `Window`/document.
+
+```ts
+class Decorator {
+    mount(wnd: Window, comms: IComms): boolean
+    unmount(wnd: Window, comms: IComms): boolean
+}
+```
+
+### `IComms`
+
+The message-passing interface between a `DecorationController` (host side) and a `Decorator` (frame side). `DirectCommsChannel` implements this for you when both sides share a JS context; implement it yourself over `postMessage` when the renderer lives in a real iframe.
+
+```ts
+interface IComms {
+    // Registers a callback for one or more command keys, scoped to a module name.
+    register(key: string | string[], module: string, callback: (data: unknown, ack: (ok: boolean) => void) => void): void
+    unregister(key: string | string[], module: string): void
+    unregisterAll(module: string): void
+
+    // Sends an event with a payload. The receiving side dispatches it to matching register()'d callbacks.
+    send(key: string, data: unknown): void
+
+    log(...data: unknown[]): void
+    readonly ready: boolean
+    destroy(): void
+}
+```
+
+## Types
+
+| Name | Notes |
+|------|-------|
+| `Decoration` | `{ id, locator, style, extras? }` — `locator` is a `Locator` from `@readium/shared` |
+| `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 `DecoratorConfig.decorationTemplates` |
+| `DecoratorConfig` | `{ decorationTemplates? }` — same shape as `DecorationControllerConfig` (the latter is a type alias of this) |
+| `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 — see [`IComms`](#icomms) above |

package/dist/comms/direct.js

@@ -0,0 +1 @@
+class o{constructor(){this.queue=[],this.channel=typeof MessageChannel<"u"?new MessageChannel:void 0,this.channel&&(this.channel.port1.onmessage=()=>this.flush())}push(s){const t=this.queue.length===0;this.queue.push(s),t&&(this.channel?this.channel.port2.postMessage(null):setTimeout(()=>this.flush(),0))}flush(){const s=this.queue;this.queue=[],s.forEach(t=>t())}clear(){this.queue=[]}}class f{constructor(){this.frame=new c(this),this.host=new l(this)}}class c{constructor(s){this.channel=s,this.registrar=new Map,this.outbox=new o,this.ready=!0}register(s,t,e){(Array.isArray(s)?s:[s]).forEach(i=>{const h=this.registrar.get(i)??[];if(h.find(a=>a.module===t))throw new Error(`Duplicate callback for "${i}" in module "${t}"`);h.push({module:t,cb:e}),this.registrar.set(i,h)})}unregister(s,t){(Array.isArray(s)?s:[s]).forEach(r=>{const i=this.registrar.get(r);i&&this.registrar.set(r,i.filter(h=>h.module!==t))})}unregisterAll(s){this.registrar.forEach((t,e)=>{this.registrar.set(e,t.filter(r=>r.module!==s))})}_dispatch(s,t,e){const r=this.registrar.get(s);if(!r?.length){e(!1);return}r.forEach(i=>i.cb(t,e))}send(s,t){this.outbox.push(()=>this.channel.host._receive(s,t))}log(...s){this.outbox.push(()=>this.channel.host._receive("log",s))}destroy(){this.registrar.clear(),this.outbox.clear()}}class l{constructor(s){this.channel=s,this.listeners=new Map,this.outbox=new o,this.ready=!0}send(s,t,e){this.outbox.push(()=>this.channel.frame._dispatch(s,t,e??(()=>{})))}on(s,t){const e=this.listeners.get(s)??[];e.push(t),this.listeners.set(s,e)}off(s,t){const e=this.listeners.get(s);e&&this.listeners.set(s,e.filter(r=>r!==t))}_receive(s,t){this.listeners.get(s)?.forEach(e=>e(t))}}export{f as DirectCommsChannel,c as DirectCommsFrame,l as DirectCommsHost};

package/dist/controller/DecorationController.js

@@ -0,0 +1 @@
+import{supportsDecorationStyle as v,decorationsEqual as _,resolveDecorationForWire as d}from"../styles.js";class p{constructor(o,e={}){this.host=o,this._decorations=new Map,this._activationState=new Map,this._hoverState=new Map,this._observers=new Map,this._hoveredDecorations=new Map,this._config=e,o.on("decoration_activated",a=>{const t=a,r=this._decorations.get(t.group)?.find(i=>i.id===t.decorationId);r&&this._observers.get(t.group)?.forEach(i=>i.onDecorationActivated?.({group:t.group,decoration:r,rect:t.rect,point:t.point}))}),o.on("decoration_pointer_enter",a=>{const t=a,r=this._decorations.get(t.group)?.find(i=>i.id===t.decorationId);r&&(this._hoveredDecorations.set(t.group,r),this._observers.get(t.group)?.forEach(i=>i.onDecorationPointerEnter?.({group:t.group,decoration:r,rect:t.rect,point:t.point})))}),o.on("decoration_pointer_leave",a=>{const t=a,r=this._decorations.get(t.group)?.find(i=>i.id===t.decorationId)??this._hoveredDecorations.get(t.group);this._hoveredDecorations.delete(t.group),r&&this._observers.get(t.group)?.forEach(i=>i.onDecorationPointerLeave?.({group:t.group,decoration:r,rect:t.rect,point:t.point}))})}supportsDecorationStyle(o){return v(o,this._config.decorationTemplates)}applyDecorations(o,e){const a=this._decorations.get(e)??[],t=new Map(a.map(n=>[n.id,n])),r=new Map(o.map(n=>[n.id,n]));for(const[n,s]of t){const c=r.get(n);c?_(s,c)||this.host.send("decorate",{group:e,action:"update",decoration:d(c,this._config.decorationTemplates)}):this.host.send("decorate",{group:e,action:"remove",decoration:{id:n}})}for(const[n,s]of r)t.has(n)||this.host.send("decorate",{group:e,action:"add",decoration:d(s,this._config.decorationTemplates)});this._decorations.set(e,o);const i=this._activationState.get(e);i!==void 0&&this.host.send("decoration_activatable",{group:e,activatable:i});const h=this._hoverState.get(e);h!==void 0&&this.host.send("decoration_hoverable",{group:e,hoverable:h})}registerDecorationObserver(o,e){this._observers.has(o)||this._observers.set(o,new Set),this._observers.get(o).add(e),e.onDecorationActivated&&(this._activationState.set(o,!0),this.host.send("decoration_activatable",{group:o,activatable:!0})),(e.onDecorationPointerEnter||e.onDecorationPointerLeave)&&(this._hoverState.set(o,!0),this.host.send("decoration_hoverable",{group:o,hoverable:!0}))}unregisterDecorationObserver(o){this._observers.forEach((e,a)=>{if(!e.has(o))return;e.delete(o);const t=[...e].some(i=>i.onDecorationActivated);this._activationState.has(a)&&!t&&(this._activationState.delete(a),this.host.send("decoration_activatable",{group:a,activatable:!1}));const r=[...e].some(i=>i.onDecorationPointerEnter||i.onDecorationPointerLeave);this._hoverState.has(a)&&!r&&(this._hoverState.delete(a),this.host.send("decoration_hoverable",{group:a,hoverable:!1}))})}destroy(){this._decorations.clear(),this._activationState.clear(),this._hoverState.clear(),this._observers.clear(),this._hoveredDecorations.clear()}}export{p as DecorationController};

package/dist/index.js

@@ -0,0 +1 @@
+import{DecorationLayout as e,DecorationStyleType as t,DecorationWidth as a,Decorator as i}from"@readium/navigator-html-injectables";import{BUILTIN_DECORATION_TYPES as m,decorationsEqual as D,resolveDecorationForWire as n,supportsDecorationStyle as s}from"./styles.js";import{DirectCommsChannel as p,DirectCommsFrame as C,DirectCommsHost as f}from"./comms/direct.js";import{DecorationController as y}from"./controller/DecorationController.js";export{m as BUILTIN_DECORATION_TYPES,y as DecorationController,e as DecorationLayout,t as DecorationStyleType,a as DecorationWidth,i as Decorator,p as DirectCommsChannel,C as DirectCommsFrame,f as DirectCommsHost,D as decorationsEqual,n as resolveDecorationForWire,s as supportsDecorationStyle};

package/dist/styles.js

@@ -0,0 +1 @@
+import{DecorationStyleType as r}from"@readium/navigator-html-injectables";const u=new Set(Object.values(r));function f(t,e){return t===r.TextColor?typeof window<"u"&&"Highlight"in window:u.has(t)?!0:!!e?.[t]}function a(t,e){const{style:o}=t;if(o.type===r.Template){const n=o;return{...t,style:{...n,element:s(n,t)}}}if(o.type&&e?.[o.type]){const n=e[o.type];return{...t,style:{type:r.Template,layout:n.layout,width:n.width,stylesheet:n.stylesheet,element:s(n,t)}}}return t}function s(t,e){return typeof t.element=="function"?t.element(e):t.element}function y(t,e){if(t.type!==e.type)return!1;if(t.type===r.Template){const l=t,i=e;return l.layout===i.layout&&l.width===i.width&&l.stylesheet===i.stylesheet}const o=t,n=e;return o.tint===n.tint&&o.layout===n.layout&&o.width===n.width&&(o.enforceContrast??!0)===(n.enforceContrast??!0)&&(o.expand??0)===(n.expand??0)}function p(t,e){return t.locator.href===e.locator.href&&JSON.stringify(t.locator.locations?.serialize?.()??t.locator.locations)===JSON.stringify(e.locator.locations?.serialize?.()??e.locator.locations)&&JSON.stringify(t.locator.text??null)===JSON.stringify(e.locator.text??null)&&y(t.style,e.style)&&JSON.stringify(t.extras??null)===JSON.stringify(e.extras??null)}export{u as BUILTIN_DECORATION_TYPES,p as decorationsEqual,a as resolveDecorationForWire,f as supportsDecorationStyle};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@readium/decorator",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Standalone decoration controller and renderer for HTML content",
+  "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",
+  "types": "./types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "ts-toolkit-source": "./src/index.ts",
+      "types": "./types/src/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "types"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "rimraf types dist",
+    "build": "pnpm clean && tsc && vite build"
+  },
+  "dependencies": {
+    "@readium/navigator-html-injectables": "workspace:*",
+    "@readium/shared": "workspace:*"
+  },
+  "devDependencies": {
+    "rimraf": "^6.1.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  }
+}

package/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;
+}

package/src/comms/direct.ts

@@ -0,0 +1,130 @@
+import type { IComms, CommsCallback } from "@readium/navigator-html-injectables";
+
+type AckFn = (ok: boolean) => void;
+type EventListener = (data: unknown) => void;
+
+/**
+ * Defers pushed tasks to a macrotask, mirroring postMessage's scheduling (as opposed to a
+ * microtask) so the standalone direct-comms path behaves like the iframe/postMessage path:
+ * it never reenters the caller's stack, and it interleaves with rAF/observer callbacks the
+ * same way postMessage does. Tasks pushed within the same tick are flushed together, in order.
+ */
+class MacrotaskQueue {
+    private queue: (() => void)[] = [];
+    private readonly channel = typeof MessageChannel !== "undefined" ? new MessageChannel() : undefined;
+
+    constructor() {
+        if (this.channel) this.channel.port1.onmessage = () => this.flush();
+    }
+
+    push(task: () => void): void {
+        const wasEmpty = this.queue.length === 0;
+        this.queue.push(task);
+        if (wasEmpty) {
+            if (this.channel) this.channel.port2.postMessage(null);
+            else setTimeout(() => this.flush(), 0);
+        }
+    }
+
+    private flush(): void {
+        const tasks = this.queue;
+        this.queue = [];
+        tasks.forEach(task => task());
+    }
+
+    clear(): void {
+        this.queue = [];
+    }
+}
+
+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 }[]>();
+    private readonly outbox = new MacrotaskQueue();
+
+    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.outbox.push(() => this.channel.host._receive(key, data));
+    }
+
+    log(...data: unknown[]): void {
+        this.outbox.push(() => this.channel.host._receive("log", data));
+    }
+
+    readonly ready = true;
+
+    destroy(): void {
+        this.registrar.clear();
+        this.outbox.clear();
+    }
+}
+
+export class DirectCommsHost {
+    private listeners = new Map<string, EventListener[]>();
+    private readonly outbox = new MacrotaskQueue();
+
+    constructor(private readonly channel: DirectCommsChannel) {}
+
+    send(key: string, data: unknown, callback?: AckFn): void {
+        this.outbox.push(() => 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;
+}

package/src/controller/DecorationController.ts

@@ -0,0 +1,123 @@
+import type { DecorationActivatedEvent, DecorationPointerEnterData, DecorationPointerLeaveData } from "@readium/navigator-html-injectables";
+import type { DirectCommsHost } from "../comms/direct.ts";
+import type { DecorationObserver } from "../Decoration.ts";
+import type { Decoration, DecoratorConfig } from "../styles.ts";
+import { decorationsEqual, resolveDecorationForWire, supportsDecorationStyle } from "../styles.ts";
+
+export type DecorationControllerConfig = DecoratorConfig;
+
+export class DecorationController {
+    private _decorations = new Map<string, Decoration[]>();
+    private _activationState = new Map<string, boolean>();
+    private _hoverState = new Map<string, boolean>();
+    private _observers = new Map<string, Set<DecorationObserver>>();
+    private _hoveredDecorations = new Map<string, Decoration>();
+    private readonly _config: DecorationControllerConfig;
+
+    constructor(private readonly host: DirectCommsHost, config: DecorationControllerConfig = {}) {
+        this._config = config;
+        host.on("decoration_activated", (raw) => {
+            const ev = raw as DecorationActivatedEvent;
+            const decoration = this._decorations.get(ev.group)?.find(d => d.id === ev.decorationId);
+            if (!decoration) return;
+            this._observers.get(ev.group)?.forEach(obs =>
+                obs.onDecorationActivated?.({ group: ev.group, decoration, rect: ev.rect, point: ev.point })
+            );
+        });
+
+        host.on("decoration_pointer_enter", (raw) => {
+            const ev = raw as DecorationPointerEnterData;
+            const decoration = this._decorations.get(ev.group)?.find(d => d.id === ev.decorationId);
+            if (!decoration) return;
+            this._hoveredDecorations.set(ev.group, decoration);
+            this._observers.get(ev.group)?.forEach(obs =>
+                obs.onDecorationPointerEnter?.({ group: ev.group, decoration, rect: ev.rect, point: ev.point })
+            );
+        });
+
+        host.on("decoration_pointer_leave", (raw) => {
+            const ev = raw as DecorationPointerLeaveData;
+            const decoration = this._decorations.get(ev.group)?.find(d => d.id === ev.decorationId)
+                ?? this._hoveredDecorations.get(ev.group);
+            this._hoveredDecorations.delete(ev.group);
+            if (!decoration) return;
+            this._observers.get(ev.group)?.forEach(obs =>
+                obs.onDecorationPointerLeave?.({ group: ev.group, decoration, rect: ev.rect, point: ev.point })
+            );
+        });
+    }
+
+    supportsDecorationStyle(styleTypeId: string): boolean {
+        return supportsDecorationStyle(styleTypeId, this._config.decorationTemplates);
+    }
+
+    applyDecorations(decorations: Decoration[], group: string): void {
+        const previous = this._decorations.get(group) ?? [];
+        const prevById = new Map(previous.map(d => [d.id, d]));
+        const nextById = new Map(decorations.map(d => [d.id, d]));
+
+        for (const [id, prev] of prevById) {
+            const next = nextById.get(id);
+            if (!next) {
+                this.host.send("decorate", { group, action: "remove", decoration: { id } });
+            } else if (!decorationsEqual(prev, next)) {
+                this.host.send("decorate", { group, action: "update", decoration: resolveDecorationForWire(next, this._config.decorationTemplates) });
+            }
+        }
+        for (const [id, next] of nextById) {
+            if (!prevById.has(id)) {
+                this.host.send("decorate", { group, action: "add", decoration: resolveDecorationForWire(next, this._config.decorationTemplates) });
+            }
+        }
+
+        this._decorations.set(group, decorations);
+        const activatable = this._activationState.get(group);
+        if (activatable !== undefined) {
+            this.host.send("decoration_activatable", { group, activatable });
+        }
+        const hoverable = this._hoverState.get(group);
+        if (hoverable !== undefined) {
+            this.host.send("decoration_hoverable", { group, hoverable });
+        }
+    }
+
+    registerDecorationObserver(group: string, observer: DecorationObserver): void {
+        if (!this._observers.has(group)) this._observers.set(group, new Set());
+        this._observers.get(group)!.add(observer);
+        if (observer.onDecorationActivated) {
+            this._activationState.set(group, true);
+            this.host.send("decoration_activatable", { group, activatable: true });
+        }
+        if (observer.onDecorationPointerEnter || observer.onDecorationPointerLeave) {
+            this._hoverState.set(group, true);
+            this.host.send("decoration_hoverable", { group, hoverable: true });
+        }
+    }
+
+    unregisterDecorationObserver(observer: DecorationObserver): void {
+        this._observers.forEach((set, group) => {
+            if (!set.has(observer)) return;
+            set.delete(observer);
+
+            const stillActivatable = [...set].some(o => o.onDecorationActivated);
+            if (this._activationState.has(group) && !stillActivatable) {
+                this._activationState.delete(group);
+                this.host.send("decoration_activatable", { group, activatable: false });
+            }
+
+            const stillHoverable = [...set].some(o => o.onDecorationPointerEnter || o.onDecorationPointerLeave);
+            if (this._hoverState.has(group) && !stillHoverable) {
+                this._hoverState.delete(group);
+                this.host.send("decoration_hoverable", { group, hoverable: false });
+            }
+        });
+    }
+
+    destroy(): void {
+        this._decorations.clear();
+        this._activationState.clear();
+        this._hoverState.clear();
+        this._observers.clear();
+        this._hoveredDecorations.clear();
+    }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export type { IComms } from "@readium/navigator-html-injectables";
+export { Decorator } from "@readium/navigator-html-injectables";
+export type {
+    DecoratorRequest,
+    DecorationActivatedEvent as DecorationActivatedWireEvent,
+} from "@readium/navigator-html-injectables";
+export {
+    DecorationStyleType,
+    DecorationLayout,
+    DecorationWidth,
+} from "@readium/navigator-html-injectables";
+
+export * from "./styles.ts";
+export * from "./comms/direct.ts";
+export * from "./Decoration.ts";
+export * from "./controller/DecorationController.ts";

package/src/styles.ts

@@ -0,0 +1,121 @@
+import type {
+    Decoration as InjectableDecoration,
+    BuiltinDecorationStyle,
+    HTMLDecorationTemplate as WireHTMLDecorationTemplate,
+} from "@readium/navigator-html-injectables";
+import { DecorationStyleType } from "@readium/navigator-html-injectables";
+
+export type { BuiltinDecorationStyle };
+
+/**
+ * Author-level decoration template. `element` is a function called once per decoration to
+ * generate the HTML string that the injectable will render. The result is resolved
+ * (via {@link resolveDecorationForWire}) before postMessage and sanitized by the injectable.
+ */
+export interface HTMLDecorationTemplate extends Omit<WireHTMLDecorationTemplate, "element"> {
+    element: (decoration: Decoration) => string;
+}
+
+/** A reference to a named style registered in `DecoratorConfig.decorationTemplates`. */
+export interface NamedDecorationStyle {
+    type: string;
+}
+
+export type DecorationStyle = BuiltinDecorationStyle | HTMLDecorationTemplate | NamedDecorationStyle;
+
+export interface Decoration extends Omit<InjectableDecoration, "style"> {
+    style: DecorationStyle;
+}
+
+/** Configuration for decoration rendering. */
+export interface DecoratorConfig {
+    /**
+     * Named custom styles. Each key is a style type ID; the value is the template that
+     * generates the HTML for decorations of that type. When a decoration's `style.type`
+     * matches a key here, the template is resolved and sent to the injectable as a
+     * Template-type decoration.
+     */
+    decorationTemplates?: Record<string, HTMLDecorationTemplate>;
+}
+
+export const BUILTIN_DECORATION_TYPES = new Set<string>(Object.values(DecorationStyleType));
+
+/**
+ * Returns whether the given style type ID can be rendered.
+ * True for all built-in types and any IDs registered in `decorationTemplates`.
+ * TextColor additionally requires the CSS Highlight API.
+ */
+export function supportsDecorationStyle(
+    styleTypeId: string,
+    decorationTemplates?: Record<string, HTMLDecorationTemplate>
+): boolean {
+    if (styleTypeId === DecorationStyleType.TextColor) return typeof window !== "undefined" && "Highlight" in window;
+    if (BUILTIN_DECORATION_TYPES.has(styleTypeId)) return true;
+    return !!decorationTemplates?.[styleTypeId];
+}
+
+/**
+ * Resolves an author-level Decoration to a wire-safe plain object for postMessage.
+ * For Template styles, calls `element(decoration)` (or passes through an already-resolved
+ * string) and embeds the resulting HTML string. For registered custom style IDs (found in
+ * `decorationTemplates`), resolves the template and converts the style to a Template wire object.
+ */
+export function resolveDecorationForWire(
+    decoration: Decoration,
+    decorationTemplates?: Record<string, HTMLDecorationTemplate>
+): unknown {
+    const { style } = decoration;
+    if (style.type === DecorationStyleType.Template) {
+        const tpl = style as HTMLDecorationTemplate;
+        return { ...decoration, style: { ...tpl, element: resolveElement(tpl, decoration) } };
+    }
+    if (style.type && decorationTemplates?.[style.type]) {
+        const tpl = decorationTemplates[style.type];
+        return {
+            ...decoration,
+            style: {
+                type: DecorationStyleType.Template,
+                layout: tpl.layout,
+                width: tpl.width,
+                stylesheet: tpl.stylesheet,
+                element: resolveElement(tpl, decoration),
+            },
+        };
+    }
+    return decoration;
+}
+
+function resolveElement(tpl: HTMLDecorationTemplate, decoration: Decoration): string {
+    // A standalone caller may pass an already-resolved (string) element.
+    return typeof tpl.element === "function" ? tpl.element(decoration) : (tpl.element as unknown as string);
+}
+
+function stylesEqual(a: DecorationStyle, b: DecorationStyle): boolean {
+    if (a.type !== b.type) return false;
+    if (a.type === DecorationStyleType.Template) {
+        const ta = a as HTMLDecorationTemplate;
+        const tb = b as HTMLDecorationTemplate;
+        // element is a function — not comparable by value; excluded from equality
+        return ta.layout === tb.layout &&
+            ta.width === tb.width &&
+            ta.stylesheet === tb.stylesheet;
+    }
+    const ba = a as BuiltinDecorationStyle;
+    const bb = b as BuiltinDecorationStyle;
+    return ba.tint === bb.tint &&
+        ba.layout === bb.layout &&
+        ba.width === bb.width &&
+        (ba.enforceContrast ?? true) === (bb.enforceContrast ?? true) &&
+        (ba.expand ?? 0) === (bb.expand ?? 0);
+}
+
+export function decorationsEqual(a: Decoration, b: Decoration): boolean {
+    return (
+        a.locator.href === b.locator.href &&
+        JSON.stringify((a.locator.locations as any)?.serialize?.() ?? a.locator.locations) ===
+            JSON.stringify((b.locator.locations as any)?.serialize?.() ?? b.locator.locations) &&
+        JSON.stringify(a.locator.text ?? null) === JSON.stringify(b.locator.text ?? null) &&
+        stylesEqual(a.style, b.style) &&
+        JSON.stringify(a.extras ?? null) === JSON.stringify(b.extras ?? null)
+    );
+}

package/types/src/Decoration.d.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;
+}

package/types/src/comms/direct.d.ts

@@ -0,0 +1,34 @@
+import type { IComms, CommsCallback } from "@readium/navigator-html-injectables";
+type AckFn = (ok: boolean) => void;
+type EventListener = (data: unknown) => void;
+export declare class DirectCommsChannel {
+    readonly frame: DirectCommsFrame;
+    readonly host: DirectCommsHost;
+    constructor();
+}
+export declare class DirectCommsFrame implements IComms {
+    private readonly channel;
+    private registrar;
+    private readonly outbox;
+    constructor(channel: DirectCommsChannel);
+    register(key: string | string[], module: string, callback: CommsCallback): void;
+    unregister(key: string | string[], module: string): void;
+    unregisterAll(module: string): void;
+    _dispatch(key: string, data: unknown, ack: AckFn): void;
+    send(key: string, data: unknown): void;
+    log(...data: unknown[]): void;
+    readonly ready = true;
+    destroy(): void;
+}
+export declare class DirectCommsHost {
+    private readonly channel;
+    private listeners;
+    private readonly outbox;
+    constructor(channel: DirectCommsChannel);
+    send(key: string, data: unknown, callback?: AckFn): void;
+    on(key: string, cb: EventListener): void;
+    off(key: string, cb: EventListener): void;
+    _receive(key: string, data: unknown): void;
+    readonly ready = true;
+}
+export {};

package/types/src/controller/DecorationController.d.ts

@@ -0,0 +1,19 @@
+import type { DirectCommsHost } from "../comms/direct.ts";
+import type { DecorationObserver } from "../Decoration.ts";
+import type { Decoration, DecoratorConfig } from "../styles.ts";
+export type DecorationControllerConfig = DecoratorConfig;
+export declare class DecorationController {
+    private readonly host;
+    private _decorations;
+    private _activationState;
+    private _hoverState;
+    private _observers;
+    private _hoveredDecorations;
+    private readonly _config;
+    constructor(host: DirectCommsHost, config?: DecorationControllerConfig);
+    supportsDecorationStyle(styleTypeId: string): boolean;
+    applyDecorations(decorations: Decoration[], group: string): void;
+    registerDecorationObserver(group: string, observer: DecorationObserver): void;
+    unregisterDecorationObserver(observer: DecorationObserver): void;
+    destroy(): void;
+}

package/types/src/index.d.ts

@@ -0,0 +1,8 @@
+export type { IComms } from "@readium/navigator-html-injectables";
+export { Decorator } from "@readium/navigator-html-injectables";
+export type { DecoratorRequest, DecorationActivatedEvent as DecorationActivatedWireEvent, } from "@readium/navigator-html-injectables";
+export { DecorationStyleType, DecorationLayout, DecorationWidth, } from "@readium/navigator-html-injectables";
+export * from "./styles.ts";
+export * from "./comms/direct.ts";
+export * from "./Decoration.ts";
+export * from "./controller/DecorationController.ts";

package/types/src/styles.d.ts

@@ -0,0 +1,43 @@
+import type { Decoration as InjectableDecoration, BuiltinDecorationStyle, HTMLDecorationTemplate as WireHTMLDecorationTemplate } from "@readium/navigator-html-injectables";
+export type { BuiltinDecorationStyle };
+/**
+ * Author-level decoration template. `element` is a function called once per decoration to
+ * generate the HTML string that the injectable will render. The result is resolved
+ * (via {@link resolveDecorationForWire}) before postMessage and sanitized by the injectable.
+ */
+export interface HTMLDecorationTemplate extends Omit<WireHTMLDecorationTemplate, "element"> {
+    element: (decoration: Decoration) => string;
+}
+/** A reference to a named style registered in `DecoratorConfig.decorationTemplates`. */
+export interface NamedDecorationStyle {
+    type: string;
+}
+export type DecorationStyle = BuiltinDecorationStyle | HTMLDecorationTemplate | NamedDecorationStyle;
+export interface Decoration extends Omit<InjectableDecoration, "style"> {
+    style: DecorationStyle;
+}
+/** Configuration for decoration rendering. */
+export interface DecoratorConfig {
+    /**
+     * Named custom styles. Each key is a style type ID; the value is the template that
+     * generates the HTML for decorations of that type. When a decoration's `style.type`
+     * matches a key here, the template is resolved and sent to the injectable as a
+     * Template-type decoration.
+     */
+    decorationTemplates?: Record<string, HTMLDecorationTemplate>;
+}
+export declare const BUILTIN_DECORATION_TYPES: Set<string>;
+/**
+ * Returns whether the given style type ID can be rendered.
+ * True for all built-in types and any IDs registered in `decorationTemplates`.
+ * TextColor additionally requires the CSS Highlight API.
+ */
+export declare function supportsDecorationStyle(styleTypeId: string, decorationTemplates?: Record<string, HTMLDecorationTemplate>): boolean;
+/**
+ * Resolves an author-level Decoration to a wire-safe plain object for postMessage.
+ * For Template styles, calls `element(decoration)` (or passes through an already-resolved
+ * string) and embeds the resulting HTML string. For registered custom style IDs (found in
+ * `decorationTemplates`), resolves the template and converts the style to a Template wire object.
+ */
+export declare function resolveDecorationForWire(decoration: Decoration, decorationTemplates?: Record<string, HTMLDecorationTemplate>): unknown;
+export declare function decorationsEqual(a: Decoration, b: Decoration): boolean;