animl-cli 0.0.0-stage → 0.1.1

package/packages/cli/src/schema-view.js

@@ -0,0 +1,493 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import "animl/all";
+import {
+  COMMON,
+  DOC,
+  ELEMENTS,
+  NODE_TYPES,
+  OWN,
+  PAINT,
+  PAINTED,
+  STATIC,
+  jsonSchema,
+  markupName,
+  nodeShape
+} from "animl";
+import { nodeAttrs } from "animl/internal/packages/markup/src/names.js";
+const ROOT = resolve(import.meta.dirname, "../../..");
+const compact = (s) => s.replace(/[^a-z0-9]/gi, "").toLowerCase();
+function distance(a, b) {
+  let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 0; i < a.length; i++) {
+    const next = [i + 1];
+    for (let j = 0; j < b.length; j++)
+      next.push(Math.min(next[j] + 1, row[j + 1] + 1, row[j] + Number(a[i] !== b[j])));
+    row = next;
+  }
+  return row[b.length];
+}
+function lookupTopic(topic, topics, _command) {
+  if (!topic) return topic;
+  if (topics.includes(topic)) return topic;
+  return [...topics].sort((a, b) => Number(b.includes("-")) - Number(a.includes("-"))).find((candidate) => compact(candidate) === compact(topic)) ?? topic;
+}
+function nearestTopic(topic, topics) {
+  const key = compact(topic);
+  const nearest = [...new Set(topics)].map((candidate) => ({ candidate, d: distance(key, compact(candidate)) })).sort((a, b) => a.d - b.d || a.candidate.localeCompare(b.candidate))[0];
+  return nearest && nearest.d <= Math.max(2, Math.floor(key.length / 3)) ? nearest.candidate : void 0;
+}
+const objectPaths = {
+  fill: [],
+  stroke: [],
+  anima: [],
+  meta: ["meta"],
+  color: ["colors", "*"],
+  glyph: ["glyphs", "*"],
+  hit: ["hit"],
+  timeline: ["timelines", "*"],
+  track: ["timelines", "*", "tracks"],
+  event: ["timelines", "*", "events", "*"],
+  layer: ["machine", "layers", "*"],
+  state: ["machine", "layers", "*", "states", "*"],
+  pose: ["machine", "layers", "*", "states", "*", "pose"],
+  ease: ["machine", "layers", "*", "states", "*", "on", "*", "ease"],
+  on: ["machine", "layers", "*", "states", "*", "on", "*"],
+  bool: ["inputs", "*"],
+  number: ["inputs", "*"],
+  trigger: ["inputs", "*"],
+  transition: ["machine", "layers", "*", "states", "*", "on", "*"],
+  listener: ["listeners", "*"],
+  input: ["inputs", "*"]
+};
+function markupLabel(shape, key) {
+  const name = markupName(shape, key);
+  if (name) return name;
+  if (shape?.element === "layout-item") return "(no attribute; use layout-* attributes)";
+  if (shape?.element) return "(no attribute; use <" + shape.element + ">)";
+  return "(no markup attribute)";
+}
+function objectPreview(shape) {
+  const entries = Object.entries(shape.p);
+  const shown = entries.slice(0, 6).map(([key, value]) => key + (value.k === "arr" ? "[]" : ""));
+  return "{ " + shown.join(", ") + (entries.length > shown.length ? ", \u2026" : "") + " }";
+}
+function shortShape(shape) {
+  switch (shape.k) {
+    case "str":
+      return shape.of ? shape.of.map((v) => JSON.stringify(v)).join(" | ") : "string";
+    case "num":
+      return "number";
+    case "bool":
+      return "bool";
+    case "any":
+      return "any";
+    case "node":
+      return "node";
+    case "alt":
+      return shape.of.map(shortShape).join(" | ");
+    case "tup":
+      return "[" + shape.of.map(shortShape).join(", ") + "]";
+    case "map":
+      return "map<" + shortShape(shape.of) + ">";
+    case "arr":
+      return shape.of.k === "obj" ? objectPreview(shape.of) + "[]" : "array<" + shortShape(shape.of) + ">";
+    case "obj":
+      return objectPreview(shape);
+  }
+}
+function shapeAt(path, root = DOC) {
+  let shape = root;
+  for (const key of path) {
+    if (shape.k === "obj") shape = shape.p[key];
+    else if (shape.k === "map" || shape.k === "arr") shape = shape.of;
+    else throw new Error("invalid schema registry path");
+  }
+  return shape;
+}
+function fields(path, root = DOC, topicName) {
+  let shape = shapeAt(path, root);
+  if (shape.k !== "obj") {
+    const p = shape.k === "map" ? { "<address>": shape.of } : shape.k === "tup" ? Object.fromEntries(shape.of.map((item, i) => [i === 0 ? "at" : "name", item])) : { [topicName === "ease" ? "curve" : "value"]: shape };
+    shape = { k: "obj", p };
+  }
+  return Object.entries(shape.p).map(([key, value]) => {
+    const composite = value.k === "obj" || value.k === "arr" && value.of.k === "obj";
+    return {
+      markup: markupLabel(value, key),
+      ani: key,
+      type: shortShape(value),
+      required: shape.req?.includes(key) ?? false,
+      ...value.default !== void 0 ? { default: value.default } : {},
+      ...value.feature ?? shape.feature ? { feature: value.feature ?? shape.feature } : {},
+      ...value.description ? { description: value.description } : {},
+      ...value.k === "num" && value.min !== void 0 ? { min: value.min } : {},
+      ...composite ? { details: topicName ? topicName + "." + key : key } : {}
+    };
+  });
+}
+const props = (rec) => Object.entries(rec).map(([name, prop]) => ({
+  name,
+  type: prop.type,
+  default: prop.def ?? null,
+  ...prop.min !== void 0 ? { min: prop.min } : {},
+  ...prop.max !== void 0 ? { max: prop.max } : {},
+  animatable: true,
+  ...prop.feature ? { feature: prop.feature } : {}
+}));
+const spellings = (type, paint) => nodeAttrs(type).filter((attr) => (!paint || attr.path[0] === paint) && attr.attr !== attr.path.join(".")).map((attr) => ({ markup: attr.attr, ani: attr.path.join(".") }));
+function typeInfo(type) {
+  return {
+    type,
+    fields: fields([], nodeShape(type), type),
+    spellings: spellings(type),
+    animatable: props({ ...COMMON, ...OWN[type] }),
+    static: [
+      "id",
+      "type",
+      "pivot",
+      ...Object.keys(STATIC[type]),
+      ...PAINTED.includes(type) ? ["fill", "stroke", "knockout"] : []
+    ]
+  };
+}
+function schemaTopics() {
+  const structural = [nodeShape("path").p, DOC.p].flatMap(
+    (record) => Object.entries(record).filter(([, value]) => value.k === "obj" || value.k === "arr" && value.of.k === "obj").map(([key, value]) => markupName(value, key) || key)
+  );
+  return [
+    .../* @__PURE__ */ new Set([
+      ...NODE_TYPES,
+      ...Object.keys(ELEMENTS),
+      ...structural,
+      ...Object.keys(objectPaths),
+      "a11y",
+      "fill",
+      "stroke"
+    ])
+  ].filter(Boolean);
+}
+function schemaTopic(topic) {
+  if (!topic) return topic;
+  const form = Object.entries(ELEMENTS).find(([, candidate]) => candidate.values?.kind === topic);
+  if (form) topic = form[0];
+  const [head, ...tail] = topic.split(".");
+  return [lookupTopic(head, schemaTopics(), "schema"), ...tail].join(".");
+}
+function nodeFieldFor(topic) {
+  return Object.entries(nodeShape("path").p).find(
+    ([key, value]) => key === topic || markupName(value, key) === topic
+  )?.[1] ?? DOC.p[topic];
+}
+function schemaData(topic) {
+  const nodeField = nodeFieldFor(topic);
+  const compositeField = nodeField && (nodeField.k === "arr" ? { ...nodeField.of, feature: nodeField.feature } : nodeField);
+  const objectFields = Object.hasOwn(objectPaths, topic) ? fields(
+    objectPaths[topic],
+    topic === "fill" || topic === "stroke" ? nodeShape("path").p[topic] : DOC,
+    topic
+  ) : ELEMENTS[topic] ? fields([], ELEMENTS[topic].shape, topic) : compositeField && compositeField.k === "obj" && !NODE_TYPES.includes(topic) ? fields([], compositeField, topic) : void 0;
+  if (topic === "a11y")
+    return {
+      topic,
+      scope: "node.a11y",
+      fields: fields([], nodeShape("path").p.a11y, topic),
+      actions: ["tap", "increase", "decrease", "focus"],
+      root: { scope: "doc.a11y (root icon semantics)", fields: fields(["a11y"], DOC, topic) }
+    };
+  if (objectFields)
+    return {
+      topic,
+      fields: objectFields,
+      ...topic === "fill" || topic === "stroke" ? {
+        [topic]: props(PAINT[topic]),
+        spellings: spellings("path", topic),
+        static: objectFields.filter((field) => !(field.ani in PAINT[topic])).map((field) => field.ani)
+      } : {}
+    };
+  if (NODE_TYPES.includes(topic))
+    return typeInfo(topic);
+  return void 0;
+}
+function allSchemaData() {
+  return {
+    nodeTypes: NODE_TYPES.map(typeInfo),
+    paint: { fill: props(PAINT.fill), stroke: props(PAINT.stroke) },
+    paintFields: {
+      fill: fields([], nodeShape("path").p.fill, "fill"),
+      stroke: fields([], nodeShape("path").p.stroke, "stroke")
+    }
+  };
+}
+function topicFeature(topic, data) {
+  if (NODE_TYPES.includes(topic)) return "core";
+  if (topic === "fill" || topic === "stroke") return "core";
+  const features = /* @__PURE__ */ new Set();
+  const take = (feature) => {
+    for (const name of String(feature ?? "").split("|")) if (name) features.add(name);
+  };
+  take(ELEMENTS[topic]?.shape.feature);
+  for (const field of data?.fields ?? []) take(field.feature);
+  if (!features.size) take(nodeFieldFor(topic)?.feature);
+  return [...features].sort().join(", ") || "core";
+}
+function exampleFiles() {
+  const result = [];
+  const visit = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = resolve(dir, entry.name);
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile() && entry.name.endsWith(".animl") && (path.includes("/examples/") || path.includes("/capabilities/")))
+        result.push(relative(ROOT, path));
+    }
+  };
+  visit(resolve(ROOT, "examples"));
+  visit(resolve(ROOT, "modules"));
+  return result.sort();
+}
+let cachedExamples;
+function examplesFor(topic, feature) {
+  cachedExamples ??= exampleFiles().map((path) => ({
+    path,
+    text: readFileSync(resolve(ROOT, path), "utf8")
+  }));
+  const terms = /* @__PURE__ */ new Set([topic, ...feature.split(/,\s*/).filter((name) => name !== "core")]);
+  const matches = cachedExamples.filter(({ path, text }) => {
+    for (const term of terms) {
+      if (path.startsWith("modules/" + term + "/")) return true;
+      if (text.toLowerCase().includes("<" + term.toLowerCase())) return true;
+      if (text.toLowerCase().includes(term.toLowerCase())) return true;
+    }
+    return false;
+  });
+  return matches.slice(0, 3).map((entry) => entry.path);
+}
+function metadata(topic, data) {
+  const page = data;
+  const requires = topicFeature(topic, page);
+  const examples = examplesFor(topic, requires);
+  return [
+    "Requires: " + requires,
+    "Docs: anima docs " + topic,
+    "Examples: " + (examples.length ? examples.join(", ") : "(none found)")
+  ].join("\n");
+}
+function fieldLine(field, prefix = "") {
+  return "  " + field.markup + " \u2194 " + prefix + field.ani + ": " + field.type + (field.required ? " (required)" : "") + ("default" in field ? " (default " + JSON.stringify(field.default) + ")" : "") + (field.feature ? " [" + field.feature + "]" : "") + (field.description ? " \u2014 " + field.description : "") + (field.details ? "; details: anima schema " + field.details : "");
+}
+function table(rows) {
+  return rows.map(
+    (row) => "  " + row.name.padEnd(12) + " " + row.type.padEnd(7) + " default " + JSON.stringify(row.default) + (row.min !== void 0 || row.max !== void 0 ? "  range [" + (row.min ?? "-\u221E") + ", " + (row.max ?? "\u221E") + "]" : "") + (row.feature ? " [" + row.feature + "]" : "")
+  ).join("\n");
+}
+const mapping = (rows) => rows.map((row) => "  " + row.markup + " \u2194 " + row.ani).join("\n");
+function showType(data) {
+  return data.type + "\n attributes (markup \u2194 .ani: type)\n" + data.fields.map((field) => fieldLine(field)).join("\n") + "\n animatable (address: <id>.<property>)\n" + table(data.animatable) + "\n not animatable: " + data.static.join(", ") + "\n markup \u2194 .ani\n" + mapping(data.spellings) + "\n module fields\n" + data.fields.filter((field) => field.feature).map((field) => "  " + field.ani + " [" + field.feature + "]").join("\n") + "\n" + metadata(data.type, data);
+}
+function showObject(topic, data) {
+  const prefix = topic === "fill" || topic === "stroke" ? topic + "." : "";
+  let text = topic + " (markup \u2194 .ani: type)\n" + data.fields.map((field) => fieldLine(field, prefix)).join("\n");
+  if (topic === "fill" || topic === "stroke")
+    text += "\n animatable (address: <id>." + topic + ".<field>)\n" + table(props(PAINT[topic]));
+  return text + "\n" + metadata(topic, data);
+}
+function schemaMiss(topic, io, json = false) {
+  const suggestion = nearestTopic(topic.split(".")[0], schemaTopics());
+  if (json) {
+    const suggestions = suggestion ? [suggestion] : [];
+    io.err(
+      JSON.stringify({
+        error: `no schema topic "${topic}"`,
+        suggestions,
+        help: "anima help schema"
+      })
+    );
+    return 2;
+  }
+  io.err(
+    suggestion ? 'no schema topic "' + topic + '"; did you mean "' + suggestion + '"? Try anima schema ' + suggestion + "\nSee 'anima schema --help'." : 'no schema topic "' + topic + `"
+See 'anima schema --help'.`
+  );
+  return 2;
+}
+function topicIndex(json, io) {
+  const base = new Set(NODE_TYPES);
+  const rows = schemaTopics().map((topic) => ({
+    topic,
+    kind: base.has(topic) ? "node" : "object",
+    summary: base.has(topic) ? topic + " node fields, animation addresses and markup spellings" : topic + " object/element fields and markup spellings",
+    open: "anima schema " + topic
+  })).sort(
+    (a, b) => Number(a.kind !== "node") - Number(b.kind !== "node") || a.topic.localeCompare(b.topic)
+  );
+  io.out(
+    json ? JSON.stringify({ topics: rows }) : rows.map((row) => row.topic + "	" + row.summary + "; open: " + row.open).join("\n")
+  );
+  return 0;
+}
+function schema(topic, full, json, io) {
+  if (full) {
+    io.out(JSON.stringify(jsonSchema(), null, 2));
+    return 0;
+  }
+  if (!topic) return topicIndex(json, io);
+  if (topic.includes(".")) {
+    const [head, ...path] = topic.split(".");
+    const canonical = schemaTopic(head);
+    const data2 = schemaData(canonical);
+    if (!data2) return schemaMiss(topic, io, json);
+    const key = path.join(".");
+    const field = data2.fields?.find(
+      (candidate) => candidate.ani === key || candidate.markup === key
+    );
+    if (!field) {
+      if (json)
+        io.err(
+          JSON.stringify({
+            error: `unknown schema field ${topic}`,
+            suggestions: [],
+            help: `anima schema ${canonical}`
+          })
+        );
+      else io.err("unknown schema field " + topic + "\nSee 'anima schema " + canonical + "'.");
+      return 2;
+    }
+    io.out(JSON.stringify({ topic, ...field }));
+    return 0;
+  }
+  topic = schemaTopic(topic);
+  const data = topic ? schemaData(topic) : void 0;
+  if (!topic || !data) return schemaMiss(topic ?? "", io, json);
+  if (json) {
+    io.out(JSON.stringify(data));
+    return 0;
+  }
+  if (topic === "a11y") {
+    const a11y = data;
+    const rows = a11y.fields.map((field) => fieldLine(field)).join("\n");
+    const rootRows = a11y.root.fields.map((field) => fieldLine(field)).join("\n");
+    io.out(
+      "node.a11y (node semantics; markup \u2194 .ani: type)\n" + rows + "\nActions: tap, increase, decrease, focus\n\ndoc.a11y (root icon semantics; markup \u2194 .ani: type)\n" + rootRows + "\n" + metadata(topic, data)
+    );
+    return 0;
+  }
+  if (NODE_TYPES.includes(topic))
+    io.out(showType(data));
+  else io.out(showObject(topic, data));
+  return 0;
+}
+function schemaAll(json, io) {
+  if (json) {
+    io.out(JSON.stringify(allSchemaData()));
+    return 0;
+  }
+  const pages = schemaTopics().map((topic) => {
+    const data = schemaData(topic);
+    if (!data) return "";
+    return NODE_TYPES.includes(topic) ? showType(data) : showObject(topic, data);
+  }).filter(Boolean);
+  io.out(pages.join("\n\n"));
+  return 0;
+}
+function schemaSearch(words, json, io) {
+  if (!words.trim()) {
+    io.err("--search needs at least one word\nSee 'anima schema --help'.");
+    return 2;
+  }
+  const entries = [];
+  for (const topic of schemaTopics()) {
+    const data = schemaData(topic);
+    if (!data) continue;
+    entries.push({ name: topic, description: "registry topic " + topic, kind: "type" });
+    for (const field of data.fields ?? []) {
+      if (field.markup !== field.ani)
+        entries.push({
+          name: topic + "." + field.markup,
+          description: [field.description, field.type, field.ani].filter(Boolean).join(" "),
+          kind: "field"
+        });
+      entries.push({
+        name: topic + "." + field.ani,
+        description: [field.description, field.type, field.markup].filter(Boolean).join(" "),
+        kind: "field"
+      });
+    }
+  }
+  const spec = readFileSync(resolve(ROOT, "spec/SPEC.md"), "utf8");
+  for (const match of spec.matchAll(/^\| \x60([^\x60]+)\x60 \| (?:error|warning) \| (.+) \|$/gm))
+    entries.push({ name: match[1], description: match[2], kind: "diagnostic" });
+  const terms = words.toLowerCase().trim().split(/\s+/);
+  const results = entries.map((entry) => ({
+    ...entry,
+    score: terms.reduce(
+      (score, term) => score + (entry.name.toLowerCase() === term ? 100 : entry.name.toLowerCase().includes(term) ? 10 : entry.description.toLowerCase().includes(term) ? 1 : 0),
+      0
+    )
+  })).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+  io.out(
+    json ? JSON.stringify({ results }) : results.map((entry) => entry.name + "	" + entry.kind + "	" + entry.description).join("\n")
+  );
+  return 0;
+}
+function filteredSchema(topic, options, json, io) {
+  if (options["editor-only"]) {
+    const result2 = { applicable: false, reason: "Anima has no editor-only entries", fields: [] };
+    io.out(json ? JSON.stringify(result2) : result2.reason);
+    return 0;
+  }
+  topic = schemaTopic(topic);
+  const nodeRows = (type, info) => info.fields.map((field) => {
+    const prop = COMMON[field.ani] ?? OWN[type][field.ani];
+    return {
+      ...field,
+      animatable: !!prop,
+      bindable: !!prop,
+      inherited: Object.hasOwn(COMMON, field.ani)
+    };
+  });
+  let rows;
+  if (!topic)
+    rows = NODE_TYPES.flatMap(
+      (type) => nodeRows(type, typeInfo(type)).map((field) => ({ ...field, ani: type + "." + field.ani }))
+    );
+  else if (NODE_TYPES.includes(topic))
+    rows = nodeRows(topic, typeInfo(topic));
+  else if (topic.includes(".")) {
+    const [type, key] = topic.split(".");
+    if (!NODE_TYPES.includes(type)) return schemaMiss(topic, io, json);
+    const data = schemaData(type);
+    const field = data.fields.find(
+      (candidate) => candidate.ani === key || candidate.markup === key
+    );
+    if (!field) return schemaMiss(topic, io, json);
+    rows = nodeRows(type, { fields: [field] });
+  } else {
+    const data = schemaData(topic);
+    if (!data) return schemaMiss(topic, io, json);
+    rows = (data.fields ?? []).map((field) => ({
+      ...field,
+      animatable: !!PAINT[topic]?.[field.ani],
+      bindable: !!PAINT[topic]?.[field.ani],
+      inherited: false
+    }));
+  }
+  const result = rows.filter(
+    (field) => (!options.animatable || field.animatable) && (!options.bindable || field.bindable) && (!options.inherited || field.inherited)
+  );
+  io.out(
+    json ? JSON.stringify({ topic, fields: result }) : result.map(
+      (field) => field.ani + ": " + field.type + "; animatable=" + field.animatable + " bindable=" + field.bindable + " inherited=" + field.inherited
+    ).join("\n")
+  );
+  return 0;
+}
+export {
+  distance,
+  filteredSchema,
+  lookupTopic,
+  schema,
+  schemaAll,
+  schemaSearch,
+  schemaTopic
+};

package/packages/cli/src/session.d.ts

@@ -0,0 +1,8 @@
+import type { Model } from 'animl';
+import { type ScriptOptions } from 'animl/internal/packages/core/src/script.js';
+export interface SessionIO {
+    out(s: string): void;
+    input?: AsyncIterable<string>;
+}
+/** One JSON reply per input line, including errors, without restarting the interpreter. */
+export declare function session(load: () => Model | undefined | Promise<Model | undefined>, io: SessionIO, opts?: ScriptOptions): Promise<number>;

package/packages/cli/src/session.js

@@ -0,0 +1,96 @@
+import { createInterface } from "node:readline";
+import { createScriptSession, ScriptError } from "animl/internal/packages/core/src/script.js";
+async function session(load, io, opts = {}) {
+  let model = await load();
+  if (!model) {
+    io.out(
+      JSON.stringify({
+        ok: false,
+        diagnostics: [
+          {
+            code: "session-load",
+            pointer: "",
+            message: "cannot load session document",
+            hint: "validate the file, fix diagnostics and start the session again"
+          }
+        ]
+      })
+    );
+    return 1;
+  }
+  let engine = createScriptSession(model, opts);
+  const lines = io.input ?? createInterface({ input: process.stdin, crlfDelay: Infinity });
+  for await (const raw of lines) {
+    try {
+      let cmd = raw.trim();
+      if (cmd.startsWith("{")) {
+        const request = JSON.parse(cmd);
+        if (!request || typeof request !== "object" || !("cmd" in request) || typeof request.cmd !== "string")
+          throw new ScriptError("JSON request needs a string cmd", 1);
+        cmd = request.cmd;
+      }
+      if (cmd.includes("\n") || cmd.includes("\r"))
+        throw new ScriptError("one command per request", 1);
+      if (cmd === "quit") {
+        io.out(JSON.stringify({ ok: true, quit: true }));
+        break;
+      }
+      if (cmd === "reload") {
+        const saved = model.doc.requires?.includes("data") ? engine.dataValues() : {};
+        const next = await load();
+        if (!next) {
+          io.out(
+            JSON.stringify({
+              ok: false,
+              diagnostics: [
+                {
+                  code: "session-reload",
+                  pointer: "",
+                  message: "reload failed",
+                  hint: "fix the file and retry reload"
+                }
+              ]
+            })
+          );
+          continue;
+        }
+        const replacement = createScriptSession(next, opts);
+        const restored = [], skipped = [];
+        for (const [path, value] of Object.entries(saved)) {
+          try {
+            replacement.execute(`data set ${path} ${JSON.stringify(value)}`);
+            restored.push(path);
+          } catch {
+            skipped.push(path);
+          }
+        }
+        replacement.execute("advance 0");
+        model = next;
+        engine = replacement;
+        io.out(JSON.stringify({ ok: true, reloaded: true, restored, skipped }));
+        continue;
+      }
+      const result = engine.execute(cmd);
+      io.out(JSON.stringify({ ok: result.diagnostics.length === 0, ...result }));
+    } catch (error) {
+      const e = error;
+      io.out(
+        JSON.stringify({
+          ok: false,
+          diagnostics: [
+            {
+              code: e.code ?? "session-command",
+              pointer: e.pointer ?? "",
+              message: e.message,
+              hint: e.hint ?? 'send a script command or {"cmd":"\u2026"}'
+            }
+          ]
+        })
+      );
+    }
+  }
+  return 0;
+}
+export {
+  session
+};

package/packages/cli/src/suggest.d.ts

@@ -0,0 +1,3 @@
+export declare const ALIASES: Readonly<Record<string, string>>;
+export declare function resolveAlias(word: string): string | undefined;
+export declare function suggest(word: string, candidates: readonly string[]): string[];

package/packages/cli/src/suggest.js

@@ -0,0 +1,62 @@
+const ALIASES = {
+  check: "validate",
+  lint: "validate",
+  show: "render",
+  draw: "render",
+  find: "search",
+  grep: "search",
+  topics: "docs"
+};
+function resolveAlias(word) {
+  return ALIASES[word];
+}
+function compact(word) {
+  return word.replace(/^--?/, "").toLowerCase();
+}
+function distance(source, target) {
+  const a = compact(source);
+  const b = compact(target);
+  const rows = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+  for (let i = 0; i <= a.length; i++) rows[i][0] = i;
+  for (let j = 0; j <= b.length; j++) rows[0][j] = j * 1.5;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const substitution = a[i - 1] === b[j - 1] ? 0 : 1.5;
+      let best = Math.min(
+        rows[i - 1][j] + 1,
+        rows[i][j - 1] + 1.5,
+        rows[i - 1][j - 1] + substitution
+      );
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+        best = Math.min(best, rows[i - 2][j - 2]);
+      rows[i][j] = best;
+    }
+  }
+  return rows[a.length][b.length];
+}
+function cutoff(word) {
+  const n = compact(word).length;
+  if (n <= 2) return 0.75;
+  if (n <= 4) return 1.6;
+  return Math.min(3.25, 1.1 + n * 0.3);
+}
+function suggest(word, candidates) {
+  const alias = resolveAlias(compact(word));
+  if (alias && candidates.includes(alias)) return [alias];
+  const needle = compact(word);
+  const ranked = candidates.map((candidate) => {
+    const name = compact(candidate);
+    const prefix = name.startsWith(needle) || needle.startsWith(name);
+    return { candidate, prefix, score: distance(word, candidate) };
+  }).filter(({ score, prefix }) => prefix || score <= cutoff(word)).sort(
+    (a, b) => Number(b.prefix) - Number(a.prefix) || a.score - b.score || a.candidate.localeCompare(b.candidate)
+  );
+  if (!ranked.length) return [];
+  const best = ranked[0].score;
+  return ranked.filter(({ prefix, score }) => prefix || score <= best + 0.75).slice(0, 3).map(({ candidate }) => candidate);
+}
+export {
+  ALIASES,
+  resolveAlias,
+  suggest
+};

package/packages/cli/src/video.d.ts

@@ -0,0 +1,2 @@
+/** CLI-only real-time WebM encoding; no browser or codec dependency ships in the runtime. */
+export declare function encodeVideo(frames: Buffer[], fps: number): Promise<Buffer>;