umlimator 0.12.1 → 0.14.0

package/lib/umlimator.d.ts

@@ -13,6 +13,8 @@ export interface MapModel {
   rules?: Rule[];
   /** Narrated walk-throughs of the map (#69): handle.play(id), the standalone page's Stories menu, umlimator.py record. */
   stories?: Story[];
+  /** Saved ways to look at the map (#94): handle.lens(id), the standalone page's Lenses menu and #lens=<id>. */
+  lenses?: Lens[];
   [key: string]: unknown;
 }
 /** A badge: its text, and optionally a palette name for its colour (green, amber, rose, accent, violet ... : --um-<tone>). */
@@ -25,6 +27,8 @@ export interface MapNode {
   opensView?: string;
   /** The number on the ⤢ badge of a card whose view is not loaded yet (else ⤢ alone). A loaded view's cards are counted. */
   opensCount?: number;
+  /** Who owns the card (a team, say): selectors pick by it, and a lens with color 'owner' rings the card in its owner's tone. */
+  owner?: string;
   [key: string]: unknown;
 }
 /** What a line means, drawn as its colour: calls (the default), feeds (hands work on), triggers (suggests, offers, fires),
@@ -52,6 +56,10 @@ export interface MapEdge {
   change?: 'added' | 'removed' | 'changed';
   /** What drift() found: undrawn (traffic ran on it, nobody drew it) or idle (drawn, carried nothing). */
   drift?: 'undrawn' | 'idle';
+  /** Budgets (#95), which critical() sums along a path: how long the call takes, in ms, and what it costs, in any unit.
+   *  Not drawn. */
+  latency?: number;
+  cost?: number;
   [key: string]: unknown;
 }
 export interface MapView {
@@ -84,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 }
@@ -104,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. */
@@ -115,6 +156,20 @@ export interface RenderOptions {
   /** update() eases into the next model: moved cards glide, new ones fade in, removed ones fade out (#67). Default true;
    *  never under prefers-reduced-motion. false draws the next model at once. */
   ease?: boolean;
+  /** The standalone page's pieces (#99), each on its own or any mix, all off by default. They are drawn inside the map's
+   *  element, around the canvas, with the page's look, keys and --um-* colours; update() and destroy() keep them in step.
+   *  nav: the views list (Miller columns) left of the map, opened and shut by its ☰ button or O; picking a view shows it
+   *  (viewchange). It comes after the map in the tab order, so focus given to the map's element still lands on the map. */
+  nav?: boolean;
+  /** The kinds of cards and lines the view draws, in a box over the map, bottom left, that folds away. */
+  legend?: boolean;
+  /** A line over the map's foot: what the pointer does, and for a while what just happened (a polite live region). */
+  hints?: boolean;
+  /** The selected card's details under the map: its kind, actions and tabs (when, what, how, an example, what it comes
+   *  from and leads to), [ and ] between tabs. Open and Unfold here emit open and expand as the canvas does; → ← ⇄ light
+   *  what the card leads to, what leads to it, and every path between two selected cards (> < P); ⏱ ¤ the slowest and the
+   *  costliest path where the view's lines have latency or cost, and ⊘ what loses its way if the card goes down (#95). */
+  details?: boolean;
   on?: { [K in keyof Events]?: (e: Events[K]) => void };
 }
 
@@ -126,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;
@@ -153,17 +211,38 @@ 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
+   *  lens takes it off. False when the model has no lens `id`. */
+  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
@@ -173,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;
 }
 
@@ -188,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;
 }
 
@@ -239,9 +323,16 @@ export interface CheckIssue { message: string; targets: Ref[] }
  *  it measures in the DOM (text overflowing its card, titles, edge labels on cards or each other). In Node, text widths
  *  are an estimate unless `measure` is given, so the layout, and what is found, can differ from a browser's. */
 export function check(model: MapModel, viewId: string, options?: { repair?: boolean; measure?: (text: string, px: number) => number; expand?: string[] }): CheckIssue[];
-/** Picks cards by id, kind (as the map draws it: "db" picks databases) or box (at any depth), each a value or a list;
- *  every key given must hold, and `not` turns a selector round. A line's end on a box is that box: in it, of no kind. */
-export interface Selector { id?: string | string[]; kind?: string | string[]; container?: string | string[]; not?: Selector }
+/** Picks cards by id, kind (as the map draws it: "db" picks databases), box (at any depth) or owner, each a value or a
+ *  list; every key given must hold, and `not` turns a selector round. A line's end on a box is that box: in it, of no kind
+ *  and no owner. */
+export interface Selector { id?: string | string[]; kind?: string | string[]; container?: string | string[]; owner?: string | string[]; not?: Selector }
+/** A lens's pick: a Selector, and `line`, line kinds. Without `line` it lights the cards it picks and the lines between two
+ *  of them; with `line`, the lines of those kinds between two cards the rest of it picks, and their ends. */
+export interface LensSelector extends Selector { line?: WireKind | WireKind[] }
+/** A saved way to look at the map (#94): what `pick` picks lit, the rest dimmed (a pick left out lights everything);
+ *  color 'owner' rings each lit card in its owner's tone, with a legend. */
+export interface Lens { id: string; title?: string; pick?: LensSelector; color?: 'owner' }
 /** What the model says must hold (`model.rules`): no line from the cards `from` picks to the cards `to` picks (a side left
  *  out picks every card), or, with noCycles, no boxes that reach each other through their lines (a line counts between
  *  the two boxes that hold its ends right under the box they share). A rule that names a box (a container, or a box's
@@ -261,6 +352,20 @@ export function reach(model: MapModel, viewId: string, from: string, options?: {
 export function describe(model: MapModel, viewId: string): string;
 /** The spans of an OpenTelemetry trace in OTLP JSON (resourceSpans), as replay() takes them. */
 export function otlpSpans(otlp: unknown): Span[];
+/** The path along a view's lines with the highest total of `by` (#95): latency (ms, the default) or cost, summed over its
+ *  lines (a line without one counts 0), from `from` to `to` (either left out: any card), never coming back to a card. Its
+ *  cards in order, then its lines, as Refs for highlight(); no refs and 0 when no line leads there. No browser needed. */
+export function critical(model: MapModel, viewId: string, options?: { from?: string; to?: string; by?: 'latency' | 'cost' }): { refs: Ref[]; total: number };
+/** What taking cards out of a view would cost (#95), with the model left as it is. unreachable: what loses its way to them
+ *  (backward, as reach() finds it: for calls, what depends on them), each with its distance from the nearest, the cards
+ *  themselves at 0. No rule breaks: rules only forbid lines and cycles, which taking cards out never adds. No browser needed. */
+export function whatIf(model: MapModel, viewId: string, options: { remove: string[] }): { unreachable: (Ref & { distance: number })[] };
+/** A trace kept as a numbered view (#96): `model` with a sequence view (render: "sequence") whose steps are the trace's calls
+ *  between cards (a span and its parent's), in time order, each line labelled with its span's name and its duration under
+ *  it. A span's service is a card as replay() matches it (match, else id, else label in any case); the caption names the
+ *  services with no card. The view (id `view`, default "trace") replaces one with that id, else comes last, under the
+ *  view that shows the most of its cards. The model passed in is not changed. */
+export function sequenceFromTrace(model: MapModel, spans: Span[], options?: { view?: string; match?: Record<string, string>; title?: string }): MapModel;
 /** What changed from one model to the next (#66), as one model to draw: `after`, with each card marked added, changed or
  *  removed (`change`: a NEW or CHANGED tab; REMOVED is faded, dashed and struck through) and each line likewise (`style`
  *  added or removed; a changed one `edited`); what left comes back in its views, boxes and places, and a card put into