@plotwork.official/viewer 0.0.0-stage → 0.1.1

package/dist/element/plotwork-diagram.js

@@ -0,0 +1,397 @@
+import { clampView, dotGridStyle, fitView, isFitView, middleOf, percentOf, zoomAt } from '../core/canvas-view.js';
+import { fingerprintOf, isFingerprint } from '../core/fingerprint.js';
+import { VIEWER_ZOOM_STEP } from '../core/limits.js';
+import { documentHost, liveIntervalOf, watchLive } from '../core/live-watch.js';
+import { drillNodeAt, nodeAt, parsePicture, traceMapOf, traceOf } from '../core/picture-map.js';
+import { loadPicture, pictureUrl, PictureLoadError } from '../core/picture-loader.js';
+import { drawnScheme, themeChoiceOf, withScheme } from '../core/picture-scheme.js';
+import { readEmbeddedSource } from '../core/picture-source.js';
+import { mergeLabels } from './copy.js';
+import { emit } from './events.js';
+import { attachGestures } from './gestures.js';
+import { buildShell } from './shell.js';
+import { place, traceLayer } from './trace-layer.js';
+/** The attributes the element reads. */
+export const OBSERVED_ATTRIBUTES = ['src', 'theme', 'live', 'interval', 'fingerprint', 'wheel', 'label'];
+/** The element's class, made on first use so that importing the package where there is no `HTMLElement` (a server render) is safe. */
+export function createPlotworkDiagramClass() {
+    return class PlotworkDiagram extends HTMLElement {
+        static get observedAttributes() {
+            return OBSERVED_ATTRIBUTES;
+        }
+        #shell;
+        #labels = mergeLabels(undefined);
+        #ownLabels;
+        #svg = null;
+        #text = null;
+        #fingerprint = null;
+        #map = null;
+        #size = null;
+        #view = { scale: 1, x: 0, y: 0 };
+        /** The canvas the view was last set for, and whether the picture is still to be fitted once the canvas has a size. */
+        #viewport = null;
+        #pendingFit = true;
+        #blob = null;
+        #traced = null;
+        #layer = null;
+        #loading = null;
+        #stopLive = null;
+        #cleanup = [];
+        #hintTimer;
+        constructor() {
+            super();
+            this.#shell = buildShell(this.attachShadow({ mode: 'open' }), this.#labels);
+        }
+        connectedCallback() {
+            /* A property set before the element was defined sits on the instance and hides the accessor: move it onto the accessor. */
+            for (const name of ['labels', 'svg']) {
+                if (!Object.hasOwn(this, name))
+                    continue;
+                const value = this[name];
+                delete this[name];
+                this[name] = value;
+            }
+            const { canvas, zoomIn, zoomOut, fit, fullscreen } = this.#shell;
+            this.#cleanup.push(attachGestures(canvas, {
+                view: () => this.#view,
+                setView: (view, glide) => this.#setView(view, glide),
+                sizes: () => this.#sizes(),
+                wheelMode: () => this.#wheelMode(),
+                hover: (point) => this.#hover(point),
+                press: (point) => this.#press(point),
+                hintWheel: () => this.#hintWheel(),
+                fit: () => this.fit(),
+                release: () => this.#trace(null),
+            }));
+            const on = (target, type, listener) => {
+                target.addEventListener(type, listener);
+                this.#cleanup.push(() => target.removeEventListener(type, listener));
+            };
+            on(zoomIn, 'click', () => this.zoomIn());
+            on(zoomOut, 'click', () => this.zoomOut());
+            on(fit, 'click', () => this.fit());
+            on(fullscreen, 'click', () => void this.#toggleFullscreen());
+            on(document, 'fullscreenchange', () => this.#syncFullscreen());
+            const resize = new ResizeObserver(() => this.#resized());
+            resize.observe(canvas);
+            this.#cleanup.push(() => resize.disconnect());
+            const dark = matchMedia('(prefers-color-scheme: dark)');
+            on(dark, 'change', () => this.#paintPaper());
+            void this.#refresh();
+        }
+        disconnectedCallback() {
+            for (const undo of this.#cleanup.splice(0))
+                undo();
+            this.#loading?.abort();
+            this.#stopWatching();
+            clearTimeout(this.#hintTimer);
+        }
+        attributeChangedCallback(name, before, after) {
+            if (before === after || !this.isConnected)
+                return;
+            if (name === 'label')
+                this.#describe();
+            else if (name === 'wheel')
+                return;
+            else if (name === 'theme' && this.#text !== null)
+                this.#paintPicture(this.#text);
+            else if (name === 'live' || name === 'interval')
+                this.#watch();
+            else
+                void this.#refresh();
+        }
+        get svg() {
+            return this.#svg;
+        }
+        set svg(value) {
+            this.#svg = typeof value === 'string' && value !== '' ? value : null;
+            if (this.isConnected)
+                void this.#refresh();
+        }
+        get labels() {
+            return this.#ownLabels;
+        }
+        set labels(value) {
+            this.#ownLabels = value;
+            this.#labels = mergeLabels(value);
+            const { zoomIn, zoomOut, fit, hint } = this.#shell;
+            for (const [button, label] of [[zoomIn, this.#labels.zoomIn], [zoomOut, this.#labels.zoomOut], [fit, this.#labels.fit]]) {
+                button.setAttribute('aria-label', label);
+                button.title = label;
+            }
+            hint.textContent = this.#labels.wheelHint;
+            this.#syncFullscreen();
+            this.#describe();
+        }
+        get fingerprint() {
+            return this.#fingerprint;
+        }
+        source() {
+            if (this.#text === null)
+                return null;
+            const reading = readEmbeddedSource(this.#text);
+            return reading.status === 'found' ? reading.source : null;
+        }
+        fit() {
+            const sizes = this.#sizes();
+            if (sizes === null)
+                return;
+            this.#pendingFit = false;
+            this.#setView(fitView(sizes.viewport, sizes.picture), true);
+        }
+        zoomIn() {
+            this.#zoomBy(VIEWER_ZOOM_STEP);
+        }
+        zoomOut() {
+            this.#zoomBy(1 / VIEWER_ZOOM_STEP);
+        }
+        async reload() {
+            await this.#refresh(true);
+        }
+        /* Loading. */
+        async #refresh(revalidate = false) {
+            this.#loading?.abort();
+            const loading = new AbortController();
+            this.#loading = loading;
+            try {
+                const text = this.#svg ?? (await this.#fetch(loading.signal, revalidate));
+                if (loading.signal.aborted)
+                    return;
+                if (text === null)
+                    return this.#fail('empty');
+                await this.#show(text, revalidate && this.#fingerprint !== null);
+            }
+            catch (error) {
+                if (!loading.signal.aborted)
+                    this.#fail(error instanceof PictureLoadError ? error.reason : 'network');
+            }
+            this.#watch();
+        }
+        async #fetch(signal, revalidate) {
+            const src = this.getAttribute('src');
+            if (src === null || src.trim() === '')
+                return null;
+            const url = pictureUrl(src, document.baseURI);
+            if (url === null)
+                throw new PictureLoadError('address');
+            return loadPicture(url, { signal, revalidate });
+        }
+        /** Shows a picture's text. An update keeps the view when the picture is the same size; a first showing fits it. */
+        async #show(text, update) {
+            const fingerprint = await fingerprintOf(text);
+            const pinned = this.getAttribute('fingerprint');
+            if (pinned !== null && isFingerprint(pinned) && pinned !== fingerprint)
+                throw new PictureLoadError('fingerprint');
+            if (update && fingerprint === this.#fingerprint)
+                return;
+            const root = parsePicture(text);
+            const map = root === null ? null : traceMapOf(root);
+            if (map === null)
+                throw new PictureLoadError('not-a-picture');
+            const previous = this.#fingerprint;
+            const size = { width: map.viewBox.width, height: map.viewBox.height };
+            const sameSize = this.#size !== null && this.#size.width === size.width && this.#size.height === size.height;
+            this.#text = text;
+            this.#fingerprint = fingerprint;
+            this.#map = map;
+            this.#size = size;
+            this.#traced = null;
+            this.#paintPicture(text);
+            const { picture, canvas, notice, toolbar } = this.#shell;
+            picture.hidden = false;
+            notice.hidden = true;
+            toolbar.hidden = false;
+            canvas.setAttribute('aria-busy', 'false');
+            this.#describe();
+            const sizes = this.#sizes();
+            this.#pendingFit = !(update && sameSize);
+            if (sizes === null)
+                return void this.#announceShown(update, previous, fingerprint, text);
+            if (this.#pendingFit)
+                this.fit();
+            else
+                this.#setView(clampView(this.#view, sizes.viewport, sizes.picture));
+            this.#drawTrace();
+            this.#announceShown(update, previous, fingerprint, text);
+        }
+        #announceShown(update, previous, fingerprint, text) {
+            if (update && previous !== null) {
+                this.#say(this.#labels.updated);
+                emit(this, 'plotwork-change', { fingerprint, previous });
+            }
+            else
+                emit(this, 'plotwork-load', { fingerprint, hasSource: readEmbeddedSource(text).status === 'found' });
+        }
+        /** Points the `img` at the picture in the scheme asked for, and paints the paper to match. */
+        #paintPicture(text) {
+            this.#paintPaper();
+            const blob = URL.createObjectURL(new Blob([withScheme(text, themeChoiceOf(this.getAttribute('theme')))], { type: 'image/svg+xml' }));
+            this.#shell.picture.src = blob;
+            if (this.#blob !== null)
+                URL.revokeObjectURL(this.#blob);
+            this.#blob = blob;
+        }
+        #fail(reason) {
+            const { picture, notice, toolbar, canvas } = this.#shell;
+            this.#text = null;
+            this.#fingerprint = null;
+            this.#map = null;
+            this.#size = null;
+            picture.hidden = true;
+            picture.removeAttribute('src');
+            if (this.#blob !== null)
+                URL.revokeObjectURL(this.#blob);
+            this.#blob = null;
+            notice.textContent = this.#labels.failed[reason];
+            notice.hidden = false;
+            toolbar.hidden = true;
+            canvas.setAttribute('aria-busy', 'false');
+            this.#drawTrace();
+            emit(this, 'plotwork-error', { reason });
+        }
+        /** Watches a live picture: only with `live`, a `src`, a picture shown, and no pinned fingerprint. */
+        #watch() {
+            this.#stopWatching();
+            if (!this.hasAttribute('live') || this.#svg !== null || this.hasAttribute('fingerprint') || this.#fingerprint === null)
+                return;
+            this.#stopLive = watchLive(documentHost(document), liveIntervalOf(this.getAttribute('interval')), async () => {
+                const text = await this.#fetch(new AbortController().signal, true);
+                if (text !== null)
+                    await this.#show(text, true);
+            });
+        }
+        #stopWatching() {
+            this.#stopLive?.();
+            this.#stopLive = null;
+        }
+        /* The canvas. */
+        #sizes() {
+            if (this.#size === null)
+                return null;
+            const { clientWidth: width, clientHeight: height } = this.#shell.canvas;
+            return width > 0 && height > 0 ? { viewport: { width, height }, picture: this.#size } : null;
+        }
+        #wheelMode() {
+            return document.fullscreenElement === this || this.getAttribute('wheel') === 'zoom' ? 'zoom' : 'modifier';
+        }
+        #setView(view, glide = false) {
+            this.#view = view;
+            this.#viewport = this.#sizes()?.viewport ?? this.#viewport;
+            const { picture, zoomLevel } = this.#shell;
+            for (const element of [picture, this.#layer]) {
+                if (element === null || this.#size === null)
+                    continue;
+                element.toggleAttribute('data-glide', glide);
+                place(element, this.#size, view);
+            }
+            zoomLevel.value = this.#labels.zoomLevel(percentOf(view.scale));
+            const grid = dotGridStyle(view);
+            this.#shell.canvas.style.backgroundSize = grid.backgroundSize;
+            this.#shell.canvas.style.backgroundPosition = grid.backgroundPosition;
+        }
+        #zoomBy(factor) {
+            const sizes = this.#sizes();
+            if (sizes !== null)
+                this.#setView(zoomAt(this.#view, middleOf(sizes.viewport), this.#view.scale * factor, sizes.viewport, sizes.picture), true);
+        }
+        #resized() {
+            const sizes = this.#sizes();
+            if (sizes === null)
+                return;
+            const wasFitted = this.#viewport !== null && isFitView(this.#view, this.#viewport, sizes.picture);
+            if (this.#pendingFit || wasFitted) {
+                this.#pendingFit = false;
+                this.#setView(fitView(sizes.viewport, sizes.picture));
+            }
+            else
+                this.#setView(clampView(this.#view, sizes.viewport, sizes.picture));
+        }
+        /** A canvas point in the picture's own units. */
+        #toPicture(point) {
+            if (this.#map === null)
+                return null;
+            return { x: (point.x - this.#view.x) / this.#view.scale + this.#map.viewBox.x, y: (point.y - this.#view.y) / this.#view.scale + this.#map.viewBox.y };
+        }
+        #hover(point) {
+            const at = point === null ? null : this.#toPicture(point);
+            const map = this.#map;
+            this.#shell.canvas.toggleAttribute('data-drill', at !== null && map !== null && drillNodeAt(map, at) !== null);
+            if (this.#traced?.pinned === true)
+                return;
+            this.#trace(at === null || map === null ? null : (nodeAt(map, at)?.id ?? null), false);
+        }
+        #press(point) {
+            const at = this.#toPicture(point);
+            const map = this.#map;
+            if (at === null || map === null)
+                return;
+            const drill = drillNodeAt(map, at);
+            if (drill?.part !== undefined) {
+                emit(this, 'plotwork-drill', { id: drill.id, part: drill.part, name: drill.name });
+                this.#say(this.#labels.drill(drill.name));
+                return;
+            }
+            const node = nodeAt(map, at);
+            if (node === null || (this.#traced?.pinned === true && this.#traced.id === node.id))
+                this.#trace(null);
+            else
+                this.#trace(node.id, true);
+        }
+        #trace(id, pinned = false) {
+            if ((this.#traced?.id ?? null) === id && (this.#traced?.pinned ?? false) === pinned)
+                return;
+            this.#traced = id === null ? null : { id, pinned };
+            this.#drawTrace();
+            emit(this, 'plotwork-trace', { id });
+        }
+        #drawTrace() {
+            this.#layer?.remove();
+            this.#layer = null;
+            const trace = this.#traced === null || this.#map === null ? null : traceOf(this.#map, this.#traced.id);
+            if (trace === null || this.#map === null || this.#size === null)
+                return;
+            this.#layer = traceLayer(this.#map, trace);
+            place(this.#layer, this.#size, this.#view);
+            this.#shell.canvas.append(this.#layer);
+            if (this.#traced?.pinned === true)
+                this.#say(this.#labels.traced(trace.node.name, trace.lines.length));
+        }
+        /* Everything else the element shows. */
+        /** The paper behind the picture: the scheme it was drawn in, else the one asked for, else the page's. */
+        #paintPaper() {
+            const choice = themeChoiceOf(this.getAttribute('theme'));
+            const drawn = this.#text === null ? null : drawnScheme(this.#text);
+            const paper = drawn ?? (choice === 'auto' ? (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : choice);
+            this.setAttribute('data-paper', paper);
+        }
+        #describe() {
+            const label = this.getAttribute('label');
+            this.#shell.canvas.setAttribute('aria-label', label === null || label.trim() === '' ? this.#labels.canvas : `${label}. ${this.#labels.canvas}`);
+        }
+        #say(text) {
+            this.#shell.live.textContent = text;
+        }
+        #hintWheel() {
+            const { hint } = this.#shell;
+            hint.setAttribute('data-shown', '');
+            clearTimeout(this.#hintTimer);
+            this.#hintTimer = setTimeout(() => hint.removeAttribute('data-shown'), 1500);
+        }
+        async #toggleFullscreen() {
+            try {
+                if (document.fullscreenElement === this)
+                    await document.exitFullscreen();
+                else
+                    await this.requestFullscreen();
+            }
+            catch {
+                // Full screen refused (an iframe without permission): the button simply does nothing.
+            }
+        }
+        #syncFullscreen() {
+            const label = document.fullscreenElement === this ? this.#labels.exitFullscreen : this.#labels.fullscreen;
+            this.#shell.fullscreen.setAttribute('aria-label', label);
+            this.#shell.fullscreen.title = label;
+        }
+    };
+}

package/dist/element/shell.d.ts

@@ -0,0 +1,22 @@
+import type { ViewerLabels } from './copy.js';
+/**
+ * The element's shadow tree: the stage, the canvas the picture moves on, the picture as an `img`, the toolbar, the notice for a
+ * picture that cannot be shown, the wheel hint, and a polite live region. Built once when the element is made; the element changes
+ * attributes and text on these nodes and never rebuilds them.
+ */
+export interface Shell {
+    stage: HTMLDivElement;
+    canvas: HTMLDivElement;
+    picture: HTMLImageElement;
+    toolbar: HTMLDivElement;
+    zoomOut: HTMLButtonElement;
+    zoomIn: HTMLButtonElement;
+    zoomLevel: HTMLOutputElement;
+    fit: HTMLButtonElement;
+    fullscreen: HTMLButtonElement;
+    notice: HTMLParagraphElement;
+    hint: HTMLParagraphElement;
+    live: HTMLDivElement;
+}
+/** Builds the shadow tree into a shadow root. */
+export declare function buildShell(root: ShadowRoot, labels: ViewerLabels): Shell;

package/dist/element/shell.js

@@ -0,0 +1,30 @@
+import { html, icon } from './dom.js';
+import { VIEWER_CSS } from './styles.js';
+const ICONS = {
+    zoomOut: ['M5 10h10'],
+    zoomIn: ['M5 10h10', 'M10 5v10'],
+    fit: ['M4 8V4h4', 'M12 4h4v4', 'M16 12v4h-4', 'M8 16H4v-4'],
+    fullscreen: ['M3 7V3h4', 'M13 3h4v4', 'M17 13v4h-4', 'M7 17H3v-4', 'M7 7h6v6H7z'],
+};
+function button(label, paths) {
+    return html('button', { type: 'button', part: 'button', 'aria-label': label, title: label }, icon(paths));
+}
+/** Builds the shadow tree into a shadow root. */
+export function buildShell(root, labels) {
+    const style = html('style');
+    style.textContent = VIEWER_CSS;
+    const picture = html('img', { class: 'picture', alt: '', draggable: 'false', decoding: 'async' });
+    const canvas = html('div', { class: 'canvas', part: 'canvas', tabindex: 0, role: 'img', 'aria-roledescription': 'diagram', 'aria-busy': 'true' }, picture);
+    const zoomOut = button(labels.zoomOut, ICONS.zoomOut);
+    const zoomIn = button(labels.zoomIn, ICONS.zoomIn);
+    const zoomLevel = html('output', { 'aria-hidden': 'true' });
+    const fit = button(labels.fit, ICONS.fit);
+    const fullscreen = button(labels.fullscreen, ICONS.fullscreen);
+    const toolbar = html('div', { class: 'toolbar', part: 'toolbar', role: 'toolbar', hidden: '' }, zoomOut, zoomLevel, zoomIn, fit, fullscreen);
+    const notice = html('p', { class: 'notice', part: 'notice', role: 'status' }, labels.loading);
+    const hint = html('p', { class: 'hint', 'aria-hidden': 'true' }, labels.wheelHint);
+    const live = html('div', { class: 'live', 'aria-live': 'polite' });
+    const stage = html('div', { class: 'stage', part: 'stage' }, canvas, toolbar, notice, hint, live);
+    root.append(style, stage);
+    return { stage, canvas, picture, toolbar, zoomOut, zoomIn, zoomLevel, fit, fullscreen, notice, hint, live };
+}

package/dist/element/styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The element's style sheet, inside its shadow root, so a page's CSS never reaches in and the element's never leaks out. A page
+ * themes it through the custom properties on `:host` (`--plotwork-paper`, `--plotwork-ink`, `--plotwork-trace`, `--plotwork-radius`,
+ * `--plotwork-font`, `--plotwork-height`) and styles the parts named with `part` (`stage`, `canvas`, `toolbar`, `button`, `notice`).
+ */
+export declare const VIEWER_CSS = "\n:host {\n  --plotwork-paper: #f4f4f1;\n  --plotwork-ink: #52514e;\n  --plotwork-trace: #0f766e;\n  --plotwork-control: #ffffff;\n  --plotwork-border: color-mix(in srgb, var(--plotwork-ink) 18%, transparent);\n  --plotwork-dot: color-mix(in srgb, var(--plotwork-ink) 22%, transparent);\n  --plotwork-radius: 10px;\n  --plotwork-font: system-ui, -apple-system, 'Segoe UI', sans-serif;\n  --plotwork-height: 480px;\n  display: block;\n  position: relative;\n  block-size: var(--plotwork-height);\n  min-block-size: 200px;\n  color-scheme: light dark;\n  font-family: var(--plotwork-font);\n  color: var(--plotwork-ink);\n}\n:host([hidden]) { display: none; }\n:host([theme='light']) { color-scheme: light; }\n:host([theme='dark']) { color-scheme: dark; }\n:host([data-paper='dark']) {\n  --plotwork-paper: #171716;\n  --plotwork-ink: #c3c2b7;\n  --plotwork-trace: #2dd4bf;\n  --plotwork-control: #262624;\n  --plotwork-dot: color-mix(in srgb, var(--plotwork-ink) 16%, transparent);\n}\n.stage {\n  position: absolute;\n  inset: 0;\n  overflow: hidden;\n  border: 1px solid var(--plotwork-border);\n  border-radius: var(--plotwork-radius);\n  background: var(--plotwork-paper);\n}\n.canvas {\n  position: absolute;\n  inset: 0;\n  overflow: hidden;\n  touch-action: none;\n  cursor: grab;\n  background-image: radial-gradient(circle, var(--plotwork-dot) 0.9px, transparent 1.4px);\n  outline: none;\n}\n.canvas:focus-visible { box-shadow: inset 0 0 0 2px var(--plotwork-trace); border-radius: var(--plotwork-radius); }\n.canvas[data-dragging] { cursor: grabbing; }\n.canvas[data-drill] { cursor: pointer; }\n.picture, .trace {\n  position: absolute;\n  inset: 0 auto auto 0;\n  display: block;\n  max-inline-size: none;\n  transform-origin: 0 0;\n  user-select: none;\n  -webkit-user-drag: none;\n  pointer-events: none;\n}\n.trace { overflow: visible; }\n.trace .veil { fill: color-mix(in srgb, var(--plotwork-paper) 62%, transparent); }\n.trace .halo, .trace .stroke, .trace .ribbon, .trace .end, .trace .label, .trace .chosen {\n  vector-effect: non-scaling-stroke;\n  stroke-linecap: round;\n  stroke-linejoin: round;\n}\n.trace .halo { fill: none; stroke: var(--plotwork-paper); stroke-width: 6; }\n.trace .stroke { fill: none; stroke: var(--plotwork-trace); stroke-width: 2.5; }\n.trace .ribbon { fill: color-mix(in srgb, var(--plotwork-trace) 30%, transparent); stroke: var(--plotwork-trace); stroke-width: 1.5; }\n.trace .end, .trace .label { fill: none; stroke: var(--plotwork-trace); stroke-width: 1.5; }\n.trace .chosen { fill: none; stroke: var(--plotwork-trace); stroke-width: 3; }\n.toolbar {\n  position: absolute;\n  inset: auto 12px 12px auto;\n  display: flex;\n  align-items: center;\n  gap: 2px;\n  padding: 4px;\n  border: 1px solid var(--plotwork-border);\n  border-radius: 999px;\n  background: var(--plotwork-control);\n  box-shadow: 0 1px 3px rgb(0 0 0 / 0.12);\n}\n:host([controls='none']) .toolbar { display: none; }\n.toolbar button {\n  display: inline-grid;\n  place-items: center;\n  inline-size: 32px;\n  block-size: 32px;\n  padding: 0;\n  border: 0;\n  border-radius: 999px;\n  background: transparent;\n  color: inherit;\n  cursor: pointer;\n}\n.toolbar button:hover { background: color-mix(in srgb, var(--plotwork-ink) 10%, transparent); }\n.toolbar button:focus-visible { outline: 2px solid var(--plotwork-trace); outline-offset: 1px; }\n.toolbar svg path { fill: none; stroke: currentColor; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; }\n.toolbar output { min-inline-size: 3.5em; font-size: 12px; font-variant-numeric: tabular-nums; text-align: center; }\n.notice, .hint {\n  position: absolute;\n  inset: 50% auto auto 50%;\n  transform: translate(-50%, -50%);\n  margin: 0;\n  max-inline-size: min(36ch, 90%);\n  text-align: center;\n  font-size: 14px;\n}\n.hint {\n  padding: 6px 12px;\n  border-radius: 999px;\n  background: rgb(23 23 22 / 0.86);\n  color: #f4f4f1;\n  pointer-events: none;\n  opacity: 0;\n}\n.hint[data-shown] { opacity: 1; }\n.notice[hidden], .hint[hidden], .toolbar[hidden] { display: none; }\n.live {\n  position: absolute;\n  inline-size: 1px;\n  block-size: 1px;\n  overflow: hidden;\n  clip-path: inset(50%);\n  white-space: nowrap;\n}\n@media (prefers-reduced-motion: no-preference) {\n  .picture[data-glide], .trace[data-glide] { transition: transform 160ms ease-out, width 160ms ease-out, height 160ms ease-out; }\n  .hint { transition: opacity 200ms ease-out; }\n}\n";

package/dist/element/styles.js

@@ -0,0 +1,137 @@
+/**
+ * The element's style sheet, inside its shadow root, so a page's CSS never reaches in and the element's never leaks out. A page
+ * themes it through the custom properties on `:host` (`--plotwork-paper`, `--plotwork-ink`, `--plotwork-trace`, `--plotwork-radius`,
+ * `--plotwork-font`, `--plotwork-height`) and styles the parts named with `part` (`stage`, `canvas`, `toolbar`, `button`, `notice`).
+ */
+export const VIEWER_CSS = `
+:host {
+  --plotwork-paper: #f4f4f1;
+  --plotwork-ink: #52514e;
+  --plotwork-trace: #0f766e;
+  --plotwork-control: #ffffff;
+  --plotwork-border: color-mix(in srgb, var(--plotwork-ink) 18%, transparent);
+  --plotwork-dot: color-mix(in srgb, var(--plotwork-ink) 22%, transparent);
+  --plotwork-radius: 10px;
+  --plotwork-font: system-ui, -apple-system, 'Segoe UI', sans-serif;
+  --plotwork-height: 480px;
+  display: block;
+  position: relative;
+  block-size: var(--plotwork-height);
+  min-block-size: 200px;
+  color-scheme: light dark;
+  font-family: var(--plotwork-font);
+  color: var(--plotwork-ink);
+}
+:host([hidden]) { display: none; }
+:host([theme='light']) { color-scheme: light; }
+:host([theme='dark']) { color-scheme: dark; }
+:host([data-paper='dark']) {
+  --plotwork-paper: #171716;
+  --plotwork-ink: #c3c2b7;
+  --plotwork-trace: #2dd4bf;
+  --plotwork-control: #262624;
+  --plotwork-dot: color-mix(in srgb, var(--plotwork-ink) 16%, transparent);
+}
+.stage {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  border: 1px solid var(--plotwork-border);
+  border-radius: var(--plotwork-radius);
+  background: var(--plotwork-paper);
+}
+.canvas {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  touch-action: none;
+  cursor: grab;
+  background-image: radial-gradient(circle, var(--plotwork-dot) 0.9px, transparent 1.4px);
+  outline: none;
+}
+.canvas:focus-visible { box-shadow: inset 0 0 0 2px var(--plotwork-trace); border-radius: var(--plotwork-radius); }
+.canvas[data-dragging] { cursor: grabbing; }
+.canvas[data-drill] { cursor: pointer; }
+.picture, .trace {
+  position: absolute;
+  inset: 0 auto auto 0;
+  display: block;
+  max-inline-size: none;
+  transform-origin: 0 0;
+  user-select: none;
+  -webkit-user-drag: none;
+  pointer-events: none;
+}
+.trace { overflow: visible; }
+.trace .veil { fill: color-mix(in srgb, var(--plotwork-paper) 62%, transparent); }
+.trace .halo, .trace .stroke, .trace .ribbon, .trace .end, .trace .label, .trace .chosen {
+  vector-effect: non-scaling-stroke;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+.trace .halo { fill: none; stroke: var(--plotwork-paper); stroke-width: 6; }
+.trace .stroke { fill: none; stroke: var(--plotwork-trace); stroke-width: 2.5; }
+.trace .ribbon { fill: color-mix(in srgb, var(--plotwork-trace) 30%, transparent); stroke: var(--plotwork-trace); stroke-width: 1.5; }
+.trace .end, .trace .label { fill: none; stroke: var(--plotwork-trace); stroke-width: 1.5; }
+.trace .chosen { fill: none; stroke: var(--plotwork-trace); stroke-width: 3; }
+.toolbar {
+  position: absolute;
+  inset: auto 12px 12px auto;
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 4px;
+  border: 1px solid var(--plotwork-border);
+  border-radius: 999px;
+  background: var(--plotwork-control);
+  box-shadow: 0 1px 3px rgb(0 0 0 / 0.12);
+}
+:host([controls='none']) .toolbar { display: none; }
+.toolbar button {
+  display: inline-grid;
+  place-items: center;
+  inline-size: 32px;
+  block-size: 32px;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+.toolbar button:hover { background: color-mix(in srgb, var(--plotwork-ink) 10%, transparent); }
+.toolbar button:focus-visible { outline: 2px solid var(--plotwork-trace); outline-offset: 1px; }
+.toolbar svg path { fill: none; stroke: currentColor; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; }
+.toolbar output { min-inline-size: 3.5em; font-size: 12px; font-variant-numeric: tabular-nums; text-align: center; }
+.notice, .hint {
+  position: absolute;
+  inset: 50% auto auto 50%;
+  transform: translate(-50%, -50%);
+  margin: 0;
+  max-inline-size: min(36ch, 90%);
+  text-align: center;
+  font-size: 14px;
+}
+.hint {
+  padding: 6px 12px;
+  border-radius: 999px;
+  background: rgb(23 23 22 / 0.86);
+  color: #f4f4f1;
+  pointer-events: none;
+  opacity: 0;
+}
+.hint[data-shown] { opacity: 1; }
+.notice[hidden], .hint[hidden], .toolbar[hidden] { display: none; }
+.live {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+@media (prefers-reduced-motion: no-preference) {
+  .picture[data-glide], .trace[data-glide] { transition: transform 160ms ease-out, width 160ms ease-out, height 160ms ease-out; }
+  .hint { transition: opacity 200ms ease-out; }
+}
+`;

package/dist/element/trace-layer.d.ts

@@ -0,0 +1,9 @@
+import type { View } from '../core/canvas-view.js';
+import type { Trace, TraceMap } from '../core/picture-map.js';
+/** The overlay for one trace. `place` sizes and moves it with the picture. */
+export declare function traceLayer(map: TraceMap, trace: Trace): SVGSVGElement;
+/** Sizes and moves an element drawn in the picture's units (the `img` or the overlay) to a view. */
+export declare function place(element: HTMLElement | SVGElement, size: {
+    width: number;
+    height: number;
+}, view: View): void;

package/dist/element/trace-layer.js

@@ -0,0 +1,45 @@
+import { svg } from './dom.js';
+/**
+ * The traced box's lines, drawn by the element over the picture, never inside it. The picture stays an `img`, which runs no
+ * script; this is an SVG of the element's own, in the picture's viewBox, sized and moved exactly as the `img` is. It holds only
+ * numbers and the path data `readTraceMap` checked. A veil dims everything but the traced box, the boxes at the other ends and the
+ * lines' labels; the lines are drawn again over the veil, stopping at each label; and the boxes are outlined. The same as the
+ * portal's `TraceOverlay`.
+ */
+/** How far an outline sits outside the box it marks, in the picture's units. */
+const OUTSET = 3;
+const outset = (box, by) => ({ x: box.x - by, y: box.y - by, width: box.width + 2 * by, height: box.height + 2 * by });
+const rect = (box, extra) => svg('rect', { x: box.x, y: box.y, width: box.width, height: box.height, ...extra });
+let masks = 0;
+/** The overlay for one trace. `place` sizes and moves it with the picture. */
+export function traceLayer(map, trace) {
+    masks += 1;
+    const maskId = `plotwork-trace-${masks}`;
+    const { viewBox } = map;
+    const others = trace.lines.map((line) => line.other).filter((node, index, all) => node.id !== trace.node.id && all.findIndex((seen) => seen.id === node.id) === index);
+    const labels = trace.lines.map((line) => line.line.label).filter((label) => label !== null);
+    const chosen = outset(trace.node.box, OUTSET);
+    const holes = [chosen, ...others.map((node) => outset(node.box, OUTSET)), ...labels.map((label) => outset(label, 2))];
+    const whole = { x: viewBox.x, y: viewBox.y, width: viewBox.width, height: viewBox.height };
+    const unitsOf = { maskUnits: 'userSpaceOnUse', ...whole };
+    const lines = svg('g', { mask: `url(#${maskId}-lines)` });
+    for (const { line } of trace.lines) {
+        const group = svg('g', { 'data-line': line.id });
+        for (const path of line.paths) {
+            const placed = svg('g', path.dx === 0 && path.dy === 0 ? {} : { transform: `translate(${path.dx} ${path.dy})` });
+            placed.append(svg('path', { class: 'halo', d: path.d }), svg('path', { class: path.filled ? 'ribbon' : 'stroke', d: path.d }));
+            group.append(placed);
+        }
+        lines.append(group);
+    }
+    return svg('svg', { class: 'trace', 'aria-hidden': 'true', focusable: 'false', 'data-trace': trace.node.id, viewBox: `${viewBox.x} ${viewBox.y} ${viewBox.width} ${viewBox.height}` }, svg('defs', {}, svg('mask', { id: maskId, ...unitsOf }, rect(whole, { fill: '#fff' }), ...holes.map((hole) => rect(hole, { rx: 6, fill: '#000' }))), svg('mask', { id: `${maskId}-lines`, ...unitsOf }, rect(whole, { fill: '#fff' }), ...labels.map((label) => rect(label, { rx: label.height / 2, fill: '#000' })))), rect(whole, { class: 'veil', mask: `url(#${maskId})` }), lines, ...labels.map((label) => {
+        const box = outset(label, 2);
+        return rect(box, { class: 'label', rx: box.height / 2 });
+    }), ...others.map((node) => rect(outset(node.box, OUTSET), { class: 'end', 'data-end': node.id, rx: node.radius + OUTSET })), rect(chosen, { class: 'chosen', rx: trace.node.radius + OUTSET }));
+}
+/** Sizes and moves an element drawn in the picture's units (the `img` or the overlay) to a view. */
+export function place(element, size, view) {
+    element.style.width = `${size.width * view.scale}px`;
+    element.style.height = `${size.height * view.scale}px`;
+    element.style.transform = `translate(${view.x}px, ${view.y}px)`;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { definePlotworkDiagram, TAG_NAME } from './element/define.js';
+export type { PlotworkDiagramElement } from './element/plotwork-diagram.js';
+export { DEFAULT_LABELS } from './element/copy.js';
+export type { ViewerLabels } from './element/copy.js';
+export type { ChangeDetail, DrillDetail, ErrorDetail, LoadDetail, PlotworkEventMap, TraceDetail } from './element/events.js';
+export { fingerprintOf, isFingerprint, readEmbeddedSource, readTraceMap } from './core/index.js';
+export type { LoadFailure, SourceReading, ThemeChoice, TraceMap } from './core/index.js';