@phin-tech/dottie 0.10.0 → 0.11.1

package/dist/types/clicks.d.ts

@@ -1,26 +1,34 @@
-import { type DottieFile, type Element, type Marker, type Page } from "./model.ts";
+import { type ClickValue, type DottieFile, type Element, type Marker, type Page } from "./model.ts";
 /** Jump to scene `scene` (an index into the page's markers) and play on to the next; open `url` in a new tab; or,
  * in <dottie-player> only, show page `page` (an index into the file's pages), where the element's link points. Any
- * of them may first `set` and `toggle` page variables (ClickAction.set, .toggle), and a click may do only that. */
+ * of them may first `set` and `toggle` page variables (ClickAction.set, .toggle), and a click may do only that. Or go to
+ * `href`, the exported web page that holds the page a `link` points at, when a drawing is exported one page per file. */
 export type Click = ({
     scene: number;
 } | {
     url: string;
 } | {
     page: number;
+} | {
+    href: string;
 } | {
     state: true;
 }) & {
-    set?: Record<string, boolean>;
+    set?: Record<string, ClickValue>;
     toggle?: string[];
     reset?: true;
+    run?: string;
 };
 /** The marker called `name`: an exact match, else one that differs only in case. */
 export declare function sceneNamed(name: string, markers: Marker[]): number;
 /** The page's clickable elements and what each click does, by element id. A scene named by no marker, or a link
  * that isn't allowed, makes nothing clickable; an element with no `click` opens its `url` when that is a web link. Given the whole file, an element whose `link` points at an element on
- * another page shows that page (the HTML export holds one page, so it can't). */
-export declare function clickTargets(page: Page, file?: DottieFile): Map<string, Click>;
+ * another page shows that page. `hrefs` names, by the id of an element a link points at, the web page that shows it
+ * (`<dottie-player links>`): a page exported on its own reaches the others through them. */
+export declare function clickTargets(page: Page, file?: DottieFile, hrefs?: Record<string, string>): Map<string, Click>;
+/** `href` if it is a page beside this one (a relative `.html` path, maybe with a `#fragment`), else null: no scheme,
+ * so never `javascript:` or another site. */
+export declare function pageHref(href: unknown): string | null;
 /** `e` as it looks hovered (HoverLook.apply). */
 export declare function hoveredElement(e: Element): Element;
 /** `page` with `ids` drawn as they look hovered. */

package/dist/types/compile.d.ts

@@ -2,8 +2,12 @@ import type { Face } from "./metrics.ts";
 /** 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. */
+    /** Page name or 1-based number; only that page goes in. The first page by default. With `allPages`, the page to
+     * start on. */
     page?: string | number;
+    /** Every page goes in, and links between them work: each page shown gets its own address (`#` and its name), so
+     * the browser's Back and Forward go between them (the player's `history`). */
+    allPages?: boolean;
     /** Show this moment (seconds) as a still. */
     at?: number;
     clean?: boolean;
@@ -11,6 +15,9 @@ export interface CompileOptions {
     noAutoplay?: boolean;
     noLoop?: boolean;
     label?: string;
+    /** The click-logic engine (dist/dottie-logic.min.js): with it the page's logic may run (ADR 0007), and the player
+     * gets allow-logic; without it a click does its own set and toggle. */
+    logicEngine?: string;
     /** A bundled font's file (`fontFile`) as base64, so the drawing carries the fonts it uses; without it the
      * player fetches them from beside itself. dottie-compile reads them from dist/fonts. */
     fontData?: (family: string, face: Face) => string | undefined;

package/dist/types/expression.d.ts

@@ -0,0 +1,51 @@
+/** A page variable's value: true or false, or a number. */
+export type Var = boolean | number;
+export type Expr = {
+    k: "lit";
+    v: Var;
+} | {
+    k: "name";
+    name: string;
+} | {
+    k: "metric";
+    metric: string;
+    target: string;
+} | {
+    k: "not";
+    e: Expr;
+} | {
+    k: "neg";
+    e: Expr;
+} | {
+    k: "bin";
+    op: string;
+    l: Expr;
+    r: Expr;
+} | {
+    k: "call";
+    fn: string;
+    args: Expr[];
+};
+/** The metrics an expression can read (PageState.metricNames). */
+export declare const METRIC_NAMES: string[];
+/** As a condition reads it: a number holds unless it is 0 (or not a number). */
+export declare const truthy: (v: Var) => boolean;
+/** As arithmetic reads it: true is 1, false 0. */
+export declare const num: (v: Var) => number;
+/** `text` parsed, or null when it isn't an expression. Remembered, since a frame reads the same conditions often. */
+export declare function parseExpr(text: string): Expr | null;
+/** What a metric reads; null when it can't be had (every comparison with it then fails). */
+export type MetricRead = (metric: string, target: string) => number | null;
+/** The value with these variables (a missing one is false). */
+export declare function evaluate(e: Expr, state: Record<string, Var>, metric?: MetricRead | null): Var;
+/** The variable names it reads, in order, each once. */
+export declare function exprNames(e: Expr): string[];
+/** The metrics it reads. */
+export declare function exprMetrics(e: Expr): {
+    metric: string;
+    target: string;
+}[];
+/** A variable's value as text shows it (Var.description): true or false, a number to two places. */
+export declare function describeVar(v: Var): string;
+/** `text` with each `{expression}` that reads only the page's variables replaced by its value (PageState.filling). */
+export declare function filling(text: string, values: Record<string, Var>): string;

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.10.0";
+export declare const VERSION = "0.11.1";

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

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

package/dist/types/logic-loader.d.ts

@@ -0,0 +1,9 @@
+import type { ClickEvent, LogicResult } from "./logic.ts";
+import type { Var } from "./expression.ts";
+interface Engine {
+    loadLogic(): Promise<void>;
+    runLogic(source: string, handler: string, state: Record<string, Var>, event: ClickEvent): LogicResult;
+}
+/** The engine, loaded; rejects where it can't be had. */
+export declare function logicEngine(): Promise<Engine>;
+export {};

package/dist/types/logic-polyfill.d.ts

@@ -0,0 +1,2 @@
+/** Adds what's missing; safe to call more than once. */
+export declare function polyfill(): void;

package/dist/types/logic.d.ts

@@ -0,0 +1,32 @@
+import type { Var } from "./expression.ts";
+/** What a handler is told about the click. */
+export interface ClickEvent {
+    /** The clicked element's id, anchor and first line of text. */
+    id: string;
+    anchor: string | null;
+    text: string | null;
+    /** Seconds into the page's timeline, and the scene playing. */
+    time: number;
+    scene: string | null;
+}
+/** New variable values, or why there are none (the state then stays as it was). */
+export type LogicResult = {
+    ok: true;
+    set: Record<string, Var>;
+} | {
+    ok: false;
+    error: string;
+};
+/** How much a handler may do: QuickJS checks in every 10,000 or so operations, and this many check-ins is the
+ * limit (a few million operations, well under a second). */
+export declare const OPERATION_BUDGET = 400;
+/** How much memory a handler may use. */
+export declare const MEMORY_LIMIT: number;
+/** Longest logic a page may have, in characters. */
+export declare const MAX_SOURCE: number;
+/** Loads the engine (once). */
+export declare function loadLogic(): Promise<void>;
+/** Whether the engine is loaded, so `runLogic` can be called. */
+export declare function logicReady(): boolean;
+/** Runs `handler` from `source` for a click; the engine must be loaded. */
+export declare function runLogic(source: string, handler: string, state: Record<string, Var>, event: ClickEvent): LogicResult;

package/dist/types/measure.d.ts

@@ -1,5 +1,6 @@
 import type { Element, Flow, Gauge, Page, RGBA } from "./model.ts";
 import { type MetricTerm } from "./state.ts";
+import type { Var } from "./expression.ts";
 /** A connector's or shape's metrics in one frame (ElementMetrics). */
 export interface ElementMetrics {
     throughput: number;
@@ -44,7 +45,7 @@ export declare const queueKey: (shape: string, flow: string) => string;
  * 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>): {
+export declare function flowFrame(flows: Flow[] | null, frame: Page, t: number, values: Record<string, Var> | null, offline?: Set<string>, sinceChange?: number | null, carried?: Record<string, number>): {
     packets: Element[];
     metrics: FrameMetrics;
     routes: Map<string, FlowRoute[]>;
@@ -62,13 +63,13 @@ export interface Finish {
 /** 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>): {
+export declare function finishPlan(elements: Element[], metrics: FrameMetrics, values: Record<string, Var> | 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>): {
+export declare function finishing(elements: Element[], metrics: FrameMetrics, values: Record<string, Var> | null, frame: Page, flows: Flow[], since?: number, carried?: Record<string, number>): {
     elements: Element[];
     readings: Record<string, number>;
 };

package/dist/types/model.d.ts

@@ -1,3 +1,4 @@
+import type { Var } from "./expression.ts";
 export interface RGBA {
     r: number;
     g: number;
@@ -32,6 +33,8 @@ export interface Style {
     /** Which colors are palette colors, by name (ADR 0005); set from the page's palette when it is read. */
     named?: ColorNames | null;
 }
+/** What a click gives a variable (ClickValue): a value, or an expression over the state before the click. */
+export type ClickValue = Var | string;
 /** Palette names for an element's colors (Theme.swift's ColorNames). */
 export interface ColorNames {
     fill: string | null;
@@ -98,10 +101,12 @@ export interface EmbeddedImage {
 export interface ClickAction {
     scene: string | null;
     url: string | null;
-    set: Record<string, boolean> | null;
+    set: Record<string, ClickValue> | null;
     toggle: string[] | null;
     /** Puts every page variable back to its starting value first. */
     reset?: boolean | null;
+    /** A handler in the page's `logic` to run (ADR 0007); where logic may not run, `set` and `toggle` stand in. */
+    run?: string | 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. */
@@ -280,12 +285,14 @@ export interface Page {
     layers: Layer[];
     elements: Element[];
     theme: string | null;
+    /** JavaScript defining the handlers clicks `run` (ADR 0007), run only on clicks, sealed, where allowed. */
+    logic?: string | null;
     /** A theme of the page's own (ADR 0005), in place of `theme`. */
     customTheme?: CustomTheme | null;
     timeline: Timeline | null;
     symbols: Symbol[] | null;
     /** The page's variables and their starting values (DottieDocument.variables). */
-    variables: Record<string, boolean> | null;
+    variables: Record<string, Var> | null;
     /** Traffic routed over the connectors drawn in each frame (DottieDocument.flows; see flows.ts). */
     flows: Flow[] | null;
 }
@@ -330,7 +337,7 @@ export interface DottieFile {
     warnings: string[];
 }
 /** The newest file version this library was written for. Newer files still load, with a warning. */
-export declare const SUPPORTED_VERSION = 2;
+export declare const SUPPORTED_VERSION = 3;
 export declare const KINDS: readonly string[];
 /** The fields dottie.js reads, per object; the schema test checks they're exactly the schema's. Anything else
  * in a file is newer than this version and is reported in `warnings`. */

package/dist/types/player.d.ts

@@ -1,6 +1,7 @@
 import { type Click } from "./clicks.ts";
 import { type DottieFile, type Page, type RGBA } from "./model.ts";
 import { type Plan } from "./svg.ts";
+import type { Var } from "./expression.ts";
 /** Finds a page by name (any case) or 1-based number; the first page when `spec` is empty or matches nothing. */
 export declare function pageIndex(file: DottieFile, spec: string | null | undefined): number;
 export declare function withRoughness(page: Page, roughness: number): Page;
@@ -13,7 +14,7 @@ export declare class Playback {
     /** Whether each scene loops (Marker.loop). */
     readonly sceneLoops: boolean[];
     /** The page's variables now: their starting values until clicks change them. */
-    state: Record<string, boolean>;
+    state: Record<string, Var>;
     /** 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. */
@@ -48,10 +49,12 @@ export declare class Playback {
     private order;
     frame: number;
     onFrame: ((frame: number) => void) | null;
-    /** `file` is the drawing `page` belongs to, so links to its other pages are clickable. */
+    /** `file` is the drawing `page` belongs to, so links to its other pages are clickable; `hrefs`, the web pages that
+     * show the elements links point at, for pages that aren't in it (clickTargets). */
     constructor(page: Page, into: Element, options?: {
         clean?: boolean;
         file?: DottieFile;
+        hrefs?: Record<string, string>;
     });
     get frameCount(): number;
     get posterFrame(): number;
@@ -107,6 +110,9 @@ export declare class DottiePlayer extends ElementBase {
     private stillTime;
     private visible;
     private observer;
+    /** The page last shown, so `page` fires only when it changes. */
+    private shownPage;
+    private readonly onPopState;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -119,6 +125,10 @@ export declare class DottiePlayer extends ElementBase {
     /** 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;
+    /** With `history`, the page the address names after its `#` (by name, any case), if it names one. */
+    private addressedPage;
+    /** The `links` attribute read: element id to web page, the pages that can't be named left out. */
+    private hrefs;
     private mountPage;
     get paused(): boolean;
     /** The moment shown: a still's own time (its `at`, or the poster), else the current frame's. */
@@ -134,10 +144,14 @@ export declare class DottiePlayer extends ElementBase {
     /** Does what clicking element `id` does: jumps to its scene and plays on to the next (with reduced motion, or in a
      * still, straight to where that stops), opens its link in a new tab, or shows its page. */
     activate(id: string): void;
+    /** Runs handler `handler` from the page's logic for a click on `id` (DottieDocument.clicked). Clicks take turns, so
+     * each handler sees the state the one before left. */
+    private logicQueue;
+    private runLogic;
     /** The page's variables now. */
-    get variables(): Record<string, boolean>;
+    get variables(): Record<string, Var>;
     /** Gives the page's variables these values (the others keep theirs), redraws, and fires `state`. */
-    setState(values: Record<string, boolean>): void;
+    setState(values: Record<string, Var>): void;
     /** Redraws, while the page itself stands still, as long as a clicked copy is playing through. */
     private scheduleReplay;
     private setPlaying;

package/dist/types/state.d.ts

@@ -1,8 +1,8 @@
-import { type ClickAction, type Element, type Page, type StateOverride } from "./model.ts";
+import { type Var } from "./expression.ts";
+import { type ClickAction, type ClickValue, 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 metrics a condition can compare (ADR 0003), as `load(workers) > 0.9`. */
-export declare const METRIC_NAMES: string[];
+export { METRIC_NAMES } from "./expression.ts";
 /** A comparison of a metric in a condition (PageState.MetricTerm). */
 export interface MetricTerm {
     metric: string;
@@ -10,25 +10,24 @@ export interface MetricTerm {
     op: string;
     value: number;
 }
-/** `term` (trimmed) read as a metric comparison, or null. */
+/** `term` read as one metric comparison, `metric(target) op number`, or null. */
 export declare function metricTerm(term: string): MetricTerm | null;
-/** Whether `condition` compares a metric anywhere. */
+/** Whether `condition` reads 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). */
+/** The variable names `condition` reads, or null when it isn't one (ADR 0007's expressions). */
 export declare function conditionNames(condition: string): string[] | null;
 /** 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;
+ * false, and a comparison with a metric that can't be had fails; a condition that can't be read never holds. */
+export declare function holds(condition: string, state: Record<string, Var>, 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>;
+export type StateChoice = "initial" | "all" | Record<string, Var>;
 /** The values `choice` gives each variable; null for "all". */
-export declare function stateValues(page: Page, choice: StateChoice): Record<string, boolean> | null;
+export declare function stateValues(page: Page, choice: StateChoice): Record<string, Var> | 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[];
+export declare function activeOverrides(e: Element, values: Record<string, Var> | 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. */
@@ -37,4 +36,6 @@ export declare function applyOverride(o: StateOverride, e: Element): Element;
 export declare function changesState(c: ClickAction | null): 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>;
+export declare function applyClick(c: ClickAction, state: Record<string, Var>, initial?: Record<string, Var>): Record<string, Var>;
+/** A click's value given the state before it (ClickValue.value); an expression that can't be read leaves `current`. */
+export declare function clickValue(v: ClickValue, state: Record<string, Var>, current: Var | undefined): Var;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phin-tech/dottie",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Render, play and compile Dottie (.dottie) drawings and animations in the browser",
   "type": "module",
   "license": "Apache-2.0",
@@ -46,12 +46,14 @@
     "prepublishOnly": "npm test && node build.mjs"
   },
   "devDependencies": {
+    "@jitl/quickjs-singlefile-browser-release-sync": "^0.32.0",
     "@types/node": "^24.19.2",
     "@types/pngjs": "^6.0.5",
     "esbuild": "^0.25.12",
     "pixelmatch": "^7.2.0",
     "playwright": "^1.64.1",
     "pngjs": "^7.0.0",
+    "quickjs-emscripten-core": "^0.32.0",
     "typescript": "^5.9.3"
   },
   "publishConfig": {