@phin-tech/dottie 0.10.0 → 0.11.1

package/PARITY.md

@@ -24,6 +24,8 @@ fixture, so the gap is visible rather than silent.
 | Ports and edge-following, rotated shapes, free ends | Supported | [edge/connectors](../fixtures/edge/connectors.dottie) | |
 | Connectors and labels on outlines (ADR 0001) | Supported | [edge/extensions](../fixtures/edge/extensions.dottie) | Edge-following meets a `.path`'s actual outline, not its box (ray against 16-step flattened curves). Endpoints pinned with `portIndex` attach to the element's `ports`. A path's label goes in its `labelRect`. |
 | Extension shapes as stored (ADR 0001) | Supported | [edge/extensions](../fixtures/edge/extensions.dottie) | Drawn from the stored path with no extension installed. The `extension` field is kept as metadata and nothing runs. Parameters, commands and handles are Dottie-only. |
+| Click logic (`logic`, a click's `run`) | Supported | [edge/logic](../fixtures/edge/logic.dottie) | One engine for both: `logic.ts` (QuickJS in WebAssembly), run by `LogicEngine.swift` in JavaScriptCore. Runs only with `allow-logic` (ADR 0007). |
+| Number variables, expressions in conditions and clicks, `{value}` in labels | Supported | [edge/counters](../fixtures/edge/counters.dottie), [expressions.json](../fixtures/expressions.json) | One grammar in `Expression.swift` and `expression.ts` (ADR 0007). |
 | Containers and swimlanes | Supported | [edge/containers](../fixtures/edge/containers.dottie) | Drawn from the stored frame and title band (`labelRect`); the app keeps them fitted (ADR 0006). |
 | Themes of a page's own, and palette colors by name | Supported | [edge/palette](../fixtures/edge/palette.dottie) | Names are resolved when a file is read, by the same rules in `Theme.swift` and `theme.ts` (ADR 0005). |
 | Elbows that go round shapes (`avoid`) | Supported | [edge/elbow-around](../fixtures/edge/elbow-around.dottie) | The same grid router, point for point (`ElbowRouter.swift`, `elbow.ts`). |
@@ -57,6 +59,6 @@ fixture, so the gap is visible rather than silent.
 | Clicks that set and toggle variables | Supported | [edge/state](../fixtures/edge/state.dottie) | Change what shows without touching the playhead |
 | Looping scenes (`loop` on a marker) | Supported | [edge/state](../fixtures/edge/state.dottie) | No stop on entering, round from the scene's end to its start |
 | Links out of the drawing (`url`) | Supported | [edge/links](../fixtures/edge/links.dottie) | A web or mail `url` opens when clicked if there is no `click`, and SVG export wraps it in `<a>`; a link to another drawing does nothing on the web |
-| Links between shapes and pages | Partial | [edge/clicks](../fixtures/edge/clicks.dottie) | A link to a shape on another page shows that page; one on the same page does nothing. The HTML export holds one page, so it has neither |
+| Links between shapes and pages | Partial | [edge/clicks](../fixtures/edge/clicks.dottie) | A link to a shape on another page shows that page; one on the same page does nothing. The HTML export of one page has neither; with every page (`--all-pages`, `history`) it shows the page at its own address, and split a page per file (`--split`, `links`) it goes to that page's file |
 | Editing | Missing | | |
 | Ticking task boxes in notes | Missing | | Drawn, not clickable |

package/README.md

@@ -28,6 +28,8 @@ prefer reduced motion. A still page is just the drawing.
 | `clean` | Draw precisely instead of sketchy |
 | `no-controls`, `no-autoplay`, `no-loop` | |
 | `label` | The accessible name; the page name by default |
+| `history` | Each page a link shows gets its own address (`#` and the page's name), so Back and Forward go between pages and a link can open any of them. One such player to a page |
+| `links` | JSON from the id of an element a link points at to the web page that shows it (`{"…": "details.html"}`), for a drawing exported one page per file: a link to another page goes there. Only relative `.html` paths are followed |
 
 Elements the drawing makes clickable work with the mouse and the keyboard (Tab, then Enter or Space). A click plays
 a named scene on to the next one, opens a link in a new tab (only `http`, `https` and `mailto`), or shows the page a
@@ -43,7 +45,8 @@ region a click took down. A looping scene plays round until a click or next leav
 
 The element has `play()`, `pause()`, `nextScene()`, `prevScene()`, `activate(elementId)`, `currentTime`
 (settable), `duration`, `paused`, `variables` and `setState({name: value})`, and fires `load`, `frame`, `action`,
-`state` (with `{variables}`, after a change) and `error` events. Its page color comes from the drawing's theme; set
+`state` (with `{variables}`, after a change), `page` (with `{index, name, first}`, when the page shown changes) and
+`error` events. Its page color comes from the drawing's theme; set
 `--dottie-radius` to round it, and style its parts with `::part(stage)` and `::part(controls)`.
 
 Without modules, `dist/dottie-player.min.js` is a classic script that registers the element and sets
@@ -56,6 +59,21 @@ when it is showing. The classic script starts the worker from its own source (a
 loads `dottie-player.min.js` from beside itself, so host the two together. Where a worker can't start, as under a
 `worker-src` policy that refuses it, the player works it out in place as before. Small drawings always do.
 
+**Click logic.** Variables can be numbers, and conditions and clicks are small expressions (`count >= 3`,
+`"count + 1"`, `{count}` in a label). For more, a page can carry `logic`: JavaScript handlers a click `run`s, each
+getting the variables and the click and returning new values. The player runs them only with `allow-logic`:
+
+```html
+<dottie-player src="game.dottie" allow-logic></dottie-player>
+```
+
+Each click's handler runs in a fresh QuickJS sandbox compiled to WebAssembly, never in your page's JavaScript: it has
+no `window`, `document`, network, timers, `Date` or `Math.random`, and a time and memory limit, so the same click on
+the same state gives the same result everywhere. A handler that fails leaves the state as it was and fires
+`logicerror` (with `{element, handler, error}`). Without `allow-logic`, a click does its own `set` and `toggle`
+instead. The engine (`dottie-logic.min.js`, about 850 KB) is loaded from beside the player only when a page with
+logic is clicked, so host it with the player; `dottie-compile --allow-logic` puts it in the compiled script instead.
+
 **Fonts.** Text in Dottie's handwriting fonts (Caveat, Patrick Hand, Architects Daughter; SIL Open Font License)
 is drawn in them: the player loads the ones a drawing uses from `fonts/` beside its own script, as `dist/fonts` on
 npm and the CDNs. If you host the player yourself, copy that folder with it, or call `Dottie.setFontBase(url)`
@@ -78,7 +96,9 @@ handwriting fonts the drawing uses (15 to 30 KB each), so one file shows it anyw
 ```
 
 `dottie-compile` takes `--page`, `--at`, `--clean`, `--no-controls`, `--no-autoplay`, `--no-loop` and `--label`;
-only the chosen page (and its pictures) goes in. The Dottie Mac app's command-line tool writes the same file:
+only the chosen page (and its pictures) goes in. With `--all-pages` every page goes in, for a drawing people drill
+into: a link to a shape on another page shows that page, each page gets its own address (`tour.html#Details`), and
+Back goes back (`--page` is then the page to start on). The Dottie Mac app's command-line tool writes the same file:
 `dottie render tour.dottie -f js`. From code: `import { compile } from "@phin-tech/dottie/compile"`.
 
 ## Use the library

package/dist/compile.js

@@ -1,4 +1,4 @@
-/*! dottie.js 0.10.0 | Apache-2.0 | https://github.com/phin-tech/dottie */
+/*! dottie.js 0.11.1 | Apache-2.0 | https://github.com/phin-tech/dottie */
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
@@ -109,12 +109,12 @@ function resolvingPalette(page) {
 }
 
 // src/model.ts
-var SUPPORTED_VERSION = 2;
+var SUPPORTED_VERSION = 3;
 var KINDS = ["rectangle", "ellipse", "diamond", "text", "connector", "freehand", "path", "note", "image", "symbol"];
 var EASES = ["linear", "easeIn", "easeOut", "easeInOut", "hold", "spring", "bounce", "elastic"];
 var KNOWN_FIELDS = {
   file: ["version", "pages", "images"],
-  page: ["id", "name", "layers", "elements", "theme", "customTheme", "guidesX", "guidesY", "guidesLocked", "timeline", "symbols", "variables", "flows"],
+  page: ["id", "name", "layers", "elements", "theme", "customTheme", "logic", "guidesX", "guidesY", "guidesLocked", "timeline", "symbols", "variables", "flows"],
   flow: ["id", "from", "to", "every", "speed", "color", "size", "when", "spread", "volume", "overrides"],
   flowOverride: ["when", "volume"],
   symbol: ["id", "name", "width", "height", "layers", "elements", "timeline", "button", "params"],
@@ -183,7 +183,7 @@ var KNOWN_FIELDS = {
   repeat: ["start", "end", "count"],
   cameraKey: ["t", "x", "y", "width", "height", "ease"],
   marker: ["t", "name", "loop"],
-  click: ["scene", "url", "set", "toggle", "reset"],
+  click: ["scene", "url", "set", "toggle", "reset", "run"],
   hover: ["stroke", "fill", "opacity"],
   override: ["when", "stroke", "fill", "textColor", "opacity", "strokeWidth", "dash", "text", "reroute", "offline", "cost", "capacity", "delay"]
 };
@@ -430,7 +430,7 @@ var Reader = class {
   variables(v) {
     if (!isObj(v)) return null;
     const out = {};
-    for (const [k, b] of Object.entries(v)) if (typeof b === "boolean") out[k] = b;
+    for (const [k, b] of Object.entries(v)) if (typeof b === "boolean" || typeof b === "number" && Number.isFinite(b)) out[k] = b;
     return Object.keys(out).length > 0 ? out : null;
   }
   click(v) {
@@ -442,12 +442,22 @@ var Reader = class {
     let set = null;
     if (isObj(v.set)) {
       set = {};
-      for (const [k, b] of Object.entries(v.set)) if (typeof b === "boolean" && isName(k)) set[k] = b;
+      for (const [k, b] of Object.entries(v.set)) {
+        if (isName(k) && (typeof b === "boolean" || typeof b === "string" || typeof b === "number" && Number.isFinite(b))) set[k] = b;
+      }
       if (Object.keys(set).length === 0) set = null;
     }
     const raw = typeof v.toggle === "string" ? [v.toggle] : Array.isArray(v.toggle) && v.toggle.every((x) => typeof x === "string") ? v.toggle : null;
     const toggle = raw ? raw.filter(isName) : null;
-    return { scene: str(v.scene) ?? null, url: safe, set, toggle: toggle && toggle.length > 0 ? toggle : null, reset: v.reset === true ? true : null };
+    const run = str(v.run);
+    return {
+      scene: str(v.scene) ?? null,
+      url: safe,
+      set,
+      toggle: toggle && toggle.length > 0 ? toggle : null,
+      reset: v.reset === true ? true : null,
+      run: run !== void 0 && isName(run) ? run : null
+    };
   }
   playback(v) {
     const s = str(v);
@@ -610,6 +620,7 @@ var Reader = class {
       elements: (Array.isArray(v.elements) ? v.elements : []).map((e) => this.element(e, images)).filter((e) => e !== null),
       theme: str(v.theme) ?? null,
       customTheme: this.customTheme(v.customTheme),
+      logic: typeof v.logic === "string" && v.logic.length > 0 ? v.logic : null,
       timeline: this.timeline(v.timeline),
       symbols: Array.isArray(v.symbols) ? v.symbols.map((x) => this.symbol(x, images)).filter((x) => x !== null) : null,
       variables: this.variables(v.variables),
@@ -751,6 +762,11 @@ function playerAttributes(options) {
   if (options.noAutoplay) out["no-autoplay"] = "";
   if (options.noLoop) out["no-loop"] = "";
   if (options.label !== void 0) out.label = options.label;
+  if (options.logicEngine) out["allow-logic"] = "";
+  if (options.allPages) {
+    out.history = "";
+    if (options.page !== void 0) out.page = String(options.page);
+  }
   return out;
 }
 function compile(source, runtime, options = {}) {
@@ -765,28 +781,32 @@ function compile(source, runtime, options = {}) {
   const file = parseDottie(raw);
   const json = raw;
   const i = pageIndex(file, options.page === void 0 ? null : String(options.page));
-  const page = json.pages[i];
+  const chosen = options.allPages ? json.pages.map((_, k) => k) : [i];
+  const pages = chosen.map((k) => json.pages[k]);
   const refs = /* @__PURE__ */ new Set();
-  JSON.stringify(page, (k, v) => {
+  JSON.stringify(pages, (k, v) => {
     if (k === "ref" && typeof v === "string") refs.add(v);
     return v;
   });
   const images = Object.fromEntries(Object.entries(json.images ?? {}).filter(([k]) => refs.has(k)));
-  const data = { version: json.version, pages: [page] };
+  const data = { version: json.version, pages };
   if (Object.keys(images).length) data.images = images;
   const fonts = {};
-  for (const family of options.fontData ? usedFonts(file.pages[i]) : []) {
+  const families2 = new Set(chosen.flatMap((k) => options.fontData ? usedFonts(file.pages[k]) : []));
+  for (const family of families2) {
     for (const face of fontFaces(family)) {
       const b64 = options.fontData(family, face);
       if (b64) (fonts[family] ?? (fonts[family] = {}))[face] = b64;
     }
   }
+  const logic = chosen.some((k) => file.pages[k].logic);
   const fill = {
     DOTTIE_DATA: () => scriptJSON(data),
-    DOTTIE_OPTIONS: () => scriptJSON(playerAttributes(options)),
+    DOTTIE_OPTIONS: () => scriptJSON(playerAttributes(logic ? options : { ...options, logicEngine: void 0 })),
     DOTTIE_FONTS: () => scriptJSON(fonts)
   };
-  return runtime.trimEnd() + "\n" + LOADER.replace(/\bDOTTIE_(?:DATA|OPTIONS|FONTS)\b/g, (m) => fill[m]());
+  const engine = options.logicEngine && logic ? options.logicEngine.trimEnd() + "\n" : "";
+  return engine + runtime.trimEnd() + "\n" + LOADER.replace(/\bDOTTIE_(?:DATA|OPTIONS|FONTS)\b/g, (m) => fill[m]());
 }
 export {
   LOADER,

package/dist/dottie-compile.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/*! dottie.js 0.10.0 | Apache-2.0 | https://github.com/phin-tech/dottie */
+/*! dottie.js 0.11.1 | Apache-2.0 | https://github.com/phin-tech/dottie */
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
@@ -117,12 +117,12 @@ function resolvingPalette(page) {
 }
 
 // src/model.ts
-var SUPPORTED_VERSION = 2;
+var SUPPORTED_VERSION = 3;
 var KINDS = ["rectangle", "ellipse", "diamond", "text", "connector", "freehand", "path", "note", "image", "symbol"];
 var EASES = ["linear", "easeIn", "easeOut", "easeInOut", "hold", "spring", "bounce", "elastic"];
 var KNOWN_FIELDS = {
   file: ["version", "pages", "images"],
-  page: ["id", "name", "layers", "elements", "theme", "customTheme", "guidesX", "guidesY", "guidesLocked", "timeline", "symbols", "variables", "flows"],
+  page: ["id", "name", "layers", "elements", "theme", "customTheme", "logic", "guidesX", "guidesY", "guidesLocked", "timeline", "symbols", "variables", "flows"],
   flow: ["id", "from", "to", "every", "speed", "color", "size", "when", "spread", "volume", "overrides"],
   flowOverride: ["when", "volume"],
   symbol: ["id", "name", "width", "height", "layers", "elements", "timeline", "button", "params"],
@@ -191,7 +191,7 @@ var KNOWN_FIELDS = {
   repeat: ["start", "end", "count"],
   cameraKey: ["t", "x", "y", "width", "height", "ease"],
   marker: ["t", "name", "loop"],
-  click: ["scene", "url", "set", "toggle", "reset"],
+  click: ["scene", "url", "set", "toggle", "reset", "run"],
   hover: ["stroke", "fill", "opacity"],
   override: ["when", "stroke", "fill", "textColor", "opacity", "strokeWidth", "dash", "text", "reroute", "offline", "cost", "capacity", "delay"]
 };
@@ -438,7 +438,7 @@ var Reader = class {
   variables(v) {
     if (!isObj(v)) return null;
     const out = {};
-    for (const [k, b] of Object.entries(v)) if (typeof b === "boolean") out[k] = b;
+    for (const [k, b] of Object.entries(v)) if (typeof b === "boolean" || typeof b === "number" && Number.isFinite(b)) out[k] = b;
     return Object.keys(out).length > 0 ? out : null;
   }
   click(v) {
@@ -450,12 +450,22 @@ var Reader = class {
     let set = null;
     if (isObj(v.set)) {
       set = {};
-      for (const [k, b] of Object.entries(v.set)) if (typeof b === "boolean" && isName(k)) set[k] = b;
+      for (const [k, b] of Object.entries(v.set)) {
+        if (isName(k) && (typeof b === "boolean" || typeof b === "string" || typeof b === "number" && Number.isFinite(b))) set[k] = b;
+      }
       if (Object.keys(set).length === 0) set = null;
     }
     const raw = typeof v.toggle === "string" ? [v.toggle] : Array.isArray(v.toggle) && v.toggle.every((x) => typeof x === "string") ? v.toggle : null;
     const toggle = raw ? raw.filter(isName) : null;
-    return { scene: str(v.scene) ?? null, url: safe, set, toggle: toggle && toggle.length > 0 ? toggle : null, reset: v.reset === true ? true : null };
+    const run = str(v.run);
+    return {
+      scene: str(v.scene) ?? null,
+      url: safe,
+      set,
+      toggle: toggle && toggle.length > 0 ? toggle : null,
+      reset: v.reset === true ? true : null,
+      run: run !== void 0 && isName(run) ? run : null
+    };
   }
   playback(v) {
     const s = str(v);
@@ -618,6 +628,7 @@ var Reader = class {
       elements: (Array.isArray(v.elements) ? v.elements : []).map((e) => this.element(e, images)).filter((e) => e !== null),
       theme: str(v.theme) ?? null,
       customTheme: this.customTheme(v.customTheme),
+      logic: typeof v.logic === "string" && v.logic.length > 0 ? v.logic : null,
       timeline: this.timeline(v.timeline),
       symbols: Array.isArray(v.symbols) ? v.symbols.map((x) => this.symbol(x, images)).filter((x) => x !== null) : null,
       variables: this.variables(v.variables),
@@ -759,6 +770,11 @@ function playerAttributes(options2) {
   if (options2.noAutoplay) out["no-autoplay"] = "";
   if (options2.noLoop) out["no-loop"] = "";
   if (options2.label !== void 0) out.label = options2.label;
+  if (options2.logicEngine) out["allow-logic"] = "";
+  if (options2.allPages) {
+    out.history = "";
+    if (options2.page !== void 0) out.page = String(options2.page);
+  }
   return out;
 }
 function compile(source2, runtime, options2 = {}) {
@@ -773,32 +789,36 @@ function compile(source2, runtime, options2 = {}) {
   const file = parseDottie(raw);
   const json = raw;
   const i = pageIndex(file, options2.page === void 0 ? null : String(options2.page));
-  const page = json.pages[i];
+  const chosen = options2.allPages ? json.pages.map((_, k) => k) : [i];
+  const pages = chosen.map((k) => json.pages[k]);
   const refs = /* @__PURE__ */ new Set();
-  JSON.stringify(page, (k, v) => {
+  JSON.stringify(pages, (k, v) => {
     if (k === "ref" && typeof v === "string") refs.add(v);
     return v;
   });
   const images = Object.fromEntries(Object.entries(json.images ?? {}).filter(([k]) => refs.has(k)));
-  const data = { version: json.version, pages: [page] };
+  const data = { version: json.version, pages };
   if (Object.keys(images).length) data.images = images;
   const fonts = {};
-  for (const family of options2.fontData ? usedFonts(file.pages[i]) : []) {
+  const families2 = new Set(chosen.flatMap((k) => options2.fontData ? usedFonts(file.pages[k]) : []));
+  for (const family of families2) {
     for (const face of fontFaces(family)) {
       const b64 = options2.fontData(family, face);
       if (b64) (fonts[family] ?? (fonts[family] = {}))[face] = b64;
     }
   }
+  const logic = chosen.some((k) => file.pages[k].logic);
   const fill = {
     DOTTIE_DATA: () => scriptJSON(data),
-    DOTTIE_OPTIONS: () => scriptJSON(playerAttributes(options2)),
+    DOTTIE_OPTIONS: () => scriptJSON(playerAttributes(logic ? options2 : { ...options2, logicEngine: void 0 })),
     DOTTIE_FONTS: () => scriptJSON(fonts)
   };
-  return runtime.trimEnd() + "\n" + LOADER.replace(/\bDOTTIE_(?:DATA|OPTIONS|FONTS)\b/g, (m) => fill[m]());
+  const engine = options2.logicEngine && logic ? options2.logicEngine.trimEnd() + "\n" : "";
+  return engine + runtime.trimEnd() + "\n" + LOADER.replace(/\bDOTTIE_(?:DATA|OPTIONS|FONTS)\b/g, (m) => fill[m]());
 }
 
 // src/index.ts
-var VERSION = "0.10.0";
+var VERSION = "0.11.1";
 
 // src/cli.ts
 var usage = `dottie-compile ${VERSION}: a Dottie drawing as one script that plays it on any page.
@@ -812,9 +832,12 @@ USAGE
 OPTIONS
   -o, --output <path>   Where to write it ("-" for stdout); default drawing.js next to the input
   -p, --page <page>     Page name or 1-based number; only that page is included (default the first)
+      --all-pages       Include every page, with links between them working and Back going back (with
+                        --page, the page to start on)
       --at <seconds>    Show that moment as a still
       --clean           Draw precisely instead of sketchy
       --no-controls, --no-autoplay, --no-loop
+      --allow-logic     let the page's click logic run (ADR 0007); it carries the engine (about 850 KB)
       --label <text>    The player's accessible name
 `;
 function fail(message, code = 2) {
@@ -824,6 +847,7 @@ function fail(message, code = 2) {
 }
 var args = process.argv.slice(2);
 var options = {};
+var allowLogic = false;
 var input;
 var output;
 for (let i = 0; i < args.length; i++) {
@@ -853,6 +877,9 @@ for (let i = 0; i < args.length; i++) {
       options.at = t;
       break;
     }
+    case "--all-pages":
+      options.allPages = true;
+      break;
     case "--clean":
       options.clean = true;
       break;
@@ -865,6 +892,9 @@ for (let i = 0; i < args.length; i++) {
     case "--no-loop":
       options.noLoop = true;
       break;
+    case "--allow-logic":
+      allowLogic = true;
+      break;
     case "--label":
       options.label = value();
       break;
@@ -895,7 +925,8 @@ try {
       return void 0;
     }
   };
-  const js = compile(source, runtime, { ...options, fontData });
+  const logicEngine = allowLogic ? readFileSync(new URL("./dottie-logic.min.js", import.meta.url), "utf8") : void 0;
+  const js = compile(source, runtime, { ...options, fontData, logicEngine });
   if (output === "-") process.stdout.write(js);
   else {
     const target = output ?? input.replace(/\.dottie$/i, "") + ".js";