umlimator 0.13.0 → 0.14.0

package/README.md

@@ -38,8 +38,9 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
 - **The page's pieces, embedded**: the standalone page's views list, details panel, legend and hint line, each one a
   `render()` option, around the map in the host's own page.
 - **Editing** (opt-in): gestures emit `change` events; the host applies them and calls `update()`.
-- **Export**: any view as a stand-alone SVG or PNG, in the browser or from the CLI; the whole map as one PDF, each view
-  with its text, then the legend and the rules (`umlimator.py pdf`).
+- **Export**: any view as a stand-alone SVG or PNG, in the browser or from the CLI; the whole map as one PDF to hand in
+  for a review: a cover with the contents, each view with its legend and tables of its cards, lines and boxes, then the
+  rules (`umlimator.py pdf`).
 - **In docs**: `<umlimator-map src="model.json">` in any page, and an `umlimator` fenced block in VitePress, Docusaurus,
   MkDocs or any Markdown that allows HTML.
 - **A layout check**: crossings, shared lines, detours, labels on lines, text that overflows its card.
@@ -59,7 +60,7 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
 npm install umlimator
 ```
 
-Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.13.0"`. npm 12 refuses git
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.14.0"`. npm 12 refuses git
 dependencies unless the project opts in, so that also needs `allow-git=root` in the `.npmrc` next to `package.json`.
 
 ## Embed
@@ -141,7 +142,8 @@ the map is drawn, and stay where scripts don't run ([`examples/element.html`](ex
 
 - **The model**: `src`, a URL resolved as an `<img>`'s is (a `data:` URL too), or the model in a child
   `<script type="application/json">`.
-- **Attributes**: `view`, `minimap`, `controls="false"`, `height` (a number is pixels; 480 by default, or size it in CSS)
+- **Attributes**: `view`, `minimap`, `controls="false"`, `wheel="ctrl"` (the wheel zooms only with Ctrl or ⌘, and scrolls
+  the page otherwise, as a map in a document should), `height` (a number is pixels; 480 by default, or size it in CSS)
   and `theme` (`light` or `dark`: theme.css's palette for that map, whatever the page's). Changing one draws the map
   again, and removing the element destroys it.
 - **Events**: `umlimator:select`, `umlimator:open` (cancel it to stay) and `umlimator:viewchange`, the map's event as
@@ -223,7 +225,7 @@ python3 umlimator.py record bike-share.html --story ride --out ride.png   # bike
 python3 umlimator.py import workspace.dsl --out model.json            # a diagram you have already, as a model
 docker compose config --format json > compose.json && python3 umlimator.py import compose.json --out model.json
 kubectl get deploy,sts,svc,ing -A -o json > cluster.json && python3 umlimator.py import cluster.json --out model.json
-python3 umlimator.py pdf page.html --out map.pdf                       # every view in one PDF, with its text, the legend, the rules
+python3 umlimator.py pdf page.html --out map.pdf                       # every view in one PDF: a cover, each view with its tables, the rules
 python3 umlimator.py trace model.json trace.json --view ride-end --match match.json --out model.json   # an OTLP trace kept as a numbered view
 python3 umlimator.py mcp model.json                                    # an MCP server over stdio, for an AI assistant (below)
 ```
@@ -239,16 +241,22 @@ opening the view below it; `examples/clinic.json` is `examples/clinic.dsl`, impo
 what is left out: [docs/module-api.md § Import](docs/module-api.md#import-90). Whatever the file holds that `import`
 doesn't read is listed on stderr with its line (in JSON, its path).
 
-`pdf` prints the map through Chrome's own print, A4 across: a title page, then each view on a page of its own, as a
-vector picture with its `describe()` text, then the legend and each rule, holding or broken in the views printed
-([bike-share's](https://zintaen.github.io/umlimator/examples/bike-share.pdf), as CI builds it). It takes `--views` and
-`--theme`, as `stills` does.
+`pdf` prints the map through Chrome's own print, as a document to hand in for a review
+([bike-share's](https://zintaen.github.io/umlimator/examples/bike-share.pdf), as CI builds it). A cover has the title,
+the date, the model's file, a summary line and the contents with each view's page. Each view starts a page of its own,
+under its path ("Bike share › What runs"): its picture in vectors, as large as the page allows, the legend of what it
+draws, and tables of its cards, lines and boxes, which go on over the next pages with their header row when they are
+long. The rules follow as a table, when the model has any, each holding or broken in the views printed. Every page ends in
+the title and "page N of M". It takes `--views` and `--theme`, as `stills` does, and `--paper a4|letter` (A4 is the
+default; both across).
 
 The page has breadcrumbs, a details panel per card (with the slowest path from it and what-if), ⌘K search, deep links
 (`#view=<id>&node=<id>`, `#story=<id>&step=<n>` for a story's step, and `#lens=<id>`), stories, lenses, and export. For
 scripts and tests, it keeps its map's handle on `window.umlimatorMap`: the `Handle` that `render()` returns (`setView()`,
 `highlight()`, `tour()`, `play()` ...).
-`stills` skips a view whose inputs have not changed since its last export (`--all` exports every view). Needs Python
+`stills` skips a view whose inputs have not changed since its last export (`--all` exports every view), and exits 1,
+saying why, when a view can't be exported. In `stills`, `check` and `pdf`, `--views` takes view ids, and a trailing `*`
+is a prefix; a name that matches no view is an error. A command that fails leaves its previous output as it was. Needs Python
 3.9+ (standard library only), Google Chrome or Chromium for `stills`, `check`, `record` and `pdf`, and Node 18+ for
 `diff`, `drift`, `trace` and `mcp`.
 
@@ -261,17 +269,19 @@ ffmpeg -f apng -i ride.png -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -pix_fmt yuv4
 ```
 
 On pull requests, the diff Action posts what they change in your maps: one comment with the summary and a sketch, and
-the pictures as the run's artifact.
+the pictures as the run's artifact. The comment names the commit it describes, only the run for the pull request's
+latest commit writes it, and it says so when the diff fails.
 
 ```yaml
 on: pull_request
 permissions: { contents: read, pull-requests: write }
+concurrency: { group: "maps-${{ github.event.pull_request.number }}", cancel-in-progress: true }   # one run per pull request
 jobs:
   maps:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: zintaen/umlimator@v0.13.0
+      - uses: zintaen/umlimator@v0.14.0
         with:
           models: "docs/*.json"   # optional: where the models are (default: every .json that is a map model)
 ```
@@ -296,12 +306,18 @@ claude mcp add umlimator -- python3 /path/to/umlimator.py mcp /path/to/model.jso
 | `show_view(view)` | shows a view on the page |
 | `highlight(refs, view?)` | lights cards and lines (their ids, or the Refs `paths` and `reach` give) and dims the rest |
 | `tour(cards, view?)` | a dot rides the lines through these cards |
-| `play_story(id)`, `clear()` | plays one of the model's stories; takes the highlight, the tour and the story off |
+| `play_story(id)`, `clear()` | plays one of the model's stories; takes the assistant's highlight, tour and story off |
+| `page_state()` | what each open page shows (its map's `state`: view, selection, layers, story, camera), and whether the model renders |
 
 - The read tools run the module's own functions in Node on the model file, read again at each call, so edits show up.
 - The page tools drive the map's page, which the server serves at `http://127.0.0.1:7391` (`--port N`, or another port
-  when that one is taken). Open it in a browser. Each tool says whether a page is connected, and gives the URL when none
-  is; a page that connects later shows the latest command, and a page drawn from an older model draws itself again.
+  when that one is taken). Open it in a browser.
+  - A tool answers "shown" once a page has shown it, or says why none did: the page's own error, or a tab in the
+    background that didn't finish in time. With no page open, it gives the URL.
+  - A page that opens later shows what the assistant built: the view, with the highlight on it, and a tour or story
+    still under way.
+  - The assistant's highlight is a layer of its own (`mcp`): off on another view, back on its own.
+  - A model that stops rendering keeps the last page that did, and the tools and the page say why.
 - The server listens on 127.0.0.1 only and fetches nothing, so a logo not in the cache yet keeps its card's sigil.
 
 ## Map a repo with Claude Code

package/lib/umlimator-element.d.ts

@@ -1,11 +1,13 @@
 // Types for lib/umlimator-element.js, `umlimator/element` (#92). Its header says what each attribute and event does.
 import type { Events, Handle } from './umlimator.js';
 
-/** <umlimator-map src view minimap controls theme height>: the model from `src` (a URL) or a child
+/** <umlimator-map src view minimap controls wheel theme height>: the model from `src` (a URL) or a child
  *  <script type="application/json">, drawn by render(); its other children show until the map is drawn. */
 export class UmlimatorMap extends HTMLElement {
-  /** render()'s handle once the map is drawn (each `load` event), else null. */
+  /** render()'s handle once the map is drawn (each `load` event), else null. Its `state` is the map's MapState. */
   readonly map: Handle | null;
+  /** True while a draw waits for its model (0.14.0); `map` is then still the map drawn last. `load` or `error` ends it. */
+  readonly loading: boolean;
 }
 
 declare global {

package/lib/umlimator-element.js

@@ -6,45 +6,54 @@
 
    The model comes from `src`, a URL (a data: URL too), or from a child <script type="application/json">, and render()
    draws it in the element's shadow root. The element's other children (a still, say) show until the map is drawn, and stay
-   where scripts don't run. Changing src, view, minimap or controls (controls="false" hides them) draws it again, and
-   removing the element destroys the map. height: a number is pixels (default 480px; CSS may size it instead). theme:
+   where scripts don't run. Changing src, view, minimap, controls (controls="false" hides them) or wheel draws it again,
+   and removing the element destroys the map. wheel="ctrl": the wheel zooms only with Ctrl or ⌘, and scrolls the page
+   otherwise, as a map in a document should. height: a number is pixels (default 480px; CSS may size it instead). theme:
    "light" or "dark", that map's palette from lib/umlimator-theme.css, whatever the page's; without it the map follows the
    page, a docs site's dark mode too (VitePress's html.dark, Docusaurus's html[data-theme="dark"]). The colours come from
    that file or the host's own --um-* variables; the element fetches nothing but its model.
    Events: the map's select, open and viewchange as umlimator:select, umlimator:open and umlimator:viewchange, the map's
-   event as `detail` (preventDefault() on umlimator:open keeps the view); load each time the map is drawn, error when it
-   can't be (its children show again). `el.map` is render()'s handle once drawn (toSVG(), highlight(), setView() ...),
-   else null. */
+   event as `detail` (preventDefault() on umlimator:open keeps the view); load each time the map is drawn, error (an
+   ErrorEvent, whose message says why) when it can't be, a model with no view to draw too (its children show again).
+   `el.map` is render()'s handle once drawn (toSVG(), highlight(), setView(), state ...), else null; `el.loading` is true
+   while a draw waits for its model, when el.map is still the map drawn last. An attribute set to the value it has draws
+   nothing again. */
 import { render } from './umlimator.js';
 
 const Base = globalThis.HTMLElement || class {}; // importable where there is no DOM (a docs site's server render)
 
 export class UmlimatorMap extends Base {
-  static observedAttributes = ['src', 'view', 'minimap', 'controls', 'height'];
+  static observedAttributes = ['src', 'view', 'minimap', 'controls', 'wheel', 'height'];
   map = null;
-  #drawn = 0; #due = false; #src = null; #model = null;
+  #drawn = 0; #due = false; #src = null; #model = null; #loading = false;
 
   constructor() {
     super();
     this.attachShadow({ mode: 'open' }).innerHTML = '<style>:host { display: block; height: 480px; overflow: hidden; } ::slotted(img) { display: block; max-width: 100%; max-height: 100%; }</style>'
       + '<slot></slot><div hidden style="height: 100%"></div>';
   }
+  get loading() { return this.#loading; } // a draw under way, waiting for its model (0.14.0)
   connectedCallback() { this.#soon(); }
-  disconnectedCallback() { this.#drop(); }
+  disconnectedCallback() { this.#loading = false; this.#drop(); }
   attributeChangedCallback(name, was, now) {
+    if (was === now) return; // set to the value it has: nothing to draw again (0.14.0)
     if (name === 'height') this.style.height = now == null ? '' : /^\d+(\.\d+)?$/.test(now) ? now + 'px' : now;
     else this.#soon();
   }
   #soon() { // attributes set together draw once
+    this.#loading = true;
     if (this.#due) return;
     this.#due = true;
-    queueMicrotask(() => { this.#due = false; if (this.isConnected) this.#draw(); });
+    queueMicrotask(() => { this.#due = false; if (this.isConnected) this.#draw(); else this.#loading = false; });
   }
   #drop() {
     this.map?.destroy(); this.map = null;
     const [, slot, box] = this.shadowRoot.children; slot.hidden = false; box.hidden = true;
   }
-  #fail(err) { this.#drop(); console.warn('<umlimator-map>:', err); this.dispatchEvent(new Event('error')); } // the children show again
+  #fail(err) { // the children show again, and the error event says why
+    this.#loading = false; this.#drop(); console.warn('<umlimator-map>:', err);
+    this.dispatchEvent(new ErrorEvent('error', { message: String((err && err.message) || err), error: err }));
+  }
   async #draw() {
     const n = ++this.#drawn, src = this.getAttribute('src'), get = a => this.getAttribute(a); // a later draw wins
     let model = src && src === this.#src ? this.#model : null;
@@ -59,7 +68,8 @@ export class UmlimatorMap extends Base {
         model = JSON.parse(json.textContent);
       }
     } catch (err) { if (n === this.#drawn) this.#fail(err); return; }
-    if (n !== this.#drawn || !this.isConnected) return;
+    if (n !== this.#drawn) return; // a later draw has the element
+    if (!this.isConnected) { this.#loading = false; return; }
     if (src) { this.#src = src; this.#model = model; }
     this.#drop();
     const [, slot, box] = this.shadowRoot.children; slot.hidden = true; box.hidden = false;
@@ -68,8 +78,10 @@ export class UmlimatorMap extends Base {
       if (!this.dispatchEvent(new CustomEvent('umlimator:' + t, { detail: e, bubbles: true, composed: true, cancelable: t === 'open' }))) e.preventDefault();
     }]));
     try {
-      this.map = render(box, model, { view: get('view') || undefined, minimap: this.hasAttribute('minimap') && get('minimap') !== 'false', controls: get('controls') !== 'false', on });
+      this.map = render(box, model, { view: get('view') || undefined, minimap: this.hasAttribute('minimap') && get('minimap') !== 'false', controls: get('controls') !== 'false', wheel: get('wheel') === 'ctrl' ? 'ctrl' : 'zoom', on });
     } catch (err) { return this.#fail(err); }
+    if (this.map.view == null) return this.#fail(new Error(`${src || 'the inline model'}: the model has no view to draw`)); // drawn, with nothing to see: an error, not a load (0.14.0)
+    this.#loading = false;
     this.dispatchEvent(new Event('load'));
   }
 }

package/lib/umlimator-markdown-it.js

@@ -6,11 +6,11 @@
      view: api
      ```
 
-   The block's `key: value` lines are the element's attributes (src, view, minimap, controls, theme, height); after them,
-   or instead of src, it may hold a model in JSON. An inline model goes into src as a data: URL, since VitePress compiles
-   the page as a Vue template, which drops a <script> child. A block the element can't use fails the build, where it is
-   seen. */
-const KEYS = ['src', 'view', 'minimap', 'controls', 'theme', 'height'];
+   The block's `key: value` lines are the element's attributes (src, view, minimap, controls, wheel, theme, height); after
+   them, or instead of src, it may hold a model in JSON. An inline model goes into src as a data: URL, since VitePress
+   compiles the page as a Vue template, which drops a <script> child. A block the element can't use fails the build,
+   where it is seen. */
+const KEYS = ['src', 'view', 'minimap', 'controls', 'wheel', 'theme', 'height'];
 
 /** A block's text as the element's attributes. */
 export function attrs(text) {

package/lib/umlimator.d.ts

@@ -92,14 +92,44 @@ export interface Events {
   change: Change;                                           // only with `editable`
   /** E or Alt + click on a stacked card, or the ⤡ tab of the box it unfolded into (#71): before the card unfolds in place
    *  (expanded: true) or folds back (false). view: the card's inner view, which may not be in the model yet; the card
-   *  unfolds once it is (the host loads it and calls update() right here, or later expand()). preventDefault(): no change. */
+   *  unfolds once it is: the update() that brings it unfolds the card (here or later), or expand(). preventDefault(): no change. */
   expand: { target: Extract<Ref, { type: 'node' }>; view: string; expanded: boolean; preventDefault(): void };
-  story: { story: string; step: number | null; steps: number };   // a story shows its step (0-based); step null: it ended
+  /** A story changed: it shows a step (0-based), it was paused or resumed (playing), or it ended (step null, on destroy()
+   *  too). playing (0.14.0): it goes on by itself. */
+  story: { story: string; step: number | null; steps: number; playing: boolean };
+  /** The map's state changed (0.14.0): at most once a frame, with the keys that changed since the last state event. The
+   *  camera is the exception: a pan, zoom, glide or drag is one event, once it comes to rest, and until then the event's
+   *  camera is where it last rested (handle.state reads it live). The last event, on destroy(), has destroyed: true. */
+  state: { state: MapState; changed: (keyof MapState)[] };
+  /** The lens on the map changed: lens(), or an update() whose model lacks the lens shown (lens: null). */
+  lens: { lens: string | null };
+}
+
+/** The map's state, for hosts and agents (0.14.0): handle.state, the state event, the standalone page's
+ *  window.umlimatorMap.state and <umlimator-map>'s el.map.state. Fresh on every read, frozen, and plain JSON. */
+export interface MapState {
+  view: string | null;            // shown now (null: the model has no views)
+  navigating: string | null;      // the view a move under way is going to
+  selection: Ref[];               // as `selected`
+  expanded: string[];             // as `expanded`
+  lens: string | null;
+  overlays: string[];             // the layers on the map, in stack order ('lens', 'highlight', 'replay', 'story', 'tour', a host's)
+  story: { id: string; step: number; steps: number; playing: boolean } | null;
+  tour: boolean;                  // a tour's dot is riding
+  replay: { playing: boolean } | null;   // a replay under way: playing, or paused
+  camera: { x: number; y: number; zoom: number };   // the centre in map units, and the zoom (1: actual size); a state event's: at rest
+  flow: boolean;
+  motion: 'full' | 'reduced' | 'instant';
+  gesture: 'idle' | 'dragging' | 'connecting' | 'naming';   // an edit in progress (editable maps)
+  destroyed: boolean;
 }
 
 /** Where the user dropped or placed something: a point in the view and, on a column view, its column and row. */
 export interface Hint { x: number; y: number; col?: number; row?: number }
-/** An edit the user asked for. Nothing changes until the host applies it and calls update(). */
+/** An edit the user asked for. Nothing changes until the host applies it and calls update(). The places it hints (a card
+ *  moved, reordered or added) are used only if that update's model shows the edit: the card in its new box, a new card
+ *  with its name, or, for a place alone, the card's `layout` entry written or the model unchanged. Any other update drops
+ *  them. An update back to the model before an applied move, or after it (undo, redo), puts the cards back as they were. */
 export type Change = { id: string; view: string; hint?: Hint } & (
   | { op: 'add'; kind: 'node'; label: string; container?: string }
   | { op: 'add'; kind: 'edge'; from: string; to: string; label?: string }
@@ -112,6 +142,9 @@ export interface RenderOptions {
   view?: string;                 // default: model.root, else the view with no parent
   select?: Ref | null;
   controls?: boolean;            // up / zoom / fit / 1:1 / flow buttons (default true)
+  /** 'zoom' (the default): the wheel zooms the map, and a trackpad pans it. 'ctrl': only Ctrl or ⌘ with the wheel (and a
+   *  trackpad's pinch) zooms, and the wheel otherwise scrolls the page, as a map in a document should. */
+  wheel?: 'zoom' | 'ctrl';
   minimap?: boolean;             // default false
   flow?: boolean;                // animated flow along lines (default: on unless prefers-reduced-motion)
   /** Text widths: default the host's font (--um-sans, measured on a canvas); false: a font-independent estimate. */
@@ -148,6 +181,9 @@ export interface Handle {
    *  where it was; none of it with the option `ease: false` or under prefers-reduced-motion, and an export at any point
    *  draws where things end up. */
   update(model: MapModel): void;
+  /** Shows a view, zooming in or out as a drill-down does. A request during a move takes the move to its own view (the
+   *  latest wins). Resolves true once the view shows; false for a view the model lacks (with a console warning), when a
+   *  later request supersedes it, or on destroy(). */
   setView(id: string): Promise<void> | void;
   select(ref: Ref | null): void;
   fit(): void;
@@ -175,13 +211,28 @@ export interface Handle {
   readonly view: string | null;
   readonly selection: Ref | null;   // the latest selected
   readonly selected: Ref[];          // every selected thing (Shift / Cmd / Ctrl + click adds cards), the latest last
+  /** The map's state as one snapshot (0.14.0): fresh, frozen and JSON-serializable on every read. */
+  readonly state: MapState;
+  /** The view a move is going to, while one is under way (setView(), a drill-down, up); else null. */
+  readonly navigating: string | null;
+  /** True once destroy() has run: calls then do nothing, and every promise has settled. */
+  readonly destroyed: boolean;
+  /** The animated flow along lines (the ≋ button and F), to read or set. */
+  flow: boolean;
+  /** How this map moves: 'instant' (drawn without animation, as the page's #check, #still and #shot are), 'reduced' (the
+   *  reader's setting), else 'full'. */
+  readonly motion: 'full' | 'reduced' | 'instant';
+  /** The player of the story shown, whoever started it (play(), the standalone page's Stories menu or a link), else null. */
+  readonly story: StoryPlayer | null;
   /** Sets (or, with null, removes) a named layer of marks, drawn over the picture without touching the model. Layers stack
    *  in the order first set: each property comes from the latest layer that sets it, and a card or line is as lit as its
    *  lowest level. They survive update() and setView(); ids the view doesn't show are ignored. toSVG() and toPNG() draw them. */
   overlay(name: string, layer: Overlay | null): void;
   /** The 'highlight' layer: these cards and lines lit, the rest dimmed (in place of the selection's dimming), or null to clear.
-   *  A Ref's level (0 to 1), else its distance (as reach() gives it), fades it. A chip's or badge's Ref lights its card. */
-  highlight(refs: Lit[] | null): void;
+   *  A Ref's level (0 to 1), else its distance (as reach() gives it), fades it. A chip's or badge's Ref lights its card.
+   *  layer (0.14.0): draw them as a layer of that name instead, so two owners never clear each other's (the MCP page's
+   *  assistant uses 'mcp'); null clears that layer only. */
+  highlight(refs: Lit[] | null, options?: { layer?: string }): void;
   /** Puts one of the model's lenses on the map (#94), or none with null: the 'lens' layer lights what it picks and dims the
    *  rest, on every view shown, and the view is not laid out again. With color 'owner', each lit card is ringed in its
    *  owner's tone, and a legend over the controls names them. It stays across update() and setView(); a model without the
@@ -189,8 +240,9 @@ export interface Handle {
   lens(id: string | null): boolean;
   /** The tour dot rides the line between each pair of cards in turn (either way), through each card to its next line; a card
    *  it reaches flashes, and a pair with no line between them is skipped. Resolves true at the end, false when cut short (a
-   *  new tour or replay, tour(null), a new picture of the view, destroy()). With reduced motion it resolves at once.
-   *  speed: map units a second (default 240). */
+   *  new tour or replay, tour(null), Esc on the map, a new picture of the view, destroy()). With reduced motion no dot rides:
+   *  it resolves at once, and the path is lit at rest (its cards ringed and numbered in turn, its lines glowing: the 'tour'
+   *  layer) and said, until the next tour or replay, tour(null), Esc or a new picture. speed: map units a second (default 240). */
   tour(path: string[] | null, options?: { speed?: number }): Promise<boolean>;
   /** Plays a trace: each call from one card to another (a span and its parent's) runs along their line at the trace's relative
    *  time; the line glows while the call lasts and keeps its duration as a label (the 'replay' layer, until stop() or the next
@@ -200,8 +252,11 @@ export interface Handle {
   /** Tells one of the model's stories (#69): each step in turn sets the view, camera, selection, highlight and caption
    *  (drawn in a bar on the map and said to screen readers), then plays its tour. auto (default true): the next step
    *  follows once a step's duration is up and its tour has ended. step: where to start (0-based). The bar and the keys
-   *  (← → PageUp PageDown, Esc) step through and stop it. null when the model has no story `id` with steps. */
-  play(id: string, options?: { step?: number; auto?: boolean }): StoryPlayer | null;
+   *  (← → PageUp PageDown, Esc) step through and stop it. The reader taking the map (a press, a key, a view or a selection
+   *  the story didn't make) pauses it, and a pause holds the step's tour too, until resume(). A step folds back the cards
+   *  unfolded on its view first, and its highlight is its own 'story' layer, which dims alone while the step shows.
+   *  null when the model has no story `id` with steps, and the story shown, if any, plays on; play(null) stops it. */
+  play(id: string | null, options?: { step?: number; auto?: boolean }): StoryPlayer | null;
   destroy(): void;
 }
 
@@ -215,9 +270,11 @@ export interface StoryStep {
   camera?: 'fit' | { x: number; y: number; zoom?: number } | { card: string; zoom?: number }; duration?: number;
 }
 /** A story being told. step: the one shown (0-based). next() past the last step ends it (done: true); stop() closes it
- *  (done: false). */
+ *  (done: false). state (0.14.0): entering a step (its view, camera, selection and highlight on their way), playing or paused
+ *  on it, then ended or stopped. */
 export interface StoryPlayer {
   readonly story: string; readonly step: number; readonly steps: number; readonly playing: boolean; readonly done: Promise<boolean>;
+  readonly state: 'entering' | 'playing' | 'paused' | 'ended' | 'stopped';
   next(): void; prev(): void; pause(): void; resume(): void; stop(): void;
 }