@phin-tech/dottie 0.7.0 → 0.9.0

package/dist/types/clicks.d.ts

@@ -13,6 +13,7 @@ export type Click = ({
 }) & {
     set?: Record<string, boolean>;
     toggle?: string[];
+    reset?: true;
 };
 /** The marker called `name`: an exact match, else one that differs only in case. */
 export declare function sceneNamed(name: string, markers: Marker[]): number;

package/dist/types/compile.d.ts

@@ -1,5 +1,5 @@
 import type { Face } from "./metrics.ts";
-/** What follows the runtime; DOTTIE_DATA and DOTTIE_OPTIONS are replaced with JSON. Plain ES5, unminified. */
+/** What follows the runtime; DOTTIE_DATA, DOTTIE_OPTIONS and DOTTIE_FONTS are replaced with JSON. Plain ES5, unminified. */
 export declare const LOADER = ";(function () {\n  var data = DOTTIE_DATA, options = DOTTIE_OPTIONS, fonts = DOTTIE_FONTS;\n  var script = document.currentScript;\n  if (window.Dottie.addFonts) window.Dottie.addFonts(Object.keys(fonts), fonts);\n  function attr(el, name, value) { el.setAttribute(name.replace(/[A-Z]/g, function (c) { return \"-\" + c.toLowerCase(); }), value); }\n  function mount() {\n    var player = document.createElement(\"dottie-player\"), k;\n    for (k in options) attr(player, k, options[k]);\n    if (script) for (k in script.dataset) if (k !== \"target\") attr(player, k, script.dataset[k]);\n    var target = script && script.dataset.target ? document.querySelector(script.dataset.target) : null;\n    if (target) target.appendChild(player);\n    else if (script && script.parentNode && script.parentNode !== document.head) script.parentNode.insertBefore(player, script);\n    else document.body.appendChild(player);\n    player.setFile(window.Dottie.parseDottie(data));\n  }\n  if (document.readyState === \"loading\" && (!script || script.parentNode === document.head || script.dataset.target)) {\n    document.addEventListener(\"DOMContentLoaded\", mount);\n  } else {\n    mount();\n  }\n})();\n";
 export interface CompileOptions {
     /** Page name or 1-based number; only that page goes in. The first page by default. */

package/dist/types/connector.d.ts

@@ -24,5 +24,9 @@ export declare function arrowhead(tip: Point, from: Point, size: number): [Point
 export declare function connectorBounds(e: Element, index: Index): Rect;
 /** Point halfway along the route, where a label sits. */
 export declare function midpoint(e: Element, index: Index): Point;
+/** Each element by id, the first with an id winning. Kept per elements array, so every follow, trace and render of
+ * one frame shares it; checked against the array's members each time, so a page changed in place is indexed anew. */
+/** Whether `index` is the one `indexOf` last built for this page's elements (without checking them again). */
+export declare function isIndexOf(page: Page, index: Index): boolean;
 export declare function indexOf(page: Page): Index;
 export { angle };

package/dist/types/flows.d.ts

@@ -0,0 +1,28 @@
+import type { Page, RGBA } from "./model.ts";
+export declare const DEFAULT_EVERY = 0.5, DEFAULT_SPEED = 160, DEFAULT_SIZE = 12;
+export declare const DEFAULT_COLOR: RGBA;
+export declare const clamp: (v: number | null, fallback: number, lo: number, hi: number) => number;
+/** The id of a flow's packet `k`: the flow's id with its last twelve digits standing for `k` (Flow.packetID). */
+export declare function packetID(flow: string, k: number): string;
+/** Every shape traffic from `from` can reach in `frame`, with the cheapest way to each:
+ * by the connectors' cost (1 each unless set), ties to the shape reached first, earlier connectors first.
+ * With `until`, the search stops once that shape is settled: its way is final then, and it is the first goal of any
+ * list it heads, but the tree holds only the shapes settled before it. */
+export declare function flowTree(from: string, frame: Page, offline?: Set<string>, until?: string): FlowTree | null;
+export declare class FlowTree {
+    settled: Set<string>;
+    came: Map<string, {
+        from: string;
+        via: string;
+        back: boolean;
+    }>;
+    readonly from: string;
+    constructor(from: string);
+    /** The first of `to` that can be reached; with `spread`, when the first can't be, every other one that can. */
+    goals(to: string[], spread: boolean): string[];
+    /** The connectors to `goal`, as [connector, backwards] hops. */
+    hops(goal: string): [string, boolean][];
+}
+/** The connectors traffic takes from `from` to the first of `to` it reaches in `frame`, as [connector, backwards]
+ * hops; null when none can be reached. */
+export declare function flowRoute(from: string, to: string[], frame: Page, offline?: Set<string>): [string, boolean][] | null;

package/dist/types/index.d.ts

@@ -20,4 +20,4 @@ export interface RenderOptions {
 /** One page of a drawing as an SVG document, as Dottie's own SVG export draws it. */
 export declare function render(source: string | DottieFile | unknown, options?: RenderOptions): string;
 /** The library's version. */
-export declare const VERSION = "0.7.0";
+export declare const VERSION = "0.9.0";

package/dist/types/measure.d.ts

@@ -0,0 +1,73 @@
+import type { Element, Flow, Gauge, Page, RGBA } from "./model.ts";
+import { type MetricTerm } from "./state.ts";
+/** A connector's or shape's metrics in one frame (ElementMetrics). */
+export interface ElementMetrics {
+    throughput: number;
+    load: number | null;
+    delay: number;
+    backlog: number;
+    inFlight: number;
+    depth: number;
+}
+/** A flow's metrics in one frame (FlowMetrics). */
+export interface FlowMetrics {
+    volume: number;
+    placed: number;
+    backlog: number;
+    backup: number;
+    transit: number | null;
+}
+/** Every metric of one frame (FrameMetrics). */
+export interface FrameMetrics {
+    elements: Map<string, ElementMetrics>;
+    flows: Map<string, FlowMetrics>;
+    carry: Record<string, number>;
+}
+export declare const emptyMetrics: () => FrameMetrics;
+/** `metric` of the element or flow `id`, or null when it has none. */
+export declare function metricValue(m: FrameMetrics, metric: string, id: string): number | null;
+/** A shape's delay as traffic feels it: 0...3600 seconds. */
+export declare function delayOf(e: Element): number;
+/** The key of a flow's queue at a shape in `FrameMetrics.carry` and `carried` (DottieDocument.queueKey). */
+export declare const queueKey: (shape: string, flow: string) => string;
+/** The packets the page's flows draw in `frame` (the page posed at `t`), with these values (null: every flow runs),
+ * and the frame's metrics. `since` is the seconds since the page's state last changed
+ * (null: `t`), and `carried` how much each flow's queue held at that moment: since then a queue grows by its
+ * backlog, or drains at the room its way on has left. */
+export declare function flowFrame(flows: Flow[] | null, frame: Page, t: number, values: Record<string, boolean> | null, offline?: Set<string>, sinceChange?: number | null, carried?: Record<string, number>): {
+    packets: Element[];
+    metrics: FrameMetrics;
+};
+/** The frame's metric for a condition's comparison: its target an element's anchor, or an element's or flow's id. */
+export declare function metricLookup(m: FrameMetrics, frame: Page): (t: MetricTerm, own: string | null) => number | null;
+/** What finishing does to one element: which of its overrides that compare metrics hold (their looks apply, in
+ * order), and, for a gauge, the reading it shows. */
+export interface Finish {
+    applied: number[];
+    gauge: {
+        value: number | null;
+    } | null;
+}
+/** For each of `elements`, the overrides that compare metrics that hold and the reading a gauge shows (easing, over
+ * `GAUGE_EASE` seconds since the state changed, from its reading then, `carried`); with no values ("all", the
+ * editor), nothing. The readings come back to carry over. */
+export declare function finishPlan(elements: Element[], metrics: FrameMetrics, values: Record<string, boolean> | null, frame: Page, since?: number, carried?: Record<string, number>): {
+    plan: Finish[];
+    readings: Record<string, number>;
+};
+/** `elements` with the looks of overrides that compare metrics applied, and gauges drawn as plain elements; with
+ * no values ("all", the editor), both are left as they are (`finishPlan`). */
+export declare function finishing(elements: Element[], metrics: FrameMetrics, values: Record<string, boolean> | null, frame: Page, flows: Flow[], since?: number, carried?: Record<string, number>): {
+    elements: Element[];
+    readings: Record<string, number>;
+};
+/** The key of a gauge's reading in `FrameMetrics.carry` and `carried` (DottieDocument.gaugeKey). */
+export declare const gaugeKey: (id: string) => string;
+export declare const GAUGE_GREEN: RGBA, GAUGE_AMBER: RGBA, GAUGE_RED: RGBA;
+export declare const GAUGE_BLUE: RGBA, GAUGE_TRACK: RGBA, GAUGE_GRAY: RGBA;
+/** A metric's value as a gauge shows it: a percentage for load and backup, seconds for transit and delay. */
+export declare function formatted(metric: string, v: number | null): string;
+/** `v` to `places` decimals, halves away from zero, trailing zeros dropped (DottieDocument.number). */
+export declare function formatNumber(v: number, places: number): string;
+/** A gauge drawn: its frame as a `.path` carrying the label, then the bar or dial. */
+export declare function gauge(e: Element, g: Gauge, value: number | null, frame: Page, flows: Flow[]): Element[];

package/dist/types/model.d.ts

@@ -55,6 +55,8 @@ export interface ConnectorData {
     waypoints: StrokePoint[] | null;
     /** Hops where the line crosses a connector drawn beneath it. */
     hops: boolean | null;
+    /** What a flow's traffic pays to take this connector (ADR 0002); null is 1. */
+    cost: number | null;
 }
 export interface PathSubpath {
     closed: boolean;
@@ -75,8 +77,31 @@ export interface ClickAction {
     url: string | null;
     set: Record<string, boolean> | null;
     toggle: string[] | null;
+    /** Puts every page variable back to its starting value first. */
+    reset?: boolean | null;
 }
 /** How a clickable element looks under the pointer or with keyboard focus; null keeps its own. */
+/** A change to an element while `when` holds (StateOverride): a field left null keeps the element's own. */
+export interface StateOverride {
+    when: string;
+    stroke: RGBA | null;
+    fill: RGBA | null;
+    textColor: RGBA | null;
+    /** Multiplies the element's opacity. */
+    opacity: number | null;
+    strokeWidth: number | null;
+    dash: DashStyle | null;
+    text: string | null;
+    /** Connector ids (uppercase) to the connectors a following element takes instead. */
+    reroute: Record<string, string> | null;
+    /** Still drawn, but carries no flow traffic. */
+    offline: boolean | null;
+    /** A connector's cost for flow traffic meanwhile. */
+    cost: number | null;
+    /** Its capacity and delay meanwhile (ADR 0003). */
+    capacity: number | null;
+    delay: number | null;
+}
 export interface HoverLook {
     stroke: RGBA | null;
     fill: RGBA | null;
@@ -110,6 +135,8 @@ export interface Element {
     hover: HoverLook | null;
     /** A condition on the page's variables: drawn only while it holds (Element.when; see state.ts). */
     when: string | null;
+    /** Changes to the element while a condition holds, in order (Element.overrides; see state.ts). */
+    overrides: StateOverride[] | null;
     /** For a `symbol` element: the page's symbol it shows, how it plays it, and from how far in. */
     symbol: string | null;
     playback: SymbolPlayback | null;
@@ -131,6 +158,23 @@ export interface Element {
         height: number;
     } | null;
     extension?: ExtensionRef | null;
+    /** The most flow volume it carries, and a shape's delay in seconds (ADR 0003). */
+    capacity?: number | null;
+    delay?: number | null;
+    /** A shape that is a queue: backlog waits at the nearest one before whatever is full. */
+    queue?: boolean | null;
+    /** Shows a metric; drawn as plain paths and a label when the page is posed (metrics.ts). */
+    gauge?: Gauge | null;
+}
+/** A metric shown in an element's frame (Gauge, ADR 0003). */
+export interface Gauge {
+    metric: string;
+    of: string;
+    max: number | null;
+    warn: number | null;
+    alarm: number | null;
+    style: "number" | "bar" | "dial" | null;
+    label: string | null;
 }
 export interface Layer {
     id: string;
@@ -210,6 +254,28 @@ export interface Page {
     symbols: Symbol[] | null;
     /** The page's variables and their starting values (DottieDocument.variables). */
     variables: Record<string, boolean> | null;
+    /** Traffic routed over the connectors drawn in each frame (DottieDocument.flows; see flows.ts). */
+    flows: Flow[] | null;
+}
+/** Traffic from one shape to the first of `to` it can reach (Flow, ADR 0002). Numbers left null take defaults. */
+export interface Flow {
+    id: string;
+    from: string;
+    to: string[];
+    every: number | null;
+    speed: number | null;
+    color: RGBA | null;
+    size: number | null;
+    when: string | null;
+    /** When the first destination can't be reached, deal packets across every other one that can. */
+    spread: boolean | null;
+    /** How much it carries (ADR 0003); null is 1. */
+    volume: number | null;
+    /** Its volume while a condition holds, the last that holds winning. */
+    overrides?: {
+        when: string;
+        volume: number | null;
+    }[] | null;
 }
 /** A drawing defined once on a page and placed by `symbol` elements, with its own timeline (Symbol). */
 export interface Symbol {

package/dist/types/planner.d.ts

@@ -0,0 +1,12 @@
+import type { Page } from "./model.ts";
+/** Frames times elements below which planning in place is quicker than starting a worker. */
+export declare const WORKER_WORK = 30000;
+/** Roughly how much resolving every frame of `page` takes: none with a camera, which plans without resolving. */
+export declare function planWork(page: Page): number;
+/** Whether `page` is worth planning in a worker, and one can be had. */
+export declare function plansInWorker(page: Page): boolean;
+/** Plans `page` in the worker; when it resolves, `plan(page)` returns that plan at once. On any failure it resolves
+ * all the same, and `plan(page)` then plans in place. */
+export declare function planInWorker(page: Page): Promise<void>;
+/** In a worker started by `planInWorker`, answers its requests. Elsewhere it does nothing. */
+export declare function servePlans(): void;

package/dist/types/player.d.ts

@@ -14,6 +14,14 @@ export declare class Playback {
     readonly sceneLoops: boolean[];
     /** The page's variables now: their starting values until clicks change them. */
     state: Record<string, boolean>;
+    /** When the variables last changed (performance.now() milliseconds): backlog piles up from then (ADR 0003). */
+    stateSince: number;
+    /** A still (the `at` attribute): backlog is drawn for the page time, not the wall clock. */
+    still: boolean;
+    /** What each queue held when the variables last changed, which it drains from (FrameMetrics.carry). */
+    carried: Record<string, number>;
+    /** Seconds since the variables last changed, or null for a still. */
+    sinceChange(now?: number): number | null;
     readonly background: RGBA;
     readonly ink: RGBA;
     /** What clicking each clickable element does, by element id. */
@@ -31,7 +39,10 @@ export declare class Playback {
     private overTimes;
     private downTimes;
     private hitTimes;
-    private last;
+    last: {
+        t: number;
+        i: number;
+    };
     private svg;
     private groups;
     private order;
@@ -90,6 +101,10 @@ export declare class DottiePlayer extends ElementBase {
     private raf;
     private replayRaf;
     private loadToken;
+    /** Counts mounts, so a plan that comes back from a worker after a newer one is dropped. */
+    private mountToken;
+    /** The time a still shows; null while the drawing is animated. */
+    private stillTime;
     private visible;
     private observer;
     constructor();
@@ -100,8 +115,13 @@ export declare class DottiePlayer extends ElementBase {
     load(): Promise<void>;
     /** Shows an already-parsed file. */
     setFile(file: DottieFile): void;
+    private showFile;
+    /** Shows the file's page; then `mounted`. A big animation is planned in a worker first (planner.ts), and what was
+     * showing stays until it is ready; a newer mount, file or failed load in the meantime wins. */
     private mount;
+    private mountPage;
     get paused(): boolean;
+    /** The moment shown: a still's own time (its `at`, or the poster), else the current frame's. */
     get currentTime(): number;
     set currentTime(t: number);
     get duration(): number;

package/dist/types/sim-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/state.d.ts

@@ -1,12 +1,25 @@
-import type { ClickAction, Page } from "./model.ts";
+import { type ClickAction, type Element, type Page, type StateOverride } from "./model.ts";
 /** Whether `name` can name a variable: a letter or underscore, then letters, digits and underscores. */
 export declare function isName(name: string): boolean;
-/** The variable names `condition` reads, or null when it isn't one: names, each optionally after `!`, joined by
- * `&&` and `||` (`&&` binds tighter). */
+/** The metrics a condition can compare (ADR 0003), as `load(workers) > 0.9`. */
+export declare const METRIC_NAMES: string[];
+/** A comparison of a metric in a condition (PageState.MetricTerm). */
+export interface MetricTerm {
+    metric: string;
+    target: string;
+    op: string;
+    value: number;
+}
+/** `term` (trimmed) read as a metric comparison, or null. */
+export declare function metricTerm(term: string): MetricTerm | null;
+/** Whether `condition` compares a metric anywhere. */
+export declare function mentionsMetric(condition: string): boolean;
+/** The variable names `condition` reads, or null when it isn't one: names, each optionally after `!`, or metric
+ * comparisons, joined by `&&` and `||` (`&&` binds tighter). */
 export declare function conditionNames(condition: string): string[] | null;
-/** Whether `condition` holds with these values. A missing variable is false; a condition that can't be read never
- * holds. */
-export declare function holds(condition: string, state: Record<string, boolean>): boolean;
+/** Whether `condition` holds with these values, and `metric` giving the frame's metrics. A missing variable is
+ * false, and so is a comparison whose metric can't be had; a condition that can't be read never holds. */
+export declare function holds(condition: string, state: Record<string, boolean>, metric?: ((m: MetricTerm) => number | null) | null): boolean;
 /** Which elements a page shows as far as its variables go: their starting values ("initial"), these values (a
  * missing one takes its starting value), or every element ("all"). */
 export type StateChoice = "initial" | "all" | Record<string, boolean>;
@@ -14,7 +27,14 @@ export type StateChoice = "initial" | "all" | Record<string, boolean>;
 export declare function stateValues(page: Page, choice: StateChoice): Record<string, boolean> | null;
 /** The ids of the elements whose `when` doesn't hold under `choice`. */
 export declare function stateHidden(page: Page, choice: StateChoice): Set<string>;
+/** The overrides of `e` that hold under `values`, in order; none for null ("all", the editor). */
+export declare function activeOverrides(e: Element, values: Record<string, boolean> | null): StateOverride[];
+/** Only what an override comparing metrics may change: its looks (ADR 0003). */
+export declare function looksOnly(o: StateOverride): StateOverride;
+/** `e` with `o` applied (StateOverride.apply): opacity multiplies, the rest replaces. */
+export declare function applyOverride(o: StateOverride, e: Element): Element;
 /** Whether a click sets or flips a variable. */
 export declare function changesState(c: ClickAction | null): boolean;
-/** `state` after the click: its `set` values, then each `toggle` flipped (a missing variable starts false). */
-export declare function applyClick(c: ClickAction, state: Record<string, boolean>): Record<string, boolean>;
+/** `state` after the click: the starting values (`initial`) back if it resets, then its `set` values, then each
+ * `toggle` flipped (a missing variable starts false). */
+export declare function applyClick(c: ClickAction, state: Record<string, boolean>, initial?: Record<string, boolean>): Record<string, boolean>;

package/dist/types/svg.d.ts

@@ -17,6 +17,12 @@ export interface Plan {
 /** What an animation shows over time (Exporter.animation): with a camera, its view at each frame, widened to
  * the first key's shape; without, the bounds of the whole animation for every frame. */
 export declare function plan(page: Page): Plan;
+/** Whether `plan(page)` would return at once. */
+export declare function hasPlan(page: Page): boolean;
+/** Has `plan(page)` return `made`, a plan of this page made elsewhere (in a worker, planner.ts). */
+export declare function rememberPlan(page: Page, made: Plan): void;
+/** Whether `page` still holds exactly the fields it had when `fields` was copied from it. */
+export declare function unchanged(page: Page, fields: Page): boolean;
 /** The opening `<svg>` tag for `b`, with the page color behind everything when `paint`. */
 export declare function svgOpen(b: Rect, background: RGBA | null, paint: boolean): string;
 export interface Part {
@@ -25,8 +31,9 @@ export interface Part {
 }
 /** The SVG for each thing drawn, back to front, keyed by element id (rock hatching as "rock"). With `links`, an
  * element whose click or `url` is a web address is wrapped in an `<a>` that opens it, the click's first (the players
- * make their own clickable groups). */
-export declare function svgParts(page: Page, background: RGBA | null, fixed?: Rect, links?: boolean): {
+ * make their own clickable groups). With `only`, just the parts whose keys it accepts, drawn as they are on the
+ * whole page (connectors still meet and hop the rest). */
+export declare function svgParts(page: Page, background: RGBA | null, fixed?: Rect, links?: boolean, only?: (key: string) => boolean): {
     bounds: Rect;
     parts: Part[];
 };

package/dist/types/symbols.d.ts

@@ -1,4 +1,4 @@
-import { type Page, type Symbol, type SymbolPlayback } from "./model.ts";
+import { type Element, type Page, type Symbol, type SymbolPlayback } from "./model.ts";
 /** The deepest instances nest, and the most elements expanding one page may make (Symbol.maxDepth, .maxElements). */
 export declare const MAX_DEPTH = 8;
 export declare const MAX_ELEMENTS = 20000;
@@ -15,9 +15,25 @@ export declare function filled(s: Symbol, args: Record<string, string> | null):
 /** The symbol as a page of its own (Symbol.page). */
 export declare function symbolPage(s: Symbol): Page;
 export declare function hasInstances(page: Page): boolean;
+/** What each instance on a page expanded into, kept so that expanding the same page again at the same moment with
+ * a few instances' times changed (a button's other states) redoes only those. */
+export declare class Expansions {
+    readonly page: Page;
+    readonly t: number;
+    readonly posing: boolean;
+    /** For each instance: its time override, the budget it found and left, and what it made. */
+    readonly made: Map<Element, {
+        override: number | undefined;
+        before: number;
+        after: number;
+        out: Element[];
+    }>;
+    constructor(page: Page, t: number, posing: boolean);
+}
 /** The page with every instance replaced by what it shows at page time `t` (DottieDocument.expandingSymbols). `times`
- * puts instances on the page at a moment of their symbol's own: a button's other states, or a clip replaying. */
-export declare function expandingSymbols(page: Page, t: number, posing?: boolean, times?: Map<string, number>): Page;
+ * puts instances on the page at a moment of their symbol's own: a button's other states, or a clip replaying.
+ * `memo` records what each instance made, or, made for this page and moment, reuses it where nothing differs. */
+export declare function expandingSymbols(page: Page, t: number, posing?: boolean, times?: Map<string, number>, memo?: Expansions): Page;
 export declare function symbolTable(page: Page): Map<string, Symbol>;
 /** The id an element of a symbol has inside instance `instance` (DottieDocument.derivedID). */
 export declare function derivedID(instance: string, inner: string): string;

package/dist/types/timeline.d.ts

@@ -1,6 +1,8 @@
+import { type Index } from "./connector.ts";
 import { type Ease, type Element, type Follow, type Page, type Timeline, type Track } from "./model.ts";
 import { Polyline, type Point, type Rect } from "./path.ts";
 import { type StateChoice } from "./state.ts";
+import { type FrameMetrics } from "./measure.ts";
 export declare function applyEase(ease: Ease, u: number): number;
 /** The time inside the track's own keys that `t` plays (repeats folded back). */
 export declare function localTime(track: Track, t: number): number;
@@ -12,8 +14,9 @@ export declare function isVisible(track: Track, t: number): boolean;
 export declare function applyTrack(track: Track, e: Element, t: number): Element;
 /** The path span placing the element at `t`, unless an x or y key after it has taken the element back. */
 export declare function followSpan(track: Track, t: number): Follow | null;
-/** The clean route of a connector, or the clean, rotated outline of any other element. */
-export declare function tracing(e: Element, page: Page): Polyline;
+/** The clean route of a connector, or the clean, rotated outline of any other element. `index` is the page's,
+ * passed by callers that already have it. */
+export declare function tracing(e: Element, page: Page, index?: Index): Polyline;
 /** `e` moved onto the path it is following at `t`, if any. `page` has every key applied. */
 export declare function following(track: Track, e: Element, t: number, page: Page): Element;
 /** Where the dashes of a line marching at `speed` stand at `t`, within one pattern `period` (Timeline.marchOffset):
@@ -21,10 +24,17 @@ export declare function following(track: Track, e: Element, t: number, page: Pag
 export declare function marchOffset(tl: Timeline, speed: number, period: number, t: number): number;
 /** The page as a still drawing at `t` seconds, symbol instances expanded (DottieDocument.resolved(at:)). A page with
  * no timeline and no instances is returned as is. */
-export declare function resolved(page: Page, t: number, state?: StateChoice): Page;
+export declare function resolved(page: Page, t: number, state?: StateChoice, since?: number | null, carried?: Record<string, number>): Page;
 /** The page posed at `t` seconds, instances kept, and the elements whose `when` doesn't hold under `state` left out
  * with their connectors (DottieDocument.posed(at:state:)). */
-export declare function posed(page: Page, t: number, state?: StateChoice): Page;
+export declare function posed(page: Page, t: number, state?: StateChoice, since?: number | null, carried?: Record<string, number>): Page;
+/** `posed`, and the frame's metrics (ADR 0003). `since` is the seconds since the page's state last changed, which
+ * backlog has been piling up for: the player passes the time since the last click; null is `t`, as exports draw it.
+ * `carried` is what each queue held when the state last changed (`FrameMetrics.carry` then), which it drains from. */
+export declare function posedWithMetrics(page: Page, t: number, state?: StateChoice, since?: number | null, carried?: Record<string, number>): {
+    frame: Page;
+    metrics: FrameMetrics;
+};
 /** The moment a still picture of the page shows: its poster, else the end. */
 export declare function posterTime(page: Page): number;
 /** The page as a still picture (its poster frame when animated). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phin-tech/dottie",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Render, play and compile Dottie (.dottie) drawings and animations in the browser",
   "type": "module",
   "license": "Apache-2.0",