@toonstrip/element 0.1.0

package/dist/comic-strip-element.d.ts

@@ -0,0 +1,18 @@
+import { type ComicStripDocument } from "@toonstrip/schema";
+export declare class ComicStripElement extends HTMLElement {
+    #private;
+    constructor();
+    static get observedAttributes(): string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /** The strip to render, as data (validated at the boundary). */
+    get document(): ComicStripDocument | null;
+    set document(doc: ComicStripDocument | null);
+    /** Base URLs of registered asset packs, searched in the order given. */
+    get packs(): string[];
+    set packs(packs: string[]);
+    /** Column count as of the last layout pass — exposed for tests/consumers. */
+    get columns(): number;
+}
+export declare function registerComicStripElement(tagName?: string): void;

package/dist/comic-strip-element.js

@@ -0,0 +1,223 @@
+/**
+ * `<comic-strip>` — the embed primitive (dev plan §5). Ported from
+ * `grues-in-comic`'s `web/src/comic-view.ts` mechanism (canvas pool,
+ * ResizeObserver relayout, devicePixelRatio backing store, IntersectionObserver
+ * visibility gating, per-panel a11y), with the turn/session/incremental-append
+ * machinery stripped out: a `ComicStripDocument` here is authored data handed
+ * over whole, not a stream of panels a game emits (dev plan §0's non-goals).
+ */
+import { layoutStrip, renderPanel, selectFigures } from "@toonstrip/core";
+import { validateDocument } from "@toonstrip/schema";
+import { describePanel } from "./describe.js";
+import { loadCastFromPacks } from "./load-pack.js";
+const GUTTER = 10;
+function copyCycles(cycles) {
+    return new Map([...cycles].map(([id, cycle]) => [id, { ...cycle }]));
+}
+function characterIdsOf(doc) {
+    return [...new Set(doc.panels.flatMap((panel) => panel.bodies.map((body) => body.character)))];
+}
+function backdropIdsOf(doc) {
+    return [...new Set(doc.panels.filter((panel) => !panel.dark).map((panel) => panel.backdrop))];
+}
+const STYLE = `
+:host { display: block; }
+.strip {
+  display: grid;
+  gap: ${GUTTER}px;
+  justify-content: center;
+}
+.panel { display: block; background: #111; }
+.notice { color: #b00; font: 14px sans-serif; }
+`;
+export class ComicStripElement extends HTMLElement {
+    #root;
+    #strip;
+    #resizeObserver;
+    #visibilityObserver = null;
+    #doc = null;
+    #packs = [];
+    #cast = null;
+    #slots = [];
+    #frozen = new WeakMap();
+    #size = { width: 400, height: 340 };
+    #columns = 1;
+    #buildToken = 0;
+    constructor() {
+        super();
+        this.#root = this.attachShadow({ mode: "open" });
+        const style = document.createElement("style");
+        style.textContent = STYLE;
+        this.#strip = document.createElement("div");
+        this.#strip.className = "strip";
+        this.#root.append(style, this.#strip);
+        this.#resizeObserver = new ResizeObserver(() => this.#relayout());
+    }
+    static get observedAttributes() {
+        return ["src"];
+    }
+    connectedCallback() {
+        this.#resizeObserver.observe(this);
+        const src = this.getAttribute("src");
+        if (src)
+            this.#loadFromSrc(src);
+    }
+    disconnectedCallback() {
+        this.#resizeObserver.disconnect();
+        this.#visibilityObserver?.disconnect();
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (name === "src" && newValue && newValue !== oldValue)
+            this.#loadFromSrc(newValue);
+    }
+    /** The strip to render, as data (validated at the boundary). */
+    get document() {
+        return this.#doc;
+    }
+    set document(doc) {
+        this.#doc = doc ? validateDocument(doc) : null;
+        void this.#rebuild();
+    }
+    /** Base URLs of registered asset packs, searched in the order given. */
+    get packs() {
+        return this.#packs;
+    }
+    set packs(packs) {
+        this.#packs = [...packs];
+        void this.#rebuild();
+    }
+    async #loadFromSrc(src) {
+        try {
+            const res = await fetch(src);
+            if (!res.ok)
+                throw new Error(`fetch ${src} failed: ${res.status} ${res.statusText}`);
+            this.document = validateDocument(await res.json());
+        }
+        catch (err) {
+            this.#fail(err instanceof Error ? err.message : String(err));
+        }
+    }
+    #fail(message) {
+        this.#strip.replaceChildren();
+        const notice = document.createElement("p");
+        notice.className = "notice";
+        notice.textContent = message;
+        this.#strip.append(notice);
+        console.error("comic-strip:", message);
+    }
+    async #rebuild() {
+        const token = ++this.#buildToken;
+        this.#visibilityObserver?.disconnect();
+        this.#slots = [];
+        this.#strip.replaceChildren();
+        this.#cast = null;
+        if (!this.#doc)
+            return;
+        let cast;
+        try {
+            cast = await loadCastFromPacks(this.#packs, characterIdsOf(this.#doc), backdropIdsOf(this.#doc));
+        }
+        catch (err) {
+            if (token === this.#buildToken)
+                this.#fail(err instanceof Error ? err.message : String(err));
+            return;
+        }
+        if (token !== this.#buildToken)
+            return; // superseded by a later document/packs set
+        this.#cast = cast;
+        // Body selection happens once, in document order, and is frozen per panel
+        // so a resize repaint reproduces the same figures rather than re-rolling
+        // pose cycles every time (mirrors comic-view.ts's `stage`/`frozen`).
+        const cycles = new Map();
+        for (const panel of this.#doc.panels) {
+            selectFigures(panel, cast, cycles);
+            this.#frozen.set(panel, copyCycles(cycles));
+        }
+        this.#size = this.#measure();
+        this.#visibilityObserver = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                const slot = this.#slots.find((s) => s.canvas === entry.target);
+                if (!slot)
+                    continue;
+                if (entry.isIntersecting)
+                    this.#paint(slot);
+                else
+                    this.#release(slot);
+            }
+        }, 
+        // No internal scroll pane here (unlike the source app's fixed-height
+        // strip) — this element assumes the host page scrolls, so visibility is
+        // relative to the viewport (root: null), not a container this owns.
+        { root: null, rootMargin: "100% 0px" });
+        for (const panel of this.#doc.panels) {
+            const canvas = document.createElement("canvas");
+            canvas.className = "panel";
+            canvas.setAttribute("role", "img");
+            canvas.setAttribute("aria-label", describePanel(panel));
+            canvas.width = 0;
+            canvas.height = 0;
+            const slot = { canvas, panel, painted: false };
+            this.#resizeSlot(slot);
+            this.#strip.append(canvas);
+            this.#slots.push(slot);
+            this.#visibilityObserver.observe(canvas);
+        }
+    }
+    #measure() {
+        const style = getComputedStyle(this);
+        const inner = (this.clientWidth || this.getBoundingClientRect().width) -
+            parseFloat(style.paddingLeft || "0") -
+            parseFloat(style.paddingRight || "0");
+        const layout = layoutStrip(inner, { gutter: GUTTER });
+        this.#strip.style.gridTemplateColumns = `repeat(${layout.columns}, ${layout.panelWidth}px)`;
+        this.#columns = layout.columns;
+        return { width: layout.panelWidth, height: layout.panelHeight };
+    }
+    #resizeSlot(slot) {
+        slot.canvas.style.width = `${this.#size.width}px`;
+        slot.canvas.style.height = `${this.#size.height}px`;
+    }
+    #paint(slot) {
+        if (!this.#cast || slot.painted)
+            return;
+        const ratio = window.devicePixelRatio || 1;
+        const { width, height } = this.#size;
+        slot.canvas.width = Math.round(width * ratio);
+        slot.canvas.height = Math.round(height * ratio);
+        const ctx = slot.canvas.getContext("2d");
+        if (!ctx)
+            return;
+        ctx.setTransform(ratio, 0, 0, ratio, 0, 0);
+        renderPanel(ctx, slot.panel, this.#cast, width, height, {
+            cycles: copyCycles(this.#frozen.get(slot.panel) ?? new Map()),
+        });
+        slot.painted = true;
+    }
+    #release(slot) {
+        if (!slot.painted)
+            return;
+        slot.canvas.width = 0;
+        slot.canvas.height = 0;
+        slot.painted = false;
+    }
+    #relayout() {
+        if (!this.#cast)
+            return;
+        this.#size = this.#measure();
+        for (const slot of this.#slots) {
+            this.#resizeSlot(slot);
+            if (slot.painted) {
+                slot.painted = false;
+                this.#paint(slot);
+            }
+        }
+    }
+    /** Column count as of the last layout pass — exposed for tests/consumers. */
+    get columns() {
+        return this.#columns;
+    }
+}
+export function registerComicStripElement(tagName = "comic-strip") {
+    if (!customElements.get(tagName))
+        customElements.define(tagName, ComicStripElement);
+}

package/dist/describe.d.ts

@@ -0,0 +1,7 @@
+import type { Panel } from "@toonstrip/schema";
+/**
+ * Alt text for a panel's canvas — a screen reader (or a search engine) gets
+ * this whether or not the panel is currently painted. Generic over the
+ * document's own `speaker`/`text` fields; no game- or role-specific labels.
+ */
+export declare function describePanel(panel: Panel): string;

package/dist/describe.js

@@ -0,0 +1,21 @@
+/**
+ * Alt text for a panel's canvas — a screen reader (or a search engine) gets
+ * this whether or not the panel is currently painted. Generic over the
+ * document's own `speaker`/`text` fields; no game- or role-specific labels.
+ */
+export function describePanel(panel) {
+    const parts = [`${panel.camera ?? "medium"} shot`];
+    if (panel.roomTitle)
+        parts.push(panel.roomTitle);
+    for (const line of panel.speakers) {
+        if (line.speaker === "caption") {
+            parts.push(`caption: ${line.text}`);
+            continue;
+        }
+        const verb = line.balloon === "thought" ? "thinks" : "says";
+        parts.push(`${line.speaker} ${verb} "${line.text}"`);
+    }
+    if (parts.length === 1)
+        parts.push("no dialogue");
+    return parts.join("; ");
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ComicStripElement, registerComicStripElement } from "./comic-strip-element.js";
+export { describePanel } from "./describe.js";
+export { loadCastFromPacks } from "./load-pack.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { ComicStripElement, registerComicStripElement } from "./comic-strip-element.js";
+export { describePanel } from "./describe.js";
+export { loadCastFromPacks } from "./load-pack.js";
+import { registerComicStripElement } from "./comic-strip-element.js";
+registerComicStripElement();

package/dist/load-pack.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser-side counterpart to `@toonstrip/pack-comic-chat`'s `loadCastManifest`
+ * (fs-based, Node-only). A pack here is a URL — `pack.json` plus the
+ * character/backdrop files it points at, fetched over HTTP rather than read
+ * off disk — assembling the same `Cast` shape `@toonstrip/core`'s `renderPanel`
+ * consumes either way (see NOTES.md "M3": this loader is new work, not a port).
+ */
+import type { Cast } from "@toonstrip/core";
+/**
+ * Loads exactly the characters/backdrops a document needs from a list of
+ * registered pack base URLs. Per the dev plan §6, an id declared by more than
+ * one registered pack is a hard error, not a silent first-match — collisions
+ * are a pack-authoring mistake the caller needs to know about immediately.
+ */
+export declare function loadCastFromPacks(packBaseUrls: readonly string[], characterIds: readonly string[], backdropIds: readonly string[]): Promise<Cast>;

package/dist/load-pack.js

@@ -0,0 +1,75 @@
+/** Resolves `path` against `baseUrl`; `baseUrl` may itself be relative (e.g. "/packs/comic-chat/"). */
+function resolveUrl(baseUrl, path) {
+    const withSlash = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    const absoluteBase = new URL(withSlash, document.baseURI);
+    return new URL(path, absoluteBase).toString();
+}
+async function fetchJson(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`fetch ${url} failed: ${res.status} ${res.statusText}`);
+    return (await res.json());
+}
+function loadImage(url) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.crossOrigin = "anonymous";
+        img.onload = () => resolve(img);
+        img.onerror = () => reject(new Error(`failed to load image ${url}`));
+        img.src = url;
+    });
+}
+/**
+ * Loads exactly the characters/backdrops a document needs from a list of
+ * registered pack base URLs. Per the dev plan §6, an id declared by more than
+ * one registered pack is a hard error, not a silent first-match — collisions
+ * are a pack-authoring mistake the caller needs to know about immediately.
+ */
+export async function loadCastFromPacks(packBaseUrls, characterIds, backdropIds) {
+    if (packBaseUrls.length === 0 && (characterIds.length > 0 || backdropIds.length > 0)) {
+        throw new Error("comic-strip: document references characters/backdrops but no packs are registered (set .packs)");
+    }
+    const packs = await Promise.all(packBaseUrls.map(async (baseUrl) => ({
+        baseUrl,
+        json: await fetchJson(resolveUrl(baseUrl, "pack.json")),
+    })));
+    const cast = {};
+    const sheets = new Map();
+    for (const id of characterIds) {
+        const matches = packs
+            .map((pack) => ({ pack, entry: pack.json.characters.find((c) => c.id === id) }))
+            .filter((m) => !!m.entry);
+        if (matches.length === 0) {
+            throw new Error(`comic-strip: no registered pack declares character "${id}"`);
+        }
+        if (matches.length > 1) {
+            throw new Error(`comic-strip: character "${id}" is declared by more than one registered pack ` +
+                `(${matches.map((m) => m.pack.baseUrl).join(", ")})`);
+        }
+        const { pack, entry } = matches[0];
+        const avatar = await fetchJson(resolveUrl(pack.baseUrl, entry.manifest));
+        const sheetUrl = resolveUrl(pack.baseUrl, entry.sheet);
+        cast[id] = { ...avatar, sheet: sheetUrl };
+        sheets.set(id, await loadImage(sheetUrl));
+    }
+    const backdrops = new Map();
+    const backdropEntries = [];
+    for (const id of backdropIds) {
+        const matches = packs
+            .map((pack) => ({ pack, entry: pack.json.backdrops.find((b) => b.id === id) }))
+            .filter((m) => !!m.entry);
+        if (matches.length === 0) {
+            throw new Error(`comic-strip: no registered pack declares backdrop "${id}"`);
+        }
+        if (matches.length > 1) {
+            throw new Error(`comic-strip: backdrop "${id}" is declared by more than one registered pack ` +
+                `(${matches.map((m) => m.pack.baseUrl).join(", ")})`);
+        }
+        const { pack, entry } = matches[0];
+        const fileUrl = resolveUrl(pack.baseUrl, entry.file);
+        backdropEntries.push({ ...entry, file: fileUrl });
+        backdrops.set(id, await loadImage(fileUrl));
+    }
+    const manifest = { version: 1, cast, backdrops: backdropEntries };
+    return { manifest, sheets, backdrops };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@toonstrip/element",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "verify:demo": "node scripts/verify-demo.mjs"
+  },
+  "dependencies": {
+    "@toonstrip/core": "workspace:*",
+    "@toonstrip/schema": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4",
+    "jsdom": "^25.0.1",
+    "playwright": "^1.48.0",
+    "axe-core": "^4.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}