@plotwork.official/viewer 0.0.0-stage → 0.1.1

package/dist/core/picture-loader.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fetching a picture's text from its address: a file beside the page, a hosted picture (`cdn.plotwork.dev/d/...`), a stable link
+ * (`/l/...`), or an organisation's embed link (`/o/...`). It sends no cookie, asks for an image, and refuses a response past
+ * `PICTURE_MAX_BYTES` before reading it whole. A failure is a `PictureLoadError` with a reason the element shows, never a
+ * stack trace.
+ *
+ * `revalidate` asks the browser to check its copy with the server before using it (`cache: 'no-cache'`): the browser sends the tag it
+ * holds, the server answers 304 when nothing changed, and the browser hands back its copy. That is how a live viewer sees a new
+ * version without downloading the picture again every time.
+ */
+/** Why a picture could not be loaded. */
+export type LoadFailure = 
+/** The address is not one the viewer fetches: not http, https, or a path relative to the page. */
+'address'
+/** The server answered 404 or 403. */
+ | 'missing'
+/** The answer is not an SVG, or is larger than any picture. */
+ | 'not-a-picture'
+/** No answer: offline, refused by the page's content security policy or CORS, or timed out. */
+ | 'network'
+/** The picture's fingerprint is not the one the page pinned. */
+ | 'fingerprint';
+export declare class PictureLoadError extends Error {
+    readonly reason: LoadFailure;
+    constructor(reason: LoadFailure);
+}
+/** The address resolved against the page, or null when it is not http or https. A `javascript:` or `data:` address is refused. */
+export declare function pictureUrl(src: string, base: string): URL | null;
+/** What a fetch needs besides the address. */
+export interface LoadOptions {
+    signal?: AbortSignal | undefined;
+    /** Check the browser's copy with the server first, for a live viewer. */
+    revalidate?: boolean | undefined;
+    /** The `fetch` to call; the global one when left out, so a test or a host can supply its own. */
+    fetcher?: typeof fetch | undefined;
+}
+/** The text of the picture at an address. */
+export declare function loadPicture(url: URL, options?: LoadOptions): Promise<string>;

package/dist/core/picture-loader.js

@@ -0,0 +1,58 @@
+import { PICTURE_MAX_BYTES, REQUEST_TIMEOUT_MS } from './limits.js';
+export class PictureLoadError extends Error {
+    reason;
+    constructor(reason) {
+        super(`The picture could not be loaded (${reason})`);
+        this.name = 'PictureLoadError';
+        this.reason = reason;
+    }
+}
+/** The address resolved against the page, or null when it is not http or https. A `javascript:` or `data:` address is refused. */
+export function pictureUrl(src, base) {
+    let url;
+    try {
+        url = new URL(src, base);
+    }
+    catch {
+        // Not an address at all: the caller says so.
+        return null;
+    }
+    return url.protocol === 'https:' || url.protocol === 'http:' ? url : null;
+}
+/** The text of the picture at an address. */
+export async function loadPicture(url, options = {}) {
+    const timeout = new AbortController();
+    const timer = setTimeout(() => timeout.abort(), REQUEST_TIMEOUT_MS);
+    const abort = () => timeout.abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const fetcher = options.fetcher ?? fetch;
+    try {
+        const response = await fetcher(url.href, {
+            credentials: 'omit',
+            headers: { Accept: 'image/svg+xml' },
+            cache: options.revalidate === true ? 'no-cache' : 'default',
+            signal: timeout.signal,
+        });
+        if (response.status === 404 || response.status === 403)
+            throw new PictureLoadError('missing');
+        if (!response.ok)
+            throw new PictureLoadError('network');
+        const declared = Number(response.headers.get('content-length'));
+        if (Number.isFinite(declared) && declared > PICTURE_MAX_BYTES)
+            throw new PictureLoadError('not-a-picture');
+        const text = await response.text();
+        if (text.length > PICTURE_MAX_BYTES || !/<svg[\s>]/.test(text))
+            throw new PictureLoadError('not-a-picture');
+        return text;
+    }
+    catch (error) {
+        if (error instanceof PictureLoadError || options.signal?.aborted === true)
+            throw error;
+        // No answer (offline, refused, or timed out) is one reason to the page, like every other failure here.
+        throw new PictureLoadError('network');
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', abort);
+    }
+}

package/dist/core/picture-map.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The boxes and lines of a painted picture, read from its text so the viewer can trace a box's lines over the `img`. Kept equal to
+ * the Plotwork portal's reader (`apps/app/src/lib/picture-trace.ts`); `spec/picture.md` is the contract both read.
+ *
+ * The engine marks what it paints: a box is a group with `data-node` (or `data-state-id` for a state's start, end, choice and
+ * history marks), and a line is a group with `data-edge`, `data-link`, `data-transition` or `data-flow` and the ids of its two
+ * ends in `data-from` and `data-to`. A Gantt link names its ends in its own id (`data-link="a>b"`), a mind map ribbon is a path
+ * with `data-link-from` and `data-link-to` holding topic numbers (the topic is `t<number>`), and a Sankey flow names its ends by
+ * the words on their boxes. A line's label is a group with `data-edge-label` equal to the line's id. A kind that marks no ends
+ * (a sequence's messages, a class or table relation, a git graph) has nothing to trace, and the map has no lines.
+ *
+ * The text is parsed with `DOMParser` into a document that is never attached to the page, so nothing in it is drawn or run.
+ * Only numbers, ids, the words on a box, and path data that passes `PATH_DATA` leave this module. Path data is drawn again by
+ * the viewer, so anything in it but commands and numbers is dropped. A mistake is a result (`null`, or a box left out), never an
+ * exception.
+ */
+export interface TraceBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One path of a line, where it is drawn. `filled` is a shape painted by its fill (a ribbon), not a stroke. */
+export interface TracePath {
+    d: string;
+    dx: number;
+    dy: number;
+    filled: boolean;
+}
+export interface TraceNode {
+    id: string;
+    /** The words on the box, for a screen reader. A state's mark with no words is named by its kind (Start, End), anything else by its id. */
+    name: string;
+    box: TraceBox;
+    /** The corner radius of the box's own shape, so its outline follows it. */
+    radius: number;
+    /** The place in its series of the diagram that draws this box in full, from the engine's `data-part` (`part=`); absent for none. */
+    part?: number;
+}
+export interface TraceLine {
+    id: string;
+    from: string;
+    to: string;
+    paths: TracePath[];
+    label: TraceBox | null;
+}
+export interface TraceMap {
+    viewBox: TraceBox;
+    nodes: TraceNode[];
+    lines: TraceLine[];
+}
+/** One line of a traced box, from that box's side: the line, which way it runs, and the box at its other end. */
+export interface TracedLine {
+    line: TraceLine;
+    direction: 'to' | 'from';
+    other: TraceNode;
+}
+export interface Trace {
+    node: TraceNode;
+    lines: TracedLine[];
+}
+/** Path data the viewer will draw again: path commands, numbers, spaces, commas, dots and minus signs, and nothing else. */
+export declare const PATH_DATA: RegExp;
+/**
+ * The boxes and lines of a painted picture. Null when the text is not an SVG or has no size. A picture whose kind marks no ends
+ * gives a map with no lines, which the viewer takes to mean there is nothing to trace.
+ */
+export declare function readTraceMap(svg: string): TraceMap | null;
+/** The root of a picture's text, parsed into a document that is never attached to the page; null when it is not an SVG. */
+export declare function parsePicture(svg: string): Element | null;
+/** The trace map of a picture already parsed with `parsePicture`, so a reader that needs more of it parses it once. */
+export declare function traceMapOf(root: Element): TraceMap | null;
+/** The boxes that have at least one line, in reading order: top to bottom, then left to right. These are the ones a person can trace. */
+export declare function traceableNodes(map: TraceMap): TraceNode[];
+/** A box's lines, each from that box's side. Null for a box with no lines or no such box. */
+export declare function traceOf(map: TraceMap, id: string): Trace | null;
+/** The traceable box under a point of the picture: the smallest one that holds it, so a box inside a box is reachable. */
+export declare function nodeAt(map: TraceMap, point: {
+    x: number;
+    y: number;
+}): TraceNode | null;
+/** The box under a point of the picture that opens a part of its series (`part=`): the smallest one that holds it. */
+export declare function drillNodeAt(map: TraceMap, point: {
+    x: number;
+    y: number;
+}): TraceNode | null;

package/dist/core/picture-map.js

@@ -0,0 +1,288 @@
+/**
+ * The boxes and lines of a painted picture, read from its text so the viewer can trace a box's lines over the `img`. Kept equal to
+ * the Plotwork portal's reader (`apps/app/src/lib/picture-trace.ts`); `spec/picture.md` is the contract both read.
+ *
+ * The engine marks what it paints: a box is a group with `data-node` (or `data-state-id` for a state's start, end, choice and
+ * history marks), and a line is a group with `data-edge`, `data-link`, `data-transition` or `data-flow` and the ids of its two
+ * ends in `data-from` and `data-to`. A Gantt link names its ends in its own id (`data-link="a>b"`), a mind map ribbon is a path
+ * with `data-link-from` and `data-link-to` holding topic numbers (the topic is `t<number>`), and a Sankey flow names its ends by
+ * the words on their boxes. A line's label is a group with `data-edge-label` equal to the line's id. A kind that marks no ends
+ * (a sequence's messages, a class or table relation, a git graph) has nothing to trace, and the map has no lines.
+ *
+ * The text is parsed with `DOMParser` into a document that is never attached to the page, so nothing in it is drawn or run.
+ * Only numbers, ids, the words on a box, and path data that passes `PATH_DATA` leave this module. Path data is drawn again by
+ * the viewer, so anything in it but commands and numbers is dropped. A mistake is a result (`null`, or a box left out), never an
+ * exception.
+ */
+/** Path data the viewer will draw again: path commands, numbers, spaces, commas, dots and minus signs, and nothing else. */
+export const PATH_DATA = /^[MmLlHhVvCcSsQqTtAaZz0-9 ,.-]+$/;
+const BOX_MARKS = ['data-node', 'data-state-id'];
+const LINE_MARKS = ['data-edge', 'data-link', 'data-transition', 'data-flow'];
+const SHAPES = 'rect, circle, ellipse, polygon, path';
+const num = (value) => {
+    const parsed = value === null ? Number.NaN : Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+};
+/** The offset of an element from the picture's origin: the sum of the translations above it, or null under a scale or a turn. */
+function offsetOf(element) {
+    let dx = 0;
+    let dy = 0;
+    for (let at = element; at !== null; at = at.parentElement) {
+        const transform = at.getAttribute('transform');
+        if (transform === null || transform.trim() === '')
+            continue;
+        const match = /^\s*translate\(\s*(-?[\d.]+)(?:[\s,]+(-?[\d.]+))?\s*\)\s*$/.exec(transform);
+        if (match === null)
+            return null;
+        dx += num(match[1] ?? null);
+        dy += num(match[2] ?? null);
+    }
+    return { dx, dy };
+}
+const COMMAND = /[MmLlHhVvCcSsQqTtAaZz]|-?(?:\d+\.?\d*|\.\d+)/g;
+/** How many numbers each command takes, and which of them are x and y pairs (the rest of an arc are radii and flags). */
+const ARITY = { M: 2, L: 2, H: 1, V: 1, C: 6, S: 4, Q: 4, T: 2, A: 7, Z: 0 };
+/** The box a path's points and control points fall in. A curve never leaves its control points, so the box holds the shape. */
+function pathBox(d) {
+    if (!PATH_DATA.test(d))
+        return null;
+    const xs = [];
+    const ys = [];
+    let pen = { x: 0, y: 0 };
+    let start = pen;
+    let command = '';
+    let numbers = [];
+    const flush = () => {
+        const upper = command.toUpperCase();
+        const relative = command !== upper;
+        const arity = ARITY[upper] ?? 0;
+        if (upper === 'Z')
+            pen = start;
+        for (let index = 0; arity > 0 && index + arity <= numbers.length; index += arity) {
+            const n = numbers.slice(index, index + arity);
+            const base = relative ? pen : { x: 0, y: 0 };
+            const pairs = [];
+            if (upper === 'H')
+                pairs.push({ x: base.x + (n[0] ?? 0), y: pen.y });
+            else if (upper === 'V')
+                pairs.push({ x: pen.x, y: base.y + (n[0] ?? 0) });
+            else if (upper === 'A')
+                pairs.push({ x: base.x + (n[5] ?? 0), y: base.y + (n[6] ?? 0) });
+            else
+                for (let pair = 0; pair + 1 < n.length; pair += 2)
+                    pairs.push({ x: base.x + (n[pair] ?? 0), y: base.y + (n[pair + 1] ?? 0) });
+            for (const point of pairs) {
+                xs.push(point.x);
+                ys.push(point.y);
+            }
+            pen = pairs[pairs.length - 1] ?? pen;
+            if (upper === 'M' && index === 0)
+                start = pen;
+        }
+    };
+    for (const token of d.match(COMMAND) ?? []) {
+        if (/[A-Za-z]/.test(token)) {
+            flush();
+            command = token;
+            numbers = [];
+        }
+        else
+            numbers.push(Number(token));
+    }
+    flush();
+    if (xs.length === 0)
+        return null;
+    const x = Math.min(...xs);
+    const y = Math.min(...ys);
+    return { x, y, width: Math.max(...xs) - x, height: Math.max(...ys) - y };
+}
+/** The box of one shape, in its own coordinates. */
+function shapeBox(shape) {
+    const name = shape.localName;
+    if (name === 'rect')
+        return { x: num(shape.getAttribute('x')), y: num(shape.getAttribute('y')), width: num(shape.getAttribute('width')), height: num(shape.getAttribute('height')) };
+    if (name === 'circle' || name === 'ellipse') {
+        const rx = num(shape.getAttribute(name === 'circle' ? 'r' : 'rx'));
+        const ry = num(shape.getAttribute(name === 'circle' ? 'r' : 'ry'));
+        return { x: num(shape.getAttribute('cx')) - rx, y: num(shape.getAttribute('cy')) - ry, width: 2 * rx, height: 2 * ry };
+    }
+    if (name === 'polygon')
+        return pathBox(`M${shape.getAttribute('points') ?? ''}`);
+    if (name === 'path')
+        return pathBox(shape.getAttribute('d') ?? '');
+    return null;
+}
+/** The first shape painted inside a box's group, where it is on the picture, and its corner radius. */
+function boxOf(group) {
+    const shapes = group.localName === 'g' ? [...group.querySelectorAll(SHAPES)] : [group];
+    for (const shape of shapes) {
+        const offset = offsetOf(shape);
+        const box = offset === null ? null : shapeBox(shape);
+        if (offset === null || box === null || box.width <= 0 || box.height <= 0)
+            continue;
+        const radius = shape.localName === 'rect' ? num(shape.getAttribute('rx')) : shape.localName === 'path' || shape.localName === 'polygon' ? 0 : box.width / 2;
+        return { box: { ...box, x: box.x + offset.dx, y: box.y + offset.dy }, radius };
+    }
+    return null;
+}
+/** The paths that draw a line, each checked and placed. A path whose data is not plain path data is left out. */
+function pathsOf(line) {
+    const paths = line.localName === 'path' ? [line] : [...line.querySelectorAll('path')];
+    const out = [];
+    for (const path of paths) {
+        const d = path.getAttribute('d') ?? '';
+        const offset = offsetOf(path);
+        if (offset === null || d === '' || !PATH_DATA.test(d))
+            continue;
+        const fill = path.getAttribute('fill');
+        out.push({ d, ...offset, filled: fill !== null && fill !== 'none' });
+    }
+    return out;
+}
+/** The two ends a line names, before they are matched to boxes. */
+function endsOf(line) {
+    const from = line.getAttribute('data-from');
+    const to = line.getAttribute('data-to');
+    if (from !== null && to !== null)
+        return { from, to, numbered: false };
+    const linkFrom = line.getAttribute('data-link-from');
+    const linkTo = line.getAttribute('data-link-to');
+    if (linkFrom !== null && linkTo !== null)
+        return { from: linkFrom, to: linkTo, numbered: true };
+    /* A Gantt link names its ends in its id, the task before and the task after a `>`. */
+    const pair = (line.getAttribute('data-link') ?? '').split('>');
+    if (pair.length === 2 && pair[0] !== '' && pair[1] !== '')
+        return { from: pair[0], to: pair[1], numbered: false };
+    return null;
+}
+/** The name of a state's mark that has no words (start, end, choice, history, fork, join), as a word a person reads. */
+const markName = (group) => {
+    const mark = group.getAttribute('data-state-marker') ?? '';
+    return /^[a-z]+$/.test(mark) ? `${mark[0].toUpperCase()}${mark.slice(1)}` : '';
+};
+const words = (group) => (group.querySelector('text')?.textContent ?? '').replace(/\s+/g, ' ').trim();
+/**
+ * The boxes and lines of a painted picture. Null when the text is not an SVG or has no size. A picture whose kind marks no ends
+ * gives a map with no lines, which the viewer takes to mean there is nothing to trace.
+ */
+export function readTraceMap(svg) {
+    const root = parsePicture(svg);
+    return root === null ? null : traceMapOf(root);
+}
+/** The root of a picture's text, parsed into a document that is never attached to the page; null when it is not an SVG. */
+export function parsePicture(svg) {
+    let document;
+    try {
+        document = new DOMParser().parseFromString(svg, 'image/svg+xml');
+    }
+    catch {
+        return null;
+    }
+    const root = document.documentElement;
+    return root.localName !== 'svg' || document.getElementsByTagName('parsererror').length > 0 ? null : root;
+}
+/** The trace map of a picture already parsed with `parsePicture`, so a reader that needs more of it parses it once. */
+export function traceMapOf(root) {
+    const viewBox = viewBoxOf(root);
+    if (viewBox === null)
+        return null;
+    const nodes = [];
+    const byId = new Map();
+    const byName = new Map();
+    for (const group of root.querySelectorAll(BOX_MARKS.map((mark) => `[${mark}]`).join(', '))) {
+        const id = BOX_MARKS.map((mark) => group.getAttribute(mark)).find((value) => value !== null) ?? '';
+        const placed = boxOf(group);
+        if (id === '' || placed === null || byId.has(id))
+            continue;
+        const name = words(group) || markName(group) || id;
+        const part = partOf(group);
+        const node = { id, name, ...placed, ...(part === null ? {} : { part }) };
+        nodes.push(node);
+        byId.set(id, node);
+        if (!byName.has(name))
+            byName.set(name, node);
+    }
+    const resolve = (end, numbered) => numbered ? byId.get(`t${end}`) : (byId.get(end) ?? byName.get(end));
+    const labels = new Map();
+    for (const group of root.querySelectorAll('[data-edge-label]')) {
+        const id = group.getAttribute('data-edge-label') ?? '';
+        const placed = boxOf(group);
+        if (id !== '' && placed !== null && !labels.has(id))
+            labels.set(id, placed.box);
+    }
+    const lines = [];
+    const marked = [...LINE_MARKS.map((mark) => `[${mark}]`), '[data-link-from]'].join(', ');
+    root.querySelectorAll(marked).forEach((element, index) => {
+        const ends = endsOf(element);
+        if (ends === null)
+            return;
+        const from = resolve(ends.from, ends.numbered);
+        const to = resolve(ends.to, ends.numbered);
+        const paths = pathsOf(element);
+        if (from === undefined || to === undefined || paths.length === 0)
+            return;
+        const id = LINE_MARKS.map((mark) => element.getAttribute(mark)).find((value) => value !== null) ?? `line-${index}`;
+        lines.push({ id, from: from.id, to: to.id, paths, label: labels.get(id) ?? null });
+    });
+    return { viewBox, nodes, lines };
+}
+/** A box's `data-part`: a whole number from 1, or null for none or anything else. */
+function partOf(group) {
+    const value = group.getAttribute('data-part') ?? '';
+    return /^[1-9]\d{0,2}$/.test(value) ? Number(value) : null;
+}
+function viewBoxOf(root) {
+    const box = (root.getAttribute('viewBox') ?? '').trim().split(/[\s,]+/).map(Number);
+    if (box.length === 4 && box.every(Number.isFinite) && box[2] > 0 && box[3] > 0) {
+        return { x: box[0], y: box[1], width: box[2], height: box[3] };
+    }
+    const width = num(root.getAttribute('width'));
+    const height = num(root.getAttribute('height'));
+    return width > 0 && height > 0 ? { x: 0, y: 0, width, height } : null;
+}
+/** The boxes that have at least one line, in reading order: top to bottom, then left to right. These are the ones a person can trace. */
+export function traceableNodes(map) {
+    const ends = new Set(map.lines.flatMap((line) => [line.from, line.to]));
+    return map.nodes.filter((node) => ends.has(node.id)).sort((a, b) => a.box.y - b.box.y || a.box.x - b.box.x);
+}
+/** A box's lines, each from that box's side. Null for a box with no lines or no such box. */
+export function traceOf(map, id) {
+    const node = map.nodes.find((candidate) => candidate.id === id);
+    if (node === undefined)
+        return null;
+    const byId = new Map(map.nodes.map((candidate) => [candidate.id, candidate]));
+    const lines = [];
+    for (const line of map.lines) {
+        if (line.from === id)
+            lines.push({ line, direction: 'to', other: byId.get(line.to) });
+        else if (line.to === id)
+            lines.push({ line, direction: 'from', other: byId.get(line.from) });
+    }
+    return lines.length === 0 ? null : { node, lines };
+}
+/** The traceable box under a point of the picture: the smallest one that holds it, so a box inside a box is reachable. */
+export function nodeAt(map, point) {
+    let best = null;
+    for (const node of traceableNodes(map)) {
+        const { x, y, width, height } = node.box;
+        if (point.x < x || point.y < y || point.x > x + width || point.y > y + height)
+            continue;
+        if (best === null || width * height < best.box.width * best.box.height)
+            best = node;
+    }
+    return best;
+}
+/** The box under a point of the picture that opens a part of its series (`part=`): the smallest one that holds it. */
+export function drillNodeAt(map, point) {
+    let best = null;
+    for (const node of map.nodes) {
+        if (node.part === undefined)
+            continue;
+        const { x, y, width, height } = node.box;
+        if (point.x < x || point.y < y || point.x > x + width || point.y > y + height)
+            continue;
+        if (best === null || width * height < best.box.width * best.box.height)
+            best = node;
+    }
+    return best;
+}

package/dist/core/picture-scheme.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Which colour scheme a picture is shown in. A Plotwork picture drawn with `scheme=auto` carries both palettes and follows the
+ * reader's settings; a host forces one with `data-scheme="light"` or `"dark"` on its root, which the engine's style sheet reads.
+ * A picture drawn for one scheme says so in `data-theme` and ignores the attribute.
+ */
+/** What the viewer is asked to show: follow the page (`auto`), or one scheme. */
+export type ThemeChoice = 'auto' | 'light' | 'dark';
+/** A scheme a picture is actually drawn in. */
+export type Scheme = 'light' | 'dark';
+/** Reads a `theme` attribute: anything that is not `light` or `dark` is `auto`. */
+export declare function themeChoiceOf(value: string | null | undefined): ThemeChoice;
+/**
+ * The picture's text with `data-scheme` set on its root for a forced scheme, or as it was for `auto`. It edits the start tag as
+ * text, so the picture is never parsed and written out again, and an existing `data-scheme` is replaced, never doubled.
+ */
+export declare function withScheme(svg: string, choice: ThemeChoice): string;
+/** The scheme a picture was drawn in when it was drawn for one (`data-theme="light"` or `"dark"`), else null: it follows the scheme it is shown in. */
+export declare function drawnScheme(svg: string): Scheme | null;

package/dist/core/picture-scheme.js

@@ -0,0 +1,31 @@
+/**
+ * Which colour scheme a picture is shown in. A Plotwork picture drawn with `scheme=auto` carries both palettes and follows the
+ * reader's settings; a host forces one with `data-scheme="light"` or `"dark"` on its root, which the engine's style sheet reads.
+ * A picture drawn for one scheme says so in `data-theme` and ignores the attribute.
+ */
+/** Reads a `theme` attribute: anything that is not `light` or `dark` is `auto`. */
+export function themeChoiceOf(value) {
+    return value === 'light' || value === 'dark' ? value : 'auto';
+}
+/** The root `<svg ...>` start tag, after anything that may come before it. */
+const ROOT_TAG = /<svg(?=[\s>])[^>]*>/;
+/**
+ * The picture's text with `data-scheme` set on its root for a forced scheme, or as it was for `auto`. It edits the start tag as
+ * text, so the picture is never parsed and written out again, and an existing `data-scheme` is replaced, never doubled.
+ */
+export function withScheme(svg, choice) {
+    if (choice === 'auto')
+        return svg;
+    const match = ROOT_TAG.exec(svg);
+    if (match === null)
+        return svg;
+    const tag = match[0].replace(/\sdata-scheme="[^"]*"/, '');
+    const marked = tag.replace(/^<svg/, `<svg data-scheme="${choice}"`);
+    return svg.slice(0, match.index) + marked + svg.slice(match.index + match[0].length);
+}
+/** The scheme a picture was drawn in when it was drawn for one (`data-theme="light"` or `"dark"`), else null: it follows the scheme it is shown in. */
+export function drawnScheme(svg) {
+    const tag = ROOT_TAG.exec(svg)?.[0] ?? '';
+    const theme = /\sdata-theme="([^"]*)"/.exec(tag)?.[1];
+    return theme === 'light' || theme === 'dark' ? theme : null;
+}

package/dist/core/picture-source.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reading the source out of a Plotwork picture, with no engine. A picture saved with its source carries the text it was drawn from in
+ * one `<metadata data-format="buun-diagram">` element of its root; this reads it back with patterns, as the engine's own reader does,
+ * so it needs no XML parser. Kept equal to the portal's reader (`apps/app/src/lib/picture-source.ts`). A mistake is a result, never
+ * an exception.
+ */
+/** What reading a picture's source found. */
+export type SourceReading = 
+/** The source, exactly as it was written into the picture. */
+{
+    status: 'found';
+    source: string;
+}
+/** A picture that carries no source: it was saved without it, or served by an organisation's embed link, which removes it. */
+ | {
+    status: 'none';
+}
+/** Not a picture, or a source that was changed after it was written and cannot be read back. */
+ | {
+    status: 'unreadable';
+};
+/** The source a picture carries, a picture that carries none, or a text that cannot be read as either. */
+export declare function readEmbeddedSource(svg: string): SourceReading;

package/dist/core/picture-source.js

@@ -0,0 +1,57 @@
+/**
+ * Reading the source out of a Plotwork picture, with no engine. A picture saved with its source carries the text it was drawn from in
+ * one `<metadata data-format="buun-diagram">` element of its root; this reads it back with patterns, as the engine's own reader does,
+ * so it needs no XML parser. Kept equal to the portal's reader (`apps/app/src/lib/picture-source.ts`). A mistake is a result, never
+ * an exception.
+ */
+const SOURCE_FORMAT = 'buun-diagram';
+const OPEN = `<metadata data-format="${SOURCE_FORMAT}"`;
+const CLOSE = '</metadata>';
+/** What can come before the root element of a saved SVG: a byte order mark, white space, an XML declaration, comments, and a doctype. */
+const PROLOGUE = /^(?:|\s|<\?xml[^>]*\?>|<!--[\s\S]*?-->|<!DOCTYPE[^>]*>)*/i;
+function fromRoot(svg) {
+    const rest = svg.slice(PROLOGUE.exec(svg)?.[0].length ?? 0);
+    return /^<svg[\s>]/.test(rest) ? rest : null;
+}
+const ESCAPE = /&(amp|lt|gt|#13);/g;
+const UNESCAPED = { amp: '&', lt: '<', gt: '>', '#13': '\r' };
+/** Reverses the writer's escaping; null when the text has a `&` that is not one of its four escapes, or a `<`, which the writer never leaves. */
+function unescapeSource(text) {
+    if (text.includes('<') || text.replace(ESCAPE, '').includes('&'))
+        return null;
+    return text.replace(ESCAPE, (_whole, name) => UNESCAPED[name] ?? '');
+}
+/** The source a picture carries, a picture that carries none, or a text that cannot be read as either. */
+export function readEmbeddedSource(svg) {
+    const root = fromRoot(svg);
+    if (root === null)
+        return { status: 'unreadable' };
+    const start = root.indexOf(OPEN);
+    if (start === -1)
+        return { status: 'none' };
+    const tagEnd = root.indexOf('>', start);
+    if (tagEnd === -1)
+        return { status: 'unreadable' };
+    const tag = root.slice(start, tagEnd);
+    if (tag.endsWith('/'))
+        return { status: 'unreadable' };
+    const close = root.indexOf(CLOSE, tagEnd);
+    if (close === -1)
+        return { status: 'unreadable' };
+    const text = unescapeSource(root.slice(tagEnd + 1, close));
+    if (text === null)
+        return { status: 'unreadable' };
+    const encoding = /\sdata-encoding="([^"]*)"/.exec(tag)?.[1] ?? 'text';
+    if (encoding === 'text')
+        return text === '' ? { status: 'unreadable' } : { status: 'found', source: text };
+    if (encoding !== 'json')
+        return { status: 'unreadable' };
+    try {
+        const decoded = JSON.parse(text);
+        return typeof decoded === 'string' && decoded !== '' ? { status: 'found', source: decoded } : { status: 'unreadable' };
+    }
+    catch {
+        // The JSON was cut or edited after it was written: that is the answer (unreadable), not an error to throw.
+        return { status: 'unreadable' };
+    }
+}

package/dist/element/copy.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Every word the element shows or says, in one place. A page in another language sets the element's `labels` property to a partial
+ * copy of this object; anything it leaves out stays English.
+ */
+export interface ViewerLabels {
+    canvas: string;
+    zoomIn: string;
+    zoomOut: string;
+    fit: string;
+    fullscreen: string;
+    exitFullscreen: string;
+    zoomLevel: (percent: number) => string;
+    loading: string;
+    wheelHint: string;
+    traced: (name: string, lines: number) => string;
+    drill: (name: string) => string;
+    updated: string;
+    failed: Readonly<Record<'address' | 'missing' | 'not-a-picture' | 'network' | 'fingerprint' | 'empty', string>>;
+}
+export declare const DEFAULT_LABELS: ViewerLabels;
+/** The labels with a page's own over the defaults. */
+export declare function mergeLabels(own: Partial<ViewerLabels> | undefined): ViewerLabels;

package/dist/element/copy.js

@@ -0,0 +1,28 @@
+export const DEFAULT_LABELS = {
+    canvas: 'Diagram. Arrow keys move it, plus and minus zoom, 0 fits it.',
+    zoomIn: 'Zoom in',
+    zoomOut: 'Zoom out',
+    fit: 'Fit to view',
+    fullscreen: 'Full screen',
+    exitFullscreen: 'Leave full screen',
+    zoomLevel: (percent) => `${percent}%`,
+    loading: 'Loading the diagram',
+    wheelHint: 'Hold Control or Command and scroll to zoom',
+    traced: (name, lines) => `${name}: ${lines} ${lines === 1 ? 'line' : 'lines'}`,
+    drill: (name) => `${name} opens its part`,
+    updated: 'The diagram was updated',
+    failed: {
+        address: 'This diagram address cannot be shown.',
+        missing: 'This diagram is not there.',
+        'not-a-picture': 'This is not a Plotwork diagram.',
+        network: 'The diagram could not be loaded. Check the connection and the page settings.',
+        fingerprint: 'This diagram has changed since the page pinned it, so it is not shown.',
+        empty: 'No diagram to show.',
+    },
+};
+/** The labels with a page's own over the defaults. */
+export function mergeLabels(own) {
+    if (own === undefined)
+        return DEFAULT_LABELS;
+    return { ...DEFAULT_LABELS, ...own, failed: { ...DEFAULT_LABELS.failed, ...own.failed } };
+}