@peekling/runtime 0.1.0 → 0.1.2

package/README.md

@@ -10,7 +10,7 @@ data cannot contain code, callbacks, DOM nodes, or raw HTML.
 ## Install
 
 ```sh
-npm install @peekling/runtime@0.1.0
+npm install @peekling/runtime@0.1.2
 ```
 
 The runtime supports modern ESM applications and the complete browser bundle.
@@ -48,6 +48,11 @@ After `ready` resolves, the Pack, stylesheet, initial State, and owned DOM are
 ready. `character: "peek"` is a networked selection. It resolves an exact pinned
 manifest and verifies the manifest and selected atlas before browser decoding.
 
+The default `companion` behavior follows the pointer when the Pack provides
+locomotion. The character can also be dragged and thrown. Clicking the character
+shows or hides its owned content bubble. Set `interaction: false` only when the
+host needs a pointer-transparent character with no direct control.
+
 Other bundlers can copy `@peekling/runtime/peekling.css` to a public asset and
 pass its final URL through `styles.url`. An HTTP or HTTPS ESM module can omit
 `styles` when a usable `peekling.css` sits beside the module. A module location
@@ -85,6 +90,8 @@ mirrored asset.
 | `override(input)`     | Request temporary ownership of declared presentation channels.                                              |
 | `pause()`             | Add the host pause reason and park runtime work.                                                            |
 | `resume()`            | Remove the host pause reason. Work resumes after every suspension reason clears.                            |
+| `refreshTargets()`    | Refresh host-approved target geometry after an application-specific layout change.                          |
+| `setIndicator(value)` | Replace the accessible dot or count notification, including its optional color. Pass `null` to clear it.    |
 | `destroy()`           | Abort pending work and release the instance's listeners, observers, frames, timers, roots, and object URLs. |
 
 Configuration failures that can be decided without Pack bytes throw before
@@ -138,6 +145,46 @@ The selected State must exist in the Pack. An Override never edits the Plan.
 When its lifetime ends, the runtime reevaluates the unchanged Plan from current
 world state.
 
+## Drag, throw, click, and custom routes
+
+Direct manipulation is enabled without adding Plan rules:
+
+```js
+const companion = hatch({
+  character: "peek",
+  interaction: {
+    gravity: 1800,
+    maxThrowSpeed: 1800,
+    bounce: 0.35,
+    label: "Open controls or drag Peek",
+  },
+});
+```
+
+Press actions can toggle, show, or hide content. They can also emit one bounded
+application Event. A drag suppresses its trailing click. Throw integration is
+time based, bounded to the viewport, and releases ownership back to the Plan
+after landing.
+
+Targets connect motion or catching to host-approved geometry. Custom SVG paths
+remain data and are sampled with detached browser geometry. See
+[Character interaction and motion](../../docs/interaction-and-motion.md) for a
+complete sunlit nook, viewport traversal, target catching, notification badge,
+and custom path examples.
+
+## Optional Canvas renderer
+
+Use the Canvas entry point when character frame presentation should use Canvas
+2D:
+
+```js
+import { hatchCanvas as hatch } from "@peekling/runtime/canvas";
+```
+
+Canvas uses the same Configuration, Pack, Plan, Event queue, interaction,
+physics, targets, and lifecycle as the default DOM renderer. Content bubbles
+remain DOM surfaces so native controls and accessibility keep working.
+
 See the repository [configuration guide](../../docs/configuration.md) for Plan
 syntax and recipes. The [execution model](../../docs/execution-model.md) defines
 Event ordering, channel ownership, Override conflicts, and cleanup.
@@ -150,14 +197,14 @@ free. The element is a lifecycle facade over hatch, not a second engine.
 ```html
 <script
   defer
-  src="https://cdn.jsdelivr.net/npm/@peekling/runtime@0.1.0/dist/peekling.min.js"
+  src="https://cdn.jsdelivr.net/npm/@peekling/runtime@0.1.2/dist/peekling.min.js"
   integrity="sha384-<runtime-release-hash>"
   crossorigin="anonymous"
 ></script>
 
 <peekling-character
   character="peek"
-  styles-url="https://cdn.jsdelivr.net/npm/@peekling/runtime@0.1.0/dist/peekling.css"
+  styles-url="https://cdn.jsdelivr.net/npm/@peekling/runtime@0.1.2/dist/peekling.css"
   styles-integrity="sha256-<stylesheet-release-hash>"
 ></peekling-character>
 ```
@@ -255,6 +302,7 @@ admission, use the repository
 | Import                           | Contents                                                                                                   |
 | -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
 | `@peekling/runtime`              | Side-effect-free ESM hatch API, public types, visibility helpers, and explicit Web Component registration. |
+| `@peekling/runtime/canvas`       | Optional Canvas 2D character renderer using the same runtime contract.                                     |
 | `@peekling/runtime/browser`      | Complete browser-global artifact.                                                                          |
 | `@peekling/runtime/peekling.css` | Required runtime stylesheet asset.                                                                         |
 | `@peekling/runtime/pack`         | Supported Pack parsing and validation surface for authoring tools.                                         |
@@ -272,17 +320,20 @@ host surfaces, blocked stylesheets, suspension, dismissal recovery, remount
 cleanup, hostile host layout, root repair, and contained failures in Chromium,
 Firefox, and WebKit.
 
+The 0.1.2 record below measures the interaction and renderer release with the
+exact release toolchain and required reserve.
+
 <!-- peekling-size-evidence:start -->
 
-The recorded canonical delivery measurement is 32,287 bytes gzip and 28,635
-bytes Brotli. Against the 32 KiB gzip and 32 KiB Brotli caps, that recorded
-build leaves 481 bytes of gzip headroom and 4,133 bytes of Brotli headroom.
-After the required 256-byte reserve, 225 gzip bytes and 3,877 Brotli bytes
+The recorded canonical delivery measurement is 38,139 bytes gzip and 33,418
+bytes Brotli. Against the 40 KiB gzip and 40 KiB Brotli caps, that recorded
+build leaves 2,821 bytes of gzip headroom and 7,542 bytes of Brotli headroom.
+After the required 256-byte reserve, 2,565 gzip bytes and 7,286 Brotli bytes
 remain for that build.
 <!-- peekling-size-evidence:end -->
 
 The record is bound to artifact hashes. Node 22.14.0, npm 11.16.0, and Node's
-default zlib compression certify the recorded values. Other supported Node
+default zlib compression certify those recorded values. Other supported Node
 versions still enforce their local size cap and reserve.
 
 The [browser performance guide](../../docs/browser-performance.md) explains the

package/dist/canvas-renderer.d.ts

@@ -0,0 +1,17 @@
+import { type CharacterRenderer, type CharacterRendererFactory } from "./renderer.js";
+import { type RuntimeStyleAsset } from "./styles.js";
+import type { NormalizedPack, Point } from "./types.js";
+/** Optional Canvas 2D presentation for the same runtime and Plan evaluator. */
+export declare class CanvasRenderer implements CharacterRenderer {
+    #private;
+    readonly host: HTMLElement;
+    readonly ready: Promise<void>;
+    constructor(document: Document, pack: NormalizedPack, atlasUrl: string, scale: number, styles: RuntimeStyleAsset);
+    swapAtlas(pack: NormalizedPack, atlasUrl: string): Promise<void>;
+    setHidden(hidden: boolean): void;
+    nextFrameIn(now: number): number | undefined;
+    render(stateName: string, now: number, position: Point, devicePixelRatio?: number, lift?: number): void;
+    destroy(): void;
+}
+export declare const createCanvasRenderer: CharacterRendererFactory;
+//# sourceMappingURL=canvas-renderer.d.ts.map

package/dist/canvas-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-renderer.d.ts","sourceRoot":"","sources":["../src/canvas-renderer.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC9B,MAAM,eAAe,CAAC;AAEvB,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExD,+EAA+E;AAC/E,qBAAa,cAAe,YAAW,iBAAiB;;IACtD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAkB9B,YACE,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,iBAAiB,EAkC1B;IAEK,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrE;IAED,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAE/B;IAED,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAmB3C;IAED,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,KAAK,EACf,gBAAgB,SAAI,EACpB,IAAI,SAAI,GACP,IAAI,CA8DN;IAED,OAAO,IAAI,IAAI,CAOd;CA4DF;AAED,eAAO,MAAM,oBAAoB,EAAE,wBAOhC,CAAC"}

package/dist/canvas-renderer.js

@@ -0,0 +1,192 @@
+import { animationCycleMs } from "./locomotion.js";
+import { frameAt, snapToDevicePixel, } from "./renderer.js";
+import { runtimeMessage } from "./runtime-diagnostics.js";
+import { connectRuntimeHost, ShadowStyleSheet, } from "./styles.js";
+/** Optional Canvas 2D presentation for the same runtime and Plan evaluator. */
+export class CanvasRenderer {
+    host;
+    ready;
+    #document;
+    #root;
+    #canvas;
+    #context;
+    #styles;
+    #canvasRule;
+    #pack;
+    #image;
+    #scale;
+    #logicalWidth = 0;
+    #logicalHeight = 0;
+    #state = "";
+    #stateStartedAt = 0;
+    #frame = -1;
+    #destroyed = false;
+    #loadGeneration = 0;
+    constructor(document, pack, atlasUrl, scale, styles) {
+        this.#document = document;
+        this.#pack = pack;
+        this.#scale = scale;
+        this.host = document.createElement("div");
+        this.host.setAttribute("aria-hidden", "true");
+        this.host.setAttribute("data-peekling-host", "");
+        this.host.setAttribute("data-peekling-renderer", "canvas");
+        this.#root = this.host.attachShadow({ mode: "closed" });
+        this.#styles = new ShadowStyleSheet(document, this.#root, styles);
+        this.#canvas = document.createElement("canvas");
+        this.#canvas.className = "sprite";
+        const context = this.#canvas.getContext("2d", { alpha: true });
+        if (!context) {
+            throw new Error(runtimeMessage("renderer.canvas", "Canvas 2D is unavailable"));
+        }
+        this.#context = context;
+        this.#image = document.createElement("img");
+        this.#root.append(this.#canvas);
+        this.ready = Promise.all([
+            this.#styles.ready.then(() => {
+                if (this.#destroyed)
+                    return;
+                this.#canvasRule = this.#styles.addRule(".sprite");
+            }),
+            this.#loadAtlas(pack, atlasUrl),
+        ]).then(() => {
+            if (this.#destroyed)
+                return;
+            this.#applyGeometry(pack);
+        });
+        void this.ready.catch(() => { });
+        this.#repair();
+    }
+    async swapAtlas(pack, atlasUrl) {
+        if (this.#destroyed)
+            return;
+        await this.#loadAtlas(pack, atlasUrl);
+        if (this.#destroyed || this.#pack !== pack)
+            return;
+        this.#applyGeometry(pack);
+        this.#frame = -1;
+    }
+    setHidden(hidden) {
+        if (!this.#destroyed)
+            this.host.toggleAttribute("hidden", hidden);
+    }
+    nextFrameIn(now) {
+        if (this.#destroyed)
+            return;
+        const state = this.#pack.states[this.#state];
+        if (!state || state.frames.length < 2)
+            return;
+        const elapsed = Math.max(0, now - this.#stateStartedAt);
+        if (state.durations?.length === state.frames.length) {
+            const total = animationCycleMs(state);
+            if (!state.loop && elapsed >= total - state.durations.at(-1))
+                return;
+            const active = state.loop ? elapsed % total : elapsed;
+            let boundary = 0;
+            for (const duration of state.durations) {
+                boundary += duration;
+                if (boundary > active)
+                    return boundary - active;
+            }
+            return state.loop ? state.durations[0] : undefined;
+        }
+        const interval = 1000 / (state.fps ?? 1);
+        if (!state.loop && elapsed >= interval * (state.frames.length - 1))
+            return;
+        return interval - (elapsed % interval || 0);
+    }
+    render(stateName, now, position, devicePixelRatio = 1, lift = 0) {
+        if (this.#destroyed)
+            return;
+        this.#repair();
+        const state = this.#pack.states[stateName];
+        if (!state) {
+            throw new Error(runtimeMessage("renderer.state", `Renderer received unknown state ${stateName}`));
+        }
+        if (stateName !== this.#state) {
+            this.#state = stateName;
+            this.#stateStartedAt = now;
+            this.#frame = -1;
+            this.host.setAttribute("data-peekling-state", stateName);
+        }
+        const frame = frameAt(state, now - this.#stateStartedAt);
+        if (frame !== this.#frame && this.#image.complete) {
+            const column = frame % this.#pack.atlas.columns;
+            const row = Math.floor(frame / this.#pack.atlas.columns);
+            const sourceWidth = this.#pack.atlas.cellWidth;
+            const sourceHeight = this.#pack.atlas.cellHeight;
+            this.#context.clearRect(0, 0, sourceWidth, sourceHeight);
+            this.#context.drawImage(this.#image, column * sourceWidth, row * sourceHeight, sourceWidth, sourceHeight, 0, 0, sourceWidth, sourceHeight);
+            this.#frame = frame;
+            this.host.setAttribute("data-peekling-frame", String(frame));
+        }
+        const width = this.#logicalWidth * this.#scale;
+        const height = this.#logicalHeight * this.#scale;
+        const x = snapToDevicePixel(position.x - width / 2, devicePixelRatio);
+        const y = snapToDevicePixel(position.y - height / 2 - lift, devicePixelRatio);
+        const rule = this.#canvasRule;
+        if (!rule) {
+            throw new Error(runtimeMessage("renderer.styles", "Peekling stylesheet is not ready"));
+        }
+        const transform = `translate3d(${x}px,${y}px,0) scale(${this.#scale})`;
+        if (rule.transform !== transform)
+            rule.transform = transform;
+        const xValue = String(x);
+        const yValue = String(y);
+        if (this.host.getAttribute("data-peekling-x") !== xValue) {
+            this.host.setAttribute("data-peekling-x", xValue);
+        }
+        if (this.host.getAttribute("data-peekling-y") !== yValue) {
+            this.host.setAttribute("data-peekling-y", yValue);
+        }
+    }
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        this.#loadGeneration += 1;
+        this.#image.src = "";
+        this.#styles.destroy();
+        this.host.remove();
+    }
+    async #loadAtlas(pack, atlasUrl) {
+        const generation = ++this.#loadGeneration;
+        const image = this.#document.createElement("img");
+        image.decoding = "async";
+        await new Promise((resolve, reject) => {
+            image.addEventListener("load", () => resolve(), { once: true });
+            image.addEventListener("error", () => reject(new Error(runtimeMessage("renderer.canvas-atlas", "Canvas atlas failed"))), { once: true });
+            image.src = atlasUrl;
+        });
+        if (this.#destroyed || generation !== this.#loadGeneration)
+            return;
+        this.#pack = pack;
+        this.#image = image;
+    }
+    #applyGeometry(pack) {
+        const rule = this.#canvasRule;
+        if (!rule) {
+            throw new Error(runtimeMessage("renderer.styles", "Peekling stylesheet is not ready"));
+        }
+        this.#logicalWidth = pack.atlas.logicalWidth ?? pack.atlas.cellWidth;
+        this.#logicalHeight = pack.atlas.logicalHeight ?? pack.atlas.cellHeight;
+        this.#canvas.width = pack.atlas.cellWidth;
+        this.#canvas.height = pack.atlas.cellHeight;
+        rule.width = `${this.#logicalWidth}px`;
+        rule.height = `${this.#logicalHeight}px`;
+        rule.imageRendering =
+            (pack.atlas.density ?? 1) === 1 ? "pixelated" : "auto";
+    }
+    #repair() {
+        if (this.#destroyed)
+            return;
+        connectRuntimeHost(this.host, this.#document, "data-peekling-host");
+        if (this.#root.host !== this.host ||
+            this.#canvas.getRootNode() !== this.#root) {
+            throw new Error(runtimeMessage("renderer.root", "Peekling character root structure was changed"));
+        }
+        if (this.host.getAttribute("aria-hidden") !== "true") {
+            this.host.setAttribute("aria-hidden", "true");
+        }
+    }
+}
+export const createCanvasRenderer = (options) => new CanvasRenderer(options.document, options.pack, options.atlasUrl, options.scale, options.styles);

package/dist/canvas.d.ts

@@ -0,0 +1,5 @@
+import { type PeeklingHatchInput, type PeeklingInstance, type PeeklingOptions } from "./runtime.js";
+/** Hatch with Canvas 2D character pixels and accessible DOM content surfaces. */
+export declare function hatchCanvas(input: PeeklingHatchInput | PeeklingOptions): PeeklingInstance;
+export type { PeeklingHatchInput, PeeklingInstance, PeeklingOptions, } from "./runtime.js";
+//# sourceMappingURL=canvas.d.ts.map

package/dist/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AAEtB,iFAAiF;AACjF,wBAAgB,WAAW,CACzB,KAAK,EAAE,kBAAkB,GAAG,eAAe,GAC1C,gBAAgB,CAElB;AAED,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,GAChB,MAAM,cAAc,CAAC"}

package/dist/canvas.js

@@ -0,0 +1,6 @@
+import { createCanvasRenderer } from "./canvas-renderer.js";
+import { PeeklingRuntime, } from "./runtime.js";
+/** Hatch with Canvas 2D character pixels and accessible DOM content surfaces. */
+export function hatchCanvas(input) {
+    return PeeklingRuntime.hatch(input, createCanvasRenderer);
+}

package/dist/configuration-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configuration-validation.d.ts","sourceRoot":"","sources":["../src/configuration-validation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AA4B/D,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,KACZ,IAAI,CAAC;AAEV,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,sBAAuB,SAAQ,SAAS;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAEtD,YAAY,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAItD;CACF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,sBAAsB,GAC5B,WAAW,CA4Ib;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,OAAO,CAExE"}
+{"version":3,"file":"configuration-validation.d.ts","sourceRoot":"","sources":["../src/configuration-validation.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAgC/D,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,KACZ,IAAI,CAAC;AAEV,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,sBAAuB,SAAQ,SAAS;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAEtD,YAAY,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAItD;CACF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,sBAAsB,GAC5B,WAAW,CA6Jb;AAkQD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,OAAO,CAExE"}

package/dist/configuration-validation.js

@@ -1,5 +1,5 @@
 import { validateHostContent } from "./content.js";
-import { isHttpPath, isSurfaceColor, NAME_PATTERN } from "./contracts.js";
+import { EVENT_NAME_PATTERN, isHttpPath, isSurfaceColor, NAME_PATTERN, STATE_NAME_PATTERN, } from "./contracts.js";
 import { isRegisteredCharacter } from "./registry.js";
 import { compactRuntimeDiagnostics } from "./runtime-diagnostics.js";
 import { validStyleIntegrity } from "./styles.js";
@@ -13,6 +13,10 @@ const CONFIGURATION_FIELDS = [
     "atlasUrl",
     "styles",
     "plan",
+    "preset",
+    "targets",
+    "interaction",
+    "indicator",
     "content",
     "bindings",
     "theme",
@@ -50,6 +54,13 @@ export function validateConfiguration(options, baseUrl, fault) {
     if (options.format !== undefined && options.format !== 1) {
         reportConfigurationFault("unsupported-format", "$.format", fault);
     }
+    if (options.plan !== undefined && options.preset !== undefined) {
+        reportConfigurationFault("incompatible-behavior", "$.preset", fault);
+    }
+    if (options.preset !== undefined &&
+        !["companion", "still", "bottom-patrol", "viewport-roam"].includes(options.preset)) {
+        reportConfigurationFault("invalid-preset", "$.preset", fault);
+    }
     if (options.character !== undefined) {
         if (typeof options.character !== "string" ||
             !NAME_PATTERN.test(options.character)) {
@@ -127,6 +138,12 @@ export function validateConfiguration(options, baseUrl, fault) {
             content = {};
     }
     validateBindings(options.bindings, content, fault);
+    validateTargets(options.targets, fault);
+    validateInteraction(options.interaction, options.targets, fault);
+    validateIndicator(options.indicator, fault);
+    if (options.interaction === false && options.indicator !== undefined) {
+        reportConfigurationFault("incompatible-indicator", "$.indicator", fault);
+    }
     validateTheme(options.theme, fault);
     validateDiagnostics(options.diagnostics, fault);
     validateAccessibility(options.accessibility, fault);
@@ -137,6 +154,164 @@ export function validateConfiguration(options, baseUrl, fault) {
     }
     return content;
 }
+function validateInteraction(interaction, targets, fault) {
+    if (interaction === undefined || interaction === false)
+        return;
+    const checked = shape(interaction, "invalid-interaction", "$.interaction", [
+        "press",
+        "pressEvent",
+        "drag",
+        "throw",
+        "dragState",
+        "riseState",
+        "fallState",
+        "landState",
+        "gravity",
+        "maxThrowSpeed",
+        "bounce",
+        "floorInset",
+        "label",
+        "contentInitiallyHidden",
+        "clearIndicatorOnPress",
+        "catchTarget",
+        "catchAnchor",
+        "catchMargin",
+        "catchEvent",
+    ], fault);
+    if (collectConfigurationFaults && !checked)
+        return;
+    const value = checked;
+    if (value.press !== undefined &&
+        ![
+            "toggle-content",
+            "show-content",
+            "hide-content",
+            "emit",
+            "none",
+        ].includes(value.press)) {
+        reportConfigurationFault("invalid-interaction", "$.interaction.press", fault);
+    }
+    if (value.pressEvent !== undefined &&
+        (typeof value.pressEvent !== "string" ||
+            !EVENT_NAME_PATTERN.test(value.pressEvent))) {
+        reportConfigurationFault("invalid-interaction-event", "$.interaction.pressEvent", fault);
+    }
+    if (value.press === "emit" && value.pressEvent === undefined) {
+        reportConfigurationFault("missing-interaction-event", "$.interaction.pressEvent", fault);
+    }
+    if (value.pressEvent !== undefined &&
+        value.press !== undefined &&
+        value.press !== "emit") {
+        reportConfigurationFault("incompatible-interaction-event", "$.interaction.pressEvent", fault);
+    }
+    for (const field of [
+        "drag",
+        "throw",
+        "contentInitiallyHidden",
+        "clearIndicatorOnPress",
+    ]) {
+        if (value[field] !== undefined && typeof value[field] !== "boolean") {
+            reportConfigurationFault("invalid-interaction", `$.interaction.${field}`, fault);
+        }
+    }
+    for (const field of [
+        "dragState",
+        "riseState",
+        "fallState",
+        "landState",
+    ]) {
+        if (value[field] !== undefined &&
+            (typeof value[field] !== "string" ||
+                !STATE_NAME_PATTERN.test(value[field]))) {
+            reportConfigurationFault("invalid-interaction-state", `$.interaction.${field}`, fault);
+        }
+    }
+    for (const [field, minimum, maximum] of [
+        ["gravity", 0, 10_000],
+        ["maxThrowSpeed", 0, 10_000],
+        ["bounce", 0, 1],
+        ["floorInset", 0, 1_000],
+        ["catchMargin", 0, 1_000],
+    ]) {
+        const item = value[field];
+        if (item !== undefined &&
+            (typeof item !== "number" ||
+                !Number.isFinite(item) ||
+                item < minimum ||
+                item > maximum)) {
+            reportConfigurationFault("invalid-interaction-range", `$.interaction.${field}`, fault);
+        }
+    }
+    if (value.label !== undefined && !text(value.label, 120)) {
+        reportConfigurationFault("invalid-interaction-label", "$.interaction.label", fault);
+    }
+    if (value.catchTarget !== undefined &&
+        (typeof value.catchTarget !== "string" ||
+            !NAME_PATTERN.test(value.catchTarget) ||
+            !Object.hasOwn(targets ?? {}, value.catchTarget))) {
+        reportConfigurationFault("invalid-catch-target", "$.interaction.catchTarget", fault);
+    }
+    if (value.catchAnchor !== undefined &&
+        !["center", "top", "right", "bottom", "left"].includes(value.catchAnchor)) {
+        reportConfigurationFault("invalid-catch-anchor", "$.interaction.catchAnchor", fault);
+    }
+    if (value.catchEvent !== undefined &&
+        (typeof value.catchEvent !== "string" ||
+            !EVENT_NAME_PATTERN.test(value.catchEvent))) {
+        reportConfigurationFault("invalid-interaction-event", "$.interaction.catchEvent", fault);
+    }
+}
+function validateIndicator(indicator, fault) {
+    if (indicator === undefined)
+        return;
+    const checked = shape(indicator, "invalid-indicator", "$.indicator", ["kind", "count", "label", "color", "visible"], fault);
+    if (collectConfigurationFaults && !checked)
+        return;
+    const value = checked;
+    if (value.kind !== undefined &&
+        value.kind !== "dot" &&
+        value.kind !== "count") {
+        reportConfigurationFault("invalid-indicator", "$.indicator.kind", fault);
+    }
+    if (!text(value.label, 120)) {
+        reportConfigurationFault("invalid-indicator", "$.indicator.label", fault);
+    }
+    if (value.count !== undefined &&
+        (typeof value.count !== "number" ||
+            !Number.isInteger(value.count) ||
+            value.count < 0 ||
+            value.count > 999)) {
+        reportConfigurationFault("invalid-indicator", "$.indicator.count", fault);
+    }
+    if (value.color !== undefined && !isSurfaceColor(value.color)) {
+        reportConfigurationFault("invalid-indicator", "$.indicator.color", fault);
+    }
+    if (value.visible !== undefined && typeof value.visible !== "boolean") {
+        reportConfigurationFault("invalid-indicator", "$.indicator.visible", fault);
+    }
+}
+function validateTargets(targets, fault) {
+    if (targets === undefined)
+        return;
+    const checked = shape(targets, "invalid-targets", "$.targets", undefined, fault);
+    if (collectConfigurationFaults && !checked)
+        return;
+    const entries = Object.entries(checked);
+    if (entries.length > 16) {
+        reportConfigurationFault("target-limit", "$.targets", fault);
+    }
+    for (const [id, selector] of entries) {
+        if (!NAME_PATTERN.test(id)) {
+            reportConfigurationFault("invalid-target", `$.targets.${id}`, fault, id);
+        }
+        if (typeof selector !== "string" ||
+            selector.length < 1 ||
+            selector.length > 256 ||
+            /[\0\r\n]/.test(selector)) {
+            reportConfigurationFault("invalid-target-selector", `$.targets.${id}`, fault, id);
+        }
+    }
+}
 export function validRuntimeName(value) {
     return value === undefined || typeof value === "boolean" || text(value, 80);
 }

package/dist/content.d.ts

@@ -39,6 +39,9 @@ export declare class ContentRenderer {
         width: number;
         height: number;
     }, name?: string): void;
+    setUserHidden(hidden: boolean): boolean;
+    toggleUserHidden(): boolean;
+    get userHidden(): boolean;
     destroy(): void;
 }
 //# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,WAAW,EAGhB,KAAK,YAAY,EAGjB,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,aAAa,CAAC;AAErB,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,EAAE,MAAM,GACd,WAAW,CA2Cb;AAyGD,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,EACpC,OAAO,EAAE,WAAW,GACnB,IAAI,CAON;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,KAAK,EACf,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC3C,SAAS,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5C,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzC,KAAK,CAwBP;AA8CD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,YAAY,EAAE,UAAU,CAAC;IAC5E,IAAI,CAAC,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,qBAAa,eAAe;;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IA2B9B,YAAY,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,sBAA2B,EAmCnE;IAED,cAAc,CACZ,UAAU,EAAE,SAAS,gBAAgB,EAAE,EACvC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,KAAK,EACf,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC3C,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC5C,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAuIN;IAmXD,OAAO,IAAI,IAAI,CAQd;CA0DF"}
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,WAAW,EAGhB,KAAK,YAAY,EAGjB,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,aAAa,CAAC;AAErB,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,EAAE,MAAM,GACd,WAAW,CA2Cb;AAyGD,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,EACpC,OAAO,EAAE,WAAW,GACnB,IAAI,CAON;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,KAAK,EACf,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC3C,SAAS,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5C,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzC,KAAK,CAwBP;AA8CD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,YAAY,EAAE,UAAU,CAAC;IAC5E,IAAI,CAAC,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,qBAAa,eAAe;;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IA6B9B,YAAY,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,sBAA2B,EAmCnE;IAED,cAAc,CACZ,UAAU,EAAE,SAAS,gBAAgB,EAAE,EACvC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,KAAK,EACf,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC3C,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC5C,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CA0IN;IAED,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAatC;IAED,gBAAgB,IAAI,OAAO,CAE1B;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAmXD,OAAO,IAAI,IAAI,CAQd;CA0DF"}

package/dist/content.js

@@ -150,6 +150,8 @@ export class ContentRenderer {
     #name;
     #nameSelection;
     #nameItem;
+    #userHidden = false;
+    #hasVisibleSurface = false;
     #destroyed = false;
     constructor(document, options = {}) {
         this.#document = document;
@@ -224,6 +226,17 @@ export class ContentRenderer {
             if (this.#destroyed)
                 return;
         }
+        let visible = false;
+        for (const surface of this.#surfaces.values()) {
+            if (!surface.host.hidden) {
+                visible = true;
+                break;
+            }
+        }
+        this.#hasVisibleSurface = visible;
+        const hidden = this.#userHidden || !visible;
+        if (this.#host.hidden !== hidden)
+            this.#host.hidden = hidden;
         const viewportChanged = viewport.width !== this.#viewportWidth ||
             viewport.height !== this.#viewportHeight;
         const placementChanged = viewportChanged ||
@@ -305,15 +318,28 @@ export class ContentRenderer {
             }
             this.#placementDirty = false;
         }
-        let visible = false;
-        for (const surface of this.#surfaces.values()) {
-            if (!surface.host.hidden) {
-                visible = true;
-                break;
+    }
+    setUserHidden(hidden) {
+        if (this.#destroyed)
+            return false;
+        const wasHidden = this.#userHidden;
+        this.#userHidden = hidden;
+        this.#host.hidden = hidden || !this.#hasVisibleSurface;
+        if (wasHidden && !hidden && !this.#host.hidden) {
+            for (const surface of this.#surfaces.values()) {
+                if (!surface.host.hidden)
+                    surface.measureDirty = true;
             }
+            this.#placementDirty = true;
+            this.#wake();
         }
-        if (this.#host.hidden === visible)
-            this.#host.hidden = !visible;
+        return !this.#userHidden;
+    }
+    toggleUserHidden() {
+        return this.setUserHidden(!this.#userHidden);
+    }
+    get userHidden() {
+        return this.#userHidden;
     }
     #select(selection, item, generation) {
         for (const region of CONTENT_REGIONS) {