@plotwork.official/viewer 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plotwork
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @plotwork.official/viewer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Embed interactive Plotwork diagrams in any page: pan and zoom, trace a box's lines, drill from an overview box into its part, light and dark, and live updates when a new version is published. A web component, `<plotwork-diagram>`, and a React component, `<PlotworkDiagram>`.
+
+## TL;DR
+
+| Question | Answer |
+|---|---|
+| What does it show? | Any SVG the Plotwork engine drew: a file in your repository, a hosted picture, a stable link, or an organisation embed link. |
+| What does it install? | Nothing else. No runtime dependencies; React is an optional peer for the React component. |
+| Does it run the diagram engine? | No. A Plotwork picture already carries its boxes, lines, parts and source, so the viewer reads them. |
+| Does it phone home? | No. It fetches only the address you give it, with no cookie. |
+| Can a picture run script in my page? | No. It is shown as an `img`, and the element builds its own nodes without HTML text. |
+| Live updates? | `live` checks the address every 60 seconds while the page is in view and swaps in a new version. |
+| Pinning? | `fingerprint="sha256-..."` shows the picture only when it is exactly that one. |
+
+## Install
+
+```bash
+npm install @plotwork.official/viewer
+```
+
+## Any page
+
+```html
+<script type="module">
+  import '@plotwork.official/viewer/register'
+</script>
+
+<plotwork-diagram src="/diagrams/checkout.svg" label="Checkout flow"></plotwork-diagram>
+```
+
+## React
+
+```tsx
+import { PlotworkDiagram } from '@plotwork.official/viewer/react'
+
+export function Architecture() {
+  return <PlotworkDiagram src="https://cdn.plotwork.dev/l/<link>.svg" live onDrill={({ part }) => openPart(part)} />
+}
+```
+
+It renders as the bare element on a server and comes alive in the browser.
+
+## Where pictures come from
+
+| Source | `src` | Notes |
+|---|---|---|
+| A file in your repository | `/diagrams/checkout.svg` | Drawn by the Plotwork command line, the MCP server or the GitHub Action. A picture saved with its source gives `source()` back. |
+| A hosted picture | `https://cdn.plotwork.dev/d/<token>.svg` | Never changes. |
+| A stable link | `https://cdn.plotwork.dev/l/<token>.svg` | Always the latest version of a named diagram. Add `live` to follow it. |
+| An organisation's library | `https://cdn.plotwork.dev/o/<token>.svg` | An embed link the owner made for your site. Other sites get a placeholder. The source is never sent. |
+| Text you already hold | the `svg` property | A bundler import, or a picture your server fetched. Wins over `src`. |
+
+## Attributes
+
+| Attribute | Values | Default |
+|---|---|---|
+| `src` | An http or https address, or a path relative to the page | none |
+| `theme` | `auto`, `light`, `dark` | `auto`: a picture drawn for both schemes follows the page |
+| `live` | present or absent | absent |
+| `interval` | seconds between checks for a live picture | `60`, never below `15` |
+| `fingerprint` | `sha256-<64 hex>` | none. A pinned picture is never live. |
+| `wheel` | `modifier` (Control or Command with the wheel zooms), `zoom` (a plain wheel zooms) | `modifier`; in full screen the wheel always zooms |
+| `controls` | `none` hides the toolbar | shown |
+| `label` | what the diagram shows, for a screen reader | none |
+
+## Methods, properties and events
+
+| Name | What it does |
+|---|---|
+| `fit()`, `zoomIn()`, `zoomOut()` | Move the view. |
+| `reload()` | Check the address again now. |
+| `source()` | The source the picture carries, or `null`. |
+| `fingerprint` | The fingerprint of the picture shown. |
+| `svg` | Set the picture's text directly. |
+| `labels` | Words in your language, over the English defaults. |
+| `plotwork-load` | `{ fingerprint, hasSource }` |
+| `plotwork-change` | `{ fingerprint, previous }`: a live picture changed. |
+| `plotwork-error` | `{ reason }`: `address`, `missing`, `not-a-picture`, `network`, `fingerprint`, or `empty`. |
+| `plotwork-drill` | `{ id, part, name }`: a box that opens a part was pressed. You decide what opens. |
+| `plotwork-trace` | `{ id }`: the traced box, or `null`. |
+
+## Theming
+
+Set custom properties on the element: `--plotwork-height`, `--plotwork-paper`, `--plotwork-ink`, `--plotwork-trace`, `--plotwork-radius`, `--plotwork-font`. Style the parts with `::part(stage)`, `::part(canvas)`, `::part(toolbar)`, `::part(button)` and `::part(notice)`.
+
+## Content security policy
+
+| Directive | Needs |
+|---|---|
+| `img-src` | `blob:` (the picture is shown from a `blob:` address) |
+| `connect-src` | the origin of each `src`, such as `https://cdn.plotwork.dev` |
+
+## See also
+
+| Page | Why |
+|---|---|
+| [Picture contract](../../spec/picture.md) | What the viewer reads from a picture |
+| [Core](./src/core/README.md) | The parts that need no element |
+| [Element](./src/element/README.md) | How `<plotwork-diagram>` is built |

package/dist/core/canvas-view.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The arithmetic of the viewer's canvas, with no browser in it: where the picture sits and how big it is drawn, for a
+ * canvas of a given size. A view is the picture's top left corner in the canvas (`x`, `y`, in pixels) and the factor it is
+ * drawn at (`scale`, 1 is the picture's own size). Every function takes a view and gives a new one that is already inside
+ * the rules, so the component that moves the picture never has to check them.
+ *
+ * The rules: the zoom is between 10 percent and 800 percent; the fit zoom is never above 100 percent, so a small diagram
+ * is not blown up to fill the window; the fitted picture is centred, except down a portrait canvas (a phone held upright), where
+ * it sits at the top so the space a short diagram leaves is below it, not above; a drag moves the picture freely at any zoom,
+ * until only a strip of it (`KEEP_PX`) is left in the canvas, so it can always be grabbed again.
+ */
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface View {
+    scale: number;
+    x: number;
+    y: number;
+}
+/** How many pixels of the picture stay in the canvas however far it is dragged, so it can always be grabbed and brought back. */
+export declare const KEEP_PX = 96;
+/** True when a canvas and a picture both have a size to work with. Before the picture has loaded, or in a window with no layout, they do not. */
+export declare function hasRoom(viewport: Size, picture: Size): boolean;
+/** The zoom at which the whole picture is in the canvas with some air around it. Never above 1, so a small picture stays its own size. */
+export declare function fitScale(viewport: Size, picture: Size): number;
+/**
+ * The smallest and largest zoom. The smallest is 10 percent, or the fit zoom when a very large picture needs less than that
+ * to be seen whole, so Fit is always reachable.
+ */
+export declare function zoomLimits(fit: number): {
+    min: number;
+    max: number;
+};
+/** A zoom held inside the limits. */
+export declare function clampScale(scale: number, fit: number): number;
+/** True for a canvas taller than it is wide: a phone held upright, where a centred picture would leave a gap above it. */
+export declare function isPortrait(viewport: Size): boolean;
+/** A view moved inside the rules for this canvas and picture. */
+export declare function clampView(view: View, viewport: Size, picture: Size): View;
+/** The picture at this zoom, centred in the canvas (at the top of a portrait one, when it fits down it). */
+export declare function centred(scale: number, viewport: Size, picture: Size): View;
+/** The picture fitted to the canvas and centred (at the top of a portrait one). */
+export declare function fitView(viewport: Size, picture: Size): View;
+/** The picture moved by `dx` and `dy` pixels. */
+export declare function panBy(view: View, dx: number, dy: number, viewport: Size, picture: Size): View;
+/**
+ * The picture at a new zoom, with the spot under `point` (in canvas pixels) staying under it: zooming with the pointer
+ * over a detail keeps the detail under the pointer. The zoom is held inside the limits first.
+ */
+export declare function zoomAt(view: View, point: Point, scale: number, viewport: Size, picture: Size): View;
+/**
+ * The view that shows a box of the picture (in the picture's own units): unchanged when the box is already whole in the canvas,
+ * else moved, at the same zoom, so the box is in the middle. Stepping from box to box with the keyboard never leaves one out of sight.
+ */
+export declare function revealed(view: View, box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, viewport: Size, picture: Size): View;
+/** The largest zoom Zoom to selection goes to: close enough to read, never so close one box fills the window. */
+export declare const BOX_ZOOM_MAX = 2;
+/** The view that shows a box of the picture whole and centred, as large as fits up to `max` (`BOX_ZOOM_MAX`), for Zoom to selection. */
+export declare function boxView(box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, viewport: Size, picture: Size, max?: number): View;
+/** The middle of the canvas, where a zoom button or key zooms around. */
+export declare function middleOf(viewport: Size): Point;
+/**
+ * The view while two fingers are down. The spot of the picture that was under the fingers' midpoint when they landed stays
+ * under their midpoint as it moves, and the zoom follows the distance between them, so a pinch zooms and a drag with two
+ * fingers pans, in one gesture.
+ */
+export declare function pinchView(start: {
+    view: View;
+    mid: Point;
+    distance: number;
+}, now: {
+    mid: Point;
+    distance: number;
+}, viewport: Size, picture: Size): View;
+/** True when the view is the fitted one, so a refit on resize is right and a double press means "zoom in". */
+export declare function isFitted(view: View, viewport: Size, picture: Size): boolean;
+/** True when the view is the fitted view itself, at the fit zoom and in its place, not one moved away from it by a drag. */
+export declare function isFitView(view: View, viewport: Size, picture: Size): boolean;
+/** What a double press does: from fitted, to 100 percent (or to 200 percent when the picture already fits at 100); from anything else, back to fit. */
+export declare function toggledScale(view: View, viewport: Size, picture: Size): number;
+/** The zoom as the whole percent a person reads. */
+export declare function percentOf(scale: number): number;
+/** How much a wheel turn zooms: smooth for a trackpad's pinch (small steps), and capped so a mouse wheel's notch is a step, not a leap. */
+export declare function wheelZoomFactor(deltaY: number): number;
+/**
+ * What a plain wheel does over a canvas. `zoom` is for a canvas that is the page (the editor, a viewer that fills the window or is in
+ * full screen): the wheel zooms. `modifier` is for a canvas inside a page that scrolls: the wheel scrolls the page, and only Control or
+ * Command with the wheel zooms.
+ */
+export type WheelMode = 'zoom' | 'modifier';
+/** What one wheel event is for: zooming at the pointer, moving the picture, or the page's own scroll. */
+export type WheelIntent = 'zoom' | 'pan' | 'page';
+/**
+ * Whether a wheel event came from a mouse's wheel rather than a two-finger swipe on a trackpad. Browsers do not say, so this reads
+ * the shape of the event: a mouse wheel reports lines or pages (`deltaMode` 1 or 2), or whole pixels in steps of a notch on one axis
+ * only. A swipe reports pixels, often fractional, often small, and often with a sideways part. A slow swipe that looks like a notch is
+ * read as a mouse and zooms, which is the safer of the two mistakes on a full-window canvas.
+ */
+export declare function isMouseWheel(event: {
+    deltaX: number;
+    deltaY: number;
+    deltaMode: number;
+}): boolean;
+/**
+ * What a wheel event does. Control or Command with the wheel (and a trackpad's pinch, which arrives that way) always zooms. With
+ * neither, a `zoom` canvas zooms for a mouse wheel and moves the picture for a trackpad swipe, so a trackpad can still get about;
+ * a `modifier` canvas leaves the wheel to the page.
+ */
+export declare function wheelIntent(event: {
+    deltaX: number;
+    deltaY: number;
+    deltaMode: number;
+    ctrlKey: boolean;
+    metaKey: boolean;
+}, mode: WheelMode): WheelIntent;
+/**
+ * What one turn of a mouse wheel multiplies the zoom by: proportional to how far it turned, so a notch (about 100 pixels) is close to
+ * a press of a zoom button and a fast spin is a few of them, never a leap.
+ */
+export declare function mouseWheelZoomFactor(deltaY: number): number;
+/** The dot grid's step at 100 percent, in pixels: the portal's own `--canvas-step` (1.5rem). */
+export declare const DOT_STEP = 24;
+/**
+ * Where the dot grid behind the picture is drawn for a view: its step on screen and its offset, so the dots move and scale with
+ * the picture like the paper it is drawn on. Zoomed far out the grid takes every second dot, and zoomed far in it adds one between,
+ * so it never turns into a grey wash or a sparse scatter.
+ */
+export declare function dotGrid(view: View): {
+    size: number;
+    x: number;
+    y: number;
+};
+/** The dot grid as the inline style of the element that pans: the CSS draws the dots, this places them. */
+export declare function dotGridStyle(view: View): {
+    backgroundSize: string;
+    backgroundPosition: string;
+};
+/** A wheel's distance in pixels, whether the device reports lines, pages, or pixels. */
+export declare function wheelPixels(delta: number, mode: number, pageSize: number): number;

package/dist/core/canvas-view.js

@@ -0,0 +1,207 @@
+import { VIEWER_MAX_ZOOM, VIEWER_MIN_ZOOM, VIEWER_PADDING } from './limits.js';
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/** How many pixels of the picture stay in the canvas however far it is dragged, so it can always be grabbed and brought back. */
+export const KEEP_PX = 96;
+/** True when a canvas and a picture both have a size to work with. Before the picture has loaded, or in a window with no layout, they do not. */
+export function hasRoom(viewport, picture) {
+    return viewport.width > 0 && viewport.height > 0 && picture.width > 0 && picture.height > 0;
+}
+/** The zoom at which the whole picture is in the canvas with some air around it. Never above 1, so a small picture stays its own size. */
+export function fitScale(viewport, picture) {
+    if (!hasRoom(viewport, picture))
+        return 1;
+    const across = Math.max(1, viewport.width - VIEWER_PADDING * 2) / picture.width;
+    const down = Math.max(1, viewport.height - VIEWER_PADDING * 2) / picture.height;
+    return Math.min(1, across, down);
+}
+/**
+ * The smallest and largest zoom. The smallest is 10 percent, or the fit zoom when a very large picture needs less than that
+ * to be seen whole, so Fit is always reachable.
+ */
+export function zoomLimits(fit) {
+    return { min: Math.min(VIEWER_MIN_ZOOM, fit), max: VIEWER_MAX_ZOOM };
+}
+/** A zoom held inside the limits. */
+export function clampScale(scale, fit) {
+    const { min, max } = zoomLimits(fit);
+    return clamp(scale, min, max);
+}
+/**
+ * Where one axis of the picture may sit: centred when it fits (or at the start, past the air, when `top` is set), else free
+ * between the two edges plus the air.
+ */
+function settle(offset, extent, size) {
+    const keep = Math.min(KEEP_PX, size, extent);
+    return clamp(offset, keep - size, extent - keep);
+}
+/** True for a canvas taller than it is wide: a phone held upright, where a centred picture would leave a gap above it. */
+export function isPortrait(viewport) {
+    return viewport.height > viewport.width;
+}
+/** A view moved inside the rules for this canvas and picture. */
+export function clampView(view, viewport, picture) {
+    if (!hasRoom(viewport, picture))
+        return view;
+    return {
+        scale: view.scale,
+        x: settle(view.x, viewport.width, picture.width * view.scale),
+        y: settle(view.y, viewport.height, picture.height * view.scale),
+    };
+}
+/** The picture at this zoom, centred in the canvas (at the top of a portrait one, when it fits down it). */
+export function centred(scale, viewport, picture) {
+    const height = picture.height * scale;
+    const top = isPortrait(viewport) && height + VIEWER_PADDING * 2 <= viewport.height;
+    return clampView({ scale, x: (viewport.width - picture.width * scale) / 2, y: top ? VIEWER_PADDING : (viewport.height - height) / 2 }, viewport, picture);
+}
+/** The picture fitted to the canvas and centred (at the top of a portrait one). */
+export function fitView(viewport, picture) {
+    return centred(fitScale(viewport, picture), viewport, picture);
+}
+/** The picture moved by `dx` and `dy` pixels. */
+export function panBy(view, dx, dy, viewport, picture) {
+    return clampView({ ...view, x: view.x + dx, y: view.y + dy }, viewport, picture);
+}
+/**
+ * The picture at a new zoom, with the spot under `point` (in canvas pixels) staying under it: zooming with the pointer
+ * over a detail keeps the detail under the pointer. The zoom is held inside the limits first.
+ */
+export function zoomAt(view, point, scale, viewport, picture) {
+    const next = clampScale(scale, fitScale(viewport, picture));
+    const ratio = next / view.scale;
+    return clampView({ scale: next, x: point.x - (point.x - view.x) * ratio, y: point.y - (point.y - view.y) * ratio }, viewport, picture);
+}
+/**
+ * The view that shows a box of the picture (in the picture's own units): unchanged when the box is already whole in the canvas,
+ * else moved, at the same zoom, so the box is in the middle. Stepping from box to box with the keyboard never leaves one out of sight.
+ */
+export function revealed(view, box, viewport, picture) {
+    const left = view.x + box.x * view.scale;
+    const top = view.y + box.y * view.scale;
+    const right = left + box.width * view.scale;
+    const bottom = top + box.height * view.scale;
+    if (left >= 0 && top >= 0 && right <= viewport.width && bottom <= viewport.height)
+        return view;
+    const middle = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+    return clampView({ ...view, x: viewport.width / 2 - middle.x * view.scale, y: viewport.height / 2 - middle.y * view.scale }, viewport, picture);
+}
+/** The largest zoom Zoom to selection goes to: close enough to read, never so close one box fills the window. */
+export const BOX_ZOOM_MAX = 2;
+/** The view that shows a box of the picture whole and centred, as large as fits up to `max` (`BOX_ZOOM_MAX`), for Zoom to selection. */
+export function boxView(box, viewport, picture, max = BOX_ZOOM_MAX) {
+    if (!hasRoom(viewport, picture) || box.width <= 0 || box.height <= 0)
+        return fitView(viewport, picture);
+    const across = Math.max(1, viewport.width - VIEWER_PADDING * 4) / box.width;
+    const down = Math.max(1, viewport.height - VIEWER_PADDING * 4) / box.height;
+    const scale = clampScale(Math.min(across, down, max), fitScale(viewport, picture));
+    const middle = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+    return clampView({ scale, x: viewport.width / 2 - middle.x * scale, y: viewport.height / 2 - middle.y * scale }, viewport, picture);
+}
+/** The middle of the canvas, where a zoom button or key zooms around. */
+export function middleOf(viewport) {
+    return { x: viewport.width / 2, y: viewport.height / 2 };
+}
+/**
+ * The view while two fingers are down. The spot of the picture that was under the fingers' midpoint when they landed stays
+ * under their midpoint as it moves, and the zoom follows the distance between them, so a pinch zooms and a drag with two
+ * fingers pans, in one gesture.
+ */
+export function pinchView(start, now, viewport, picture) {
+    const fit = fitScale(viewport, picture);
+    const ratio = start.distance > 0 ? now.distance / start.distance : 1;
+    const scale = clampScale(start.view.scale * ratio, fit);
+    const spot = { x: (start.mid.x - start.view.x) / start.view.scale, y: (start.mid.y - start.view.y) / start.view.scale };
+    return clampView({ scale, x: now.mid.x - spot.x * scale, y: now.mid.y - spot.y * scale }, viewport, picture);
+}
+/** How near the fit zoom a zoom has to be to count as fitted: a hair, so a rounding difference is not "zoomed". */
+const FIT_TOLERANCE = 0.002;
+/** True when the view is the fitted one, so a refit on resize is right and a double press means "zoom in". */
+export function isFitted(view, viewport, picture) {
+    return Math.abs(view.scale - fitScale(viewport, picture)) < FIT_TOLERANCE;
+}
+/** True when the view is the fitted view itself, at the fit zoom and in its place, not one moved away from it by a drag. */
+export function isFitView(view, viewport, picture) {
+    const fit = fitView(viewport, picture);
+    return isFitted(view, viewport, picture) && Math.abs(view.x - fit.x) < 0.5 && Math.abs(view.y - fit.y) < 0.5;
+}
+/** What a double press does: from fitted, to 100 percent (or to 200 percent when the picture already fits at 100); from anything else, back to fit. */
+export function toggledScale(view, viewport, picture) {
+    const fit = fitScale(viewport, picture);
+    if (!isFitted(view, viewport, picture))
+        return fit;
+    return fit < 1 ? 1 : 2;
+}
+/** The zoom as the whole percent a person reads. */
+export function percentOf(scale) {
+    return Math.round(scale * 100);
+}
+/** How much a wheel turn zooms: smooth for a trackpad's pinch (small steps), and capped so a mouse wheel's notch is a step, not a leap. */
+export function wheelZoomFactor(deltaY) {
+    return Math.exp(-clamp(deltaY, -60, 60) * 0.008);
+}
+/** The least a mouse notch moves in pixels. A trackpad sends many smaller events instead. */
+const MOUSE_NOTCH_PX = 40;
+/**
+ * Whether a wheel event came from a mouse's wheel rather than a two-finger swipe on a trackpad. Browsers do not say, so this reads
+ * the shape of the event: a mouse wheel reports lines or pages (`deltaMode` 1 or 2), or whole pixels in steps of a notch on one axis
+ * only. A swipe reports pixels, often fractional, often small, and often with a sideways part. A slow swipe that looks like a notch is
+ * read as a mouse and zooms, which is the safer of the two mistakes on a full-window canvas.
+ */
+export function isMouseWheel(event) {
+    if (event.deltaMode !== 0)
+        return true;
+    return event.deltaX === 0 && Number.isInteger(event.deltaY) && Math.abs(event.deltaY) >= MOUSE_NOTCH_PX;
+}
+/**
+ * What a wheel event does. Control or Command with the wheel (and a trackpad's pinch, which arrives that way) always zooms. With
+ * neither, a `zoom` canvas zooms for a mouse wheel and moves the picture for a trackpad swipe, so a trackpad can still get about;
+ * a `modifier` canvas leaves the wheel to the page.
+ */
+export function wheelIntent(event, mode) {
+    if (event.ctrlKey || event.metaKey)
+        return 'zoom';
+    if (mode === 'modifier')
+        return 'page';
+    return isMouseWheel(event) ? 'zoom' : 'pan';
+}
+/**
+ * What one turn of a mouse wheel multiplies the zoom by: proportional to how far it turned, so a notch (about 100 pixels) is close to
+ * a press of a zoom button and a fast spin is a few of them, never a leap.
+ */
+export function mouseWheelZoomFactor(deltaY) {
+    return Math.exp(-clamp(deltaY, -240, 240) * 0.0022);
+}
+/** The dot grid's step at 100 percent, in pixels: the portal's own `--canvas-step` (1.5rem). */
+export const DOT_STEP = 24;
+/** The narrowest and widest a step of the dot grid is drawn on screen. Past either, the grid halves or doubles. */
+const DOT_MIN_PX = 14;
+const DOT_MAX_PX = 40;
+/**
+ * Where the dot grid behind the picture is drawn for a view: its step on screen and its offset, so the dots move and scale with
+ * the picture like the paper it is drawn on. Zoomed far out the grid takes every second dot, and zoomed far in it adds one between,
+ * so it never turns into a grey wash or a sparse scatter.
+ */
+export function dotGrid(view) {
+    let size = DOT_STEP * (Number.isFinite(view.scale) && view.scale > 0 ? view.scale : 1);
+    while (size < DOT_MIN_PX)
+        size *= 2;
+    while (size > DOT_MAX_PX)
+        size /= 2;
+    const wrap = (offset) => ((offset % size) + size) % size;
+    return { size, x: wrap(view.x), y: wrap(view.y) };
+}
+/** The dot grid as the inline style of the element that pans: the CSS draws the dots, this places them. */
+export function dotGridStyle(view) {
+    const grid = dotGrid(view);
+    return { backgroundSize: `${grid.size}px ${grid.size}px`, backgroundPosition: `${grid.x}px ${grid.y}px` };
+}
+/** A wheel's distance in pixels, whether the device reports lines, pages, or pixels. */
+export function wheelPixels(delta, mode, pageSize) {
+    if (mode === 1)
+        return delta * 16;
+    if (mode === 2)
+        return delta * pageSize;
+    return delta;
+}

package/dist/core/fingerprint.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A picture's fingerprint: `sha256-` and the SHA-256 of its text in UTF-8, as lower-case hex. The same value an organisation embed
+ * link sends as its `ETag` (without the quotes), and what `fingerprint` pins a viewer to. Computed with Web Crypto, so it works in
+ * every browser and in Node 20 and later with nothing installed.
+ */
+/** The prefix every fingerprint starts with, naming the hash. */
+export declare const FINGERPRINT_PREFIX = "sha256-";
+/** True for a value with the shape of a fingerprint. */
+export declare function isFingerprint(value: string): boolean;
+/** The fingerprint of a picture's text. */
+export declare function fingerprintOf(text: string): Promise<string>;

package/dist/core/fingerprint.js

@@ -0,0 +1,20 @@
+/**
+ * A picture's fingerprint: `sha256-` and the SHA-256 of its text in UTF-8, as lower-case hex. The same value an organisation embed
+ * link sends as its `ETag` (without the quotes), and what `fingerprint` pins a viewer to. Computed with Web Crypto, so it works in
+ * every browser and in Node 20 and later with nothing installed.
+ */
+/** The prefix every fingerprint starts with, naming the hash. */
+export const FINGERPRINT_PREFIX = 'sha256-';
+const FINGERPRINT = /^sha256-[0-9a-f]{64}$/;
+/** True for a value with the shape of a fingerprint. */
+export function isFingerprint(value) {
+    return FINGERPRINT.test(value);
+}
+/** The fingerprint of a picture's text. */
+export async function fingerprintOf(text) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    let hex = '';
+    for (const byte of new Uint8Array(digest))
+        hex += byte.toString(16).padStart(2, '0');
+    return FINGERPRINT_PREFIX + hex;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,13 @@
+export * from './canvas-view.js';
+export { drillNodeAt, nodeAt, parsePicture, readTraceMap, traceableNodes, traceMapOf, traceOf, PATH_DATA } from './picture-map.js';
+export type { Trace, TraceBox, TraceLine, TraceMap, TraceNode, TracePath, TracedLine } from './picture-map.js';
+export { readEmbeddedSource } from './picture-source.js';
+export type { SourceReading } from './picture-source.js';
+export { drawnScheme, themeChoiceOf, withScheme } from './picture-scheme.js';
+export type { Scheme, ThemeChoice } from './picture-scheme.js';
+export { FINGERPRINT_PREFIX, fingerprintOf, isFingerprint } from './fingerprint.js';
+export { loadPicture, pictureUrl, PictureLoadError } from './picture-loader.js';
+export type { LoadFailure, LoadOptions } from './picture-loader.js';
+export { documentHost, liveIntervalOf, watchLive } from './live-watch.js';
+export type { WatchHost } from './live-watch.js';
+export * from './limits.js';

package/dist/core/index.js

@@ -0,0 +1,8 @@
+export * from './canvas-view.js';
+export { drillNodeAt, nodeAt, parsePicture, readTraceMap, traceableNodes, traceMapOf, traceOf, PATH_DATA } from './picture-map.js';
+export { readEmbeddedSource } from './picture-source.js';
+export { drawnScheme, themeChoiceOf, withScheme } from './picture-scheme.js';
+export { FINGERPRINT_PREFIX, fingerprintOf, isFingerprint } from './fingerprint.js';
+export { loadPicture, pictureUrl, PictureLoadError } from './picture-loader.js';
+export { documentHost, liveIntervalOf, watchLive } from './live-watch.js';
+export * from './limits.js';

package/dist/core/limits.d.ts

@@ -0,0 +1,19 @@
+/** The smallest zoom, 10 percent, unless a very large picture needs less to be seen whole. */
+export declare const VIEWER_MIN_ZOOM = 0.1;
+/** The largest zoom, 800 percent. */
+export declare const VIEWER_MAX_ZOOM = 8;
+/** What a zoom button or key multiplies the zoom by. */
+export declare const VIEWER_ZOOM_STEP = 1.25;
+/** How far an arrow key moves the picture, in pixels. */
+export declare const VIEWER_PAN_STEP = 64;
+/** The air around a fitted picture, in pixels. */
+export declare const VIEWER_PADDING = 24;
+/** The most text of a picture the viewer reads. The largest hosted picture is 2 MiB; a response past this is not one. */
+export declare const PICTURE_MAX_BYTES: number;
+/** How long a fetch of a picture may take before it counts as failed, in milliseconds. */
+export declare const REQUEST_TIMEOUT_MS = 15000;
+/** The default and the shortest time between two checks for a new version of a live picture, in seconds. */
+export declare const LIVE_INTERVAL_DEFAULT_S = 60;
+export declare const LIVE_INTERVAL_MIN_S = 15;
+/** How far a pointer may move between down and up and still count as a press, not a drag, in pixels. */
+export declare const PRESS_SLOP_PX = 4;

package/dist/core/limits.js

@@ -0,0 +1,19 @@
+/** The smallest zoom, 10 percent, unless a very large picture needs less to be seen whole. */
+export const VIEWER_MIN_ZOOM = 0.1;
+/** The largest zoom, 800 percent. */
+export const VIEWER_MAX_ZOOM = 8;
+/** What a zoom button or key multiplies the zoom by. */
+export const VIEWER_ZOOM_STEP = 1.25;
+/** How far an arrow key moves the picture, in pixels. */
+export const VIEWER_PAN_STEP = 64;
+/** The air around a fitted picture, in pixels. */
+export const VIEWER_PADDING = 24;
+/** The most text of a picture the viewer reads. The largest hosted picture is 2 MiB; a response past this is not one. */
+export const PICTURE_MAX_BYTES = 3 * 1024 * 1024;
+/** How long a fetch of a picture may take before it counts as failed, in milliseconds. */
+export const REQUEST_TIMEOUT_MS = 15_000;
+/** The default and the shortest time between two checks for a new version of a live picture, in seconds. */
+export const LIVE_INTERVAL_DEFAULT_S = 60;
+export const LIVE_INTERVAL_MIN_S = 15;
+/** How far a pointer may move between down and up and still count as a press, not a drag, in pixels. */
+export const PRESS_SLOP_PX = 4;

package/dist/core/live-watch.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Watching a live picture for a new version. Every `interval` seconds, and once when the page comes back into view, it calls
+ * `check`; it never checks while the page is hidden, so a tab in the background costs no request. A check that fails is skipped,
+ * and the next one tries again: a picture already shown stays shown.
+ */
+/** The interval from an `interval` attribute, in seconds: the default when it is not a number, and never below the minimum. */
+export declare function liveIntervalOf(value: string | null | undefined): number;
+/** What the watch reads from the page, so a test can stand in for it. */
+export interface WatchHost {
+    isVisible(): boolean;
+    onVisible(listener: () => void): () => void;
+    setInterval(handler: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+/** The browser's page, as a watch host. */
+export declare function documentHost(document: Document): WatchHost;
+/** Starts watching; the function it returns stops it. Two checks never overlap. */
+export declare function watchLive(host: WatchHost, intervalS: number, check: () => Promise<void>): () => void;

package/dist/core/live-watch.js

@@ -0,0 +1,49 @@
+import { LIVE_INTERVAL_DEFAULT_S, LIVE_INTERVAL_MIN_S } from './limits.js';
+/**
+ * Watching a live picture for a new version. Every `interval` seconds, and once when the page comes back into view, it calls
+ * `check`; it never checks while the page is hidden, so a tab in the background costs no request. A check that fails is skipped,
+ * and the next one tries again: a picture already shown stays shown.
+ */
+/** The interval from an `interval` attribute, in seconds: the default when it is not a number, and never below the minimum. */
+export function liveIntervalOf(value) {
+    const seconds = value === null || value === undefined || value.trim() === '' ? Number.NaN : Number(value);
+    if (!Number.isFinite(seconds))
+        return LIVE_INTERVAL_DEFAULT_S;
+    return Math.max(LIVE_INTERVAL_MIN_S, Math.round(seconds));
+}
+/** The browser's page, as a watch host. */
+export function documentHost(document) {
+    return {
+        isVisible: () => document.visibilityState === 'visible',
+        onVisible(listener) {
+            const handler = () => {
+                if (document.visibilityState === 'visible')
+                    listener();
+            };
+            document.addEventListener('visibilitychange', handler);
+            return () => document.removeEventListener('visibilitychange', handler);
+        },
+        setInterval: (handler, ms) => globalThis.setInterval(handler, ms),
+        clearInterval: (handle) => globalThis.clearInterval(handle),
+    };
+}
+/** Starts watching; the function it returns stops it. Two checks never overlap. */
+export function watchLive(host, intervalS, check) {
+    let running = false;
+    const tick = () => {
+        if (running || !host.isVisible())
+            return;
+        running = true;
+        check()
+            .catch(() => undefined)
+            .finally(() => {
+            running = false;
+        });
+    };
+    const handle = host.setInterval(tick, intervalS * 1000);
+    const stopVisible = host.onVisible(tick);
+    return () => {
+        host.clearInterval(handle);
+        stopVisible();
+    };
+}