@phin-tech/dottie 0.9.0 → 0.11.0

package/dist/types/clicks.d.ts

@@ -1,4 +1,4 @@
-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. */
@@ -11,9 +11,10 @@ export type Click = ({
 } | {
     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;

package/dist/types/compile.d.ts

@@ -11,6 +11,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/elbow.d.ts

@@ -0,0 +1,18 @@
+import type { Element } from "./model.ts";
+import type { Point, Rect } from "./path.ts";
+/** How far a route keeps from the shapes it goes round. */
+export declare const MARGIN = 16;
+/** What a bend costs, in points of length. */
+export declare const BEND = 24;
+/** Shapes smaller than this either way (packets, dots, small icons) aren't in the way. */
+export declare const SMALLEST = 24;
+/** More shapes in the way than this, and the plain route is kept. */
+export declare const MOST = 48;
+/** The box of `e` if a route goes round it: not a connector, text, freehand line or plain path, not invisible, and
+ * not small. */
+export declare function obstacle(e: Element): Rect | null;
+/** Whether the right-angled line through `points` passes through the inside of `r` (not just along its edge). */
+export declare function crosses(points: Point[], r: Rect): boolean;
+/** `plain` (the Z or L from `a` to `b`), or a way round the shapes among `elements` it crosses, leaving out `except`
+ * (the connector's own ends). */
+export declare function avoiding(plain: Point[], a: Point, b: Point, startVertical: boolean, endVertical: boolean, elements: Iterable<Element>, except: Set<string>): Point[];

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/flows.d.ts

@@ -4,6 +4,8 @@ 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;
+/** `cost` as routing uses it: 1 for null, kept within 0...1,000,000 (ConnectorData.routeCost). */
+export declare const routeCost: (cost: number | null) => number;
 /** 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

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@ export { BUNDLED_FONTS } from "./text.ts";
 export { inspect, inspectFrame, inspectPage, sampleTimes } from "./inspect.ts";
 export { DottiePlayer, Playback, definePlayer, pageIndex, withRoughness } from "./player.ts";
 export { bounds, plan, svg, svgParts, type Plan, type Part } from "./svg.ts";
-export { themeNamed, themes, type Theme } from "./theme.ts";
+export { pageTheme, paletteColor, themeNamed, themes, type Theme } from "./theme.ts";
 export { cameraView, frameTimes, posterTime, resolved, sceneAt, still, transientElements } from "./timeline.ts";
 export interface RenderOptions {
     /** Page name or 1-based number; the first page by default. */
@@ -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.9.0";
+export declare const VERSION = "0.11.0";

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;
@@ -28,15 +29,26 @@ export declare const emptyMetrics: () => FrameMetrics;
 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;
+/** One way a flow's traffic takes in a frame (`flowFrame`'s routes): to `goal` over the connectors `hops`
+ * ([connector, backwards]), carrying `amount` of its volume at a cost of `cost`; `waits` when it goes only as far as
+ * the queue it waits in. */
+export interface FlowRoute {
+    goal: string;
+    hops: [string, boolean][];
+    amount: number;
+    waits: boolean;
+    cost: 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>): {
+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[]>;
 };
 /** 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;
@@ -51,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;
@@ -29,6 +30,29 @@ export interface Style {
     dashOffset: number | null;
     /** The color of a shape's or connector's label; null follows `stroke`. Text boxes and notes ignore it. */
     textColor: RGBA | null;
+    /** 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;
+    stroke: string | null;
+    textColor: string | null;
+}
+/** A named color in a theme's palette. */
+export interface PaletteColor {
+    name: string;
+    color: RGBA;
+}
+/** A theme made in the drawing (CustomTheme): it takes the place of the page's `theme`. */
+export interface CustomTheme {
+    name: string;
+    background: RGBA;
+    ink: RGBA;
+    palette: PaletteColor[];
+    base: string | null;
 }
 /** `portIndex` pins the end to one of the bound element's `ports`, and wins over `port`. */
 export interface Endpoint {
@@ -55,6 +79,8 @@ export interface ConnectorData {
     waypoints: StrokePoint[] | null;
     /** Hops where the line crosses a connector drawn beneath it. */
     hops: boolean | null;
+    /** An elbow line goes round the shapes in its way instead of through them (elbow.ts). */
+    avoid?: boolean | null;
     /** What a flow's traffic pays to take this connector (ADR 0002); null is 1. */
     cost: number | null;
 }
@@ -75,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. */
@@ -163,6 +191,13 @@ export interface Element {
     delay?: number | null;
     /** A shape that is a queue: backlog waits at the nearest one before whatever is full. */
     queue?: boolean | null;
+    /** The container this element is in (ADR 0006). */
+    containerID?: string | null;
+    /** On a rectangle: it's a container. Its title band is its `labelRect`, kept by the app, so drawing needs nothing more. */
+    container?: {
+        fixed: boolean | null;
+        lanes: "rows" | "columns" | null;
+    } | null;
     /** Shows a metric; drawn as plain paths and a label when the page is posed (metrics.ts). */
     gauge?: Gauge | null;
 }
@@ -250,10 +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;
 }
@@ -298,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. */
@@ -134,10 +135,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/dist/types/theme.d.ts

@@ -1,10 +1,22 @@
-import type { RGBA } from "./model.ts";
+import type { Page, PaletteColor, RGBA } from "./model.ts";
 export interface Theme {
     id: string;
     name: string;
     background: RGBA;
     ink: RGBA;
+    palette: PaletteColor[];
 }
+/** The palette names every built-in theme has, in order. */
+export declare const PALETTE_NAMES: string[];
+/** Light pages. */
+export declare const LIGHT_PALETTE: PaletteColor[];
 export declare const themes: Theme[];
 /** The theme a page names, or null (white page, black ink) for none or one this version doesn't know. */
 export declare function themeNamed(id: string | null | undefined): Theme | null;
+/** The theme `page` is drawn in: its own, else the built-in it names, else null. */
+export declare function pageTheme(page: Pick<Page, "theme" | "customTheme">): Theme | null;
+/** The palette color `name` names on `page`, ignoring case. */
+export declare function paletteColor(page: Pick<Page, "theme" | "customTheme">, name: string): RGBA | null;
+/** `page` with every named color set from its palette (DottieDocument.resolvingPalette); a name the palette doesn't
+ * have keeps the color it had. */
+export declare function resolvingPalette(page: Page): Page;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phin-tech/dottie",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "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": {