@flatkit/compiler 0.30.1 → 0.31.0

package/dist/cli/flatc.js

@@ -1,8 +1,566 @@
 import {
-  run
-} from "../chunk-MRB6DWJA.js";
-import "../chunk-LO4PABQX.js";
-import "../chunk-KXKX2RMX.js";
+  applyFixes,
+  docHasErrors,
+  formatDiagnostics,
+  lintDocReport,
+  programDiagnostics,
+  repairLoop
+} from "../chunk-UO7ZHNQT.js";
+import {
+  compileFlatpack,
+  packToJSON
+} from "../chunk-KXKX2RMX.js";
+
+// src/cli/flatc.ts
+import { readFileSync, writeFileSync, existsSync, readdirSync, watch, mkdirSync, copyFileSync } from "fs";
+import { resolve, dirname, basename, extname, join, relative, isAbsolute } from "path";
+import { parseProgramFull, parseFlatLib } from "@flatkit/engine/flatFormat";
+import { hasPackage } from "@flatkit/engine/stdlib";
+import { parseUnits } from "@flatkit/engine/dsl";
+import { sanitizeDoc } from "@flatkit/engine/validateDoc";
+import { unitsToFunctions } from "@flatkit/engine/scriptDoc";
+import { containerBBox, containerBBoxUnion } from "@flatkit/engine/groups";
+import { isInstance, isGroup } from "@flatkit/engine/layers";
+import { IDENTITY } from "@flatkit/engine/transform";
+import { FlatSyntaxError } from "@flatkit/engine/flatFormat";
+import { playHeadless } from "@flatkit/player/debug";
+var MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".avif": "image/avif",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg",
+  ".m4a": "audio/mp4",
+  // Fonts (RFC 8081 media types) — matches the editor's import (`font/woff2` default, FontFace API).
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf"
+  // NB: video (.mp4/.webm/…) intentionally omitted — no video runtime in the editor or player yet.
+};
+var mimeFor = (path) => MIME[extname(path).toLowerCase()] ?? "application/octet-stream";
+function isWithin(baseDir, target) {
+  const rel = relative(baseDir, target);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+function printHelp() {
+  process.stdout.write(`flatc \u2014 compile a FlatInk program into a .flatpack
+
+Usage:
+  flatc <program.flatink> [assets.flat \u2026] [-o output.flatpack]
+  flatc <program.flatink> --watch
+  flatc --play <program.flatink | scene.flatpack> --script <gestures.json>
+  flatc --render <program.flatink | scene.flatpack> -o out.png [--frame N] [--at k=v[,k2=v2]] [--scale S]
+  flatc --preview <library.flat> [--symbol NAME] [-o out.flatpack | --render -o out.png]
+  flatc <library.flat> [more.flat \u2026] --check
+
+  program.flatink   the program (composition + logic, text DSL)
+  assets.flat       visual asset libs (default: every .flat in the program's folder)
+  -o, --out         output file (default: <program>.flatpack \u2014 the CANONICAL name, JSON inside)
+  --assets MODE     media baking: 'inline' (default, base64 in the .flatpack) or 'external'
+                    (sidecar <out>.assets/ folder; asset.data = relative key \u2014 serve the folder and
+                    play with sameOriginAssetResolver(<flatpackUrl>))
+  --check           semantic lint only (no .flatpack); exits \u22600 on ERROR (warnings do not stop). Lints a
+                    program .flatink OR an asset library .flat (per-symbol; several .flat are merged)
+  --fix             apply the MECHANICAL repairs the diagnostics carry (missing separator, run-on line)
+                    and re-check, iterating. Writes the file AT MOST ONCE, and never a text it has not
+                    re-checked; a file it cannot repair is left untouched, mtime included. Implies --check.
+  --no-libs         do NOT auto-discover the .flat files sitting next to the program (use it in a working
+                    folder, where a neighbouring scratch file is not a dependency)
+  --watch           recompile on every change in the folder (agent \u2192 player loop)
+  --play            run the file WITHOUT a canvas, replay --script and print { sends, vars } (JSON)
+  --trace           (with --play) HUMAN-READABLE log per gesture: emitted sends + variable diff (debug)
+  --script <f>      JSON gesture script: [{ "type": "down|move|up|cancel", "x", "y" }, { "type": "set", "name", "value" }, { "type": "wait", "frames": N }, { "type": "wheel", "dy": N }]
+                    semantic (by NAME, the engine resolves coords): { "type": "drag", "source", "target" } \xB7 { "type": "tap", "target" }
+                    \xB7 { "type": "scratch", "target" } (sweeps a reveal zone) \xB7 { "type": "connect", "source", "target" } (pulls a link wire)
+                    { "type": "key", "name": "ArrowRight", "frames": N } holds a key (keys.<name> = 1) N steps, then releases it
+                    "wait" lets the simulation run N fixed steps (60 Hz): "every frame" + playhead advance like in real playback
+                    "expect" self-verifies: { "type": "expect", "sends": ["done"], "vars": { "score": 3 } } \u2192 exits \u22600 on mismatch
+                    (sends = sequence of names emitted SINCE the last expect; vars = current state). Great in CI.
+  --render          render a PNG IMAGE (headless skia): see what we draw (positioning)
+  --preview         wrap ONE symbol of a <library.flat> into a playable Doc (a single centered instance on an
+                    auto-sized stage) \u2192 a .flatpack to drop in the browser player, or a PNG with --render.
+                    No wrapper .flatink to author by hand. Output defaults to <library>.<symbol>.flatpack/.png
+  --symbol NAME     (with --preview) which symbol to wrap (default: the first in the lib)
+  --bbox all|frame0 (with --preview) auto-size to the UNION over all frames (default 'all', no clipping of
+                    drifting/rotating/growing motion) or just frame 0 ('frame0', the old behavior)
+  --pad N           (with --preview) padding in px around the symbol's bounds (default 24)
+  --set p=v[,p2=v2] set a SYMBOL's exposed params (works with --preview AND --render); a state param
+                    takes a state NAME
+                    or a number (e.g. --set door=open), others take a number \u2192 baked into the preview
+  --frame N         (with --render) target frame (default 0)
+  --at k=v[,k2=v2]  (with --render) force variables \u2192 capture a given state (e.g. a step of an escape)
+  --steps N         (with --render) run N fixed sim steps (60 Hz, every-frame) BEFORE capture \u2192 see a
+                    stateful act unfold without forcing every derived variable by hand in --at
+  --scale S|auto    (with --render) resolution factor (default 2); 'auto' picks one from the canvas size
+                    (enlarges small/thin assets so fine filaments stay legible, large assets stay 1x)
+  -h, --help        this help
+
+Media referenced by 'asset "id" "path" kind' are embedded (paths relative to the program).
+`);
+}
+function buildDocFromProgram(programPath, explicitFlats = [], assetMode = "inline", assetsDir = "", noLibs = false, srcOverride) {
+  const baseDir = dirname(programPath);
+  const programSrc = srcOverride ?? readFileSync(programPath, "utf8");
+  const prog = parseProgramFull(programSrc);
+  const flatPaths = new Set(explicitFlats.map((p) => resolve(p)));
+  if (!flatPaths.size && !noLibs) for (const f of readdirSync(baseDir).filter((f2) => f2.endsWith(".flat"))) flatPaths.add(join(baseDir, f));
+  const pkgFunctions = [];
+  const localResolved = /* @__PURE__ */ new Set();
+  for (const name of prog.imports ?? []) {
+    if (hasPackage(name)) continue;
+    const fink = join(baseDir, name + ".flatink");
+    const fflat = join(baseDir, name + ".flat");
+    if (!isWithin(baseDir, fink) || !isWithin(baseDir, fflat)) {
+      process.stderr.write(`flatc: package outside the program folder (ignored): "${name}"
+`);
+      continue;
+    }
+    let found = false;
+    if (existsSync(fink)) {
+      for (const f of unitsToFunctions(parseUnits(readFileSync(fink, "utf8")).units)) pkgFunctions.push(f, { ...f, name: `${name}.${f.name}` });
+      found = true;
+    }
+    if (existsSync(fflat)) {
+      flatPaths.add(fflat);
+      found = true;
+    }
+    if (found) localResolved.add(name);
+    else process.stderr.write(`flatc: package not found: "${name}" (neither stdlib, nor ${name}.flatink / ${name}.flat)
+`);
+  }
+  const assetSrcs = [...flatPaths].map((p) => {
+    const src = readFileSync(p, "utf8");
+    try {
+      parseFlatLib(src);
+    } catch (e) {
+      throw new Error(`${basename(p)}: ${e.message} (pass --no-libs to ignore the .flat files sitting next to the program)`, { cause: e });
+    }
+    if (programConstructsIn(src).length) process.stderr.write(`flatc: ${basename(p)}: looks like a PROGRAM saved as .flat \u2014 loaded as a symbol library, so its scene/object blocks are ignored. Rename it to .flatink, or pass --no-libs.
+`);
+    return src;
+  });
+  const media = {};
+  const mediaCopies = [];
+  for (const a of prog.assets ?? []) {
+    const mp = resolve(baseDir, a.data);
+    if (!isWithin(baseDir, mp)) {
+      process.stderr.write(`flatc: media outside the program folder (ignored): ${a.data}
+`);
+      continue;
+    }
+    if (!existsSync(mp)) {
+      process.stderr.write(`flatc: missing media (ignored): ${a.data}
+`);
+      continue;
+    }
+    const mime = mimeFor(mp);
+    if (assetMode === "external") {
+      const key = `${assetsDir}/${a.data.replace(/\\/g, "/")}`;
+      media[a.data] = { mime, data: key };
+      mediaCopies.push({ src: mp, key });
+    } else {
+      media[a.data] = { mime, data: `data:${mime};base64,${readFileSync(mp).toString("base64")}` };
+    }
+  }
+  let doc = compileFlatpack(programSrc, assetSrcs, media);
+  if (pkgFunctions.length) doc = { ...doc, functions: [...doc.functions ?? [], ...pkgFunctions] };
+  const stdImports = (doc.imports ?? []).filter(hasPackage);
+  doc = { ...doc, imports: stdImports.length ? stdImports : void 0 };
+  return { doc, flatLibs: flatPaths.size, packages: localResolved.size, media: Object.keys(media).length, mediaCopies, src: programSrc };
+}
+function compileOnce(programPath, explicitFlats, out, checkOnly, assetMode = "inline", noLibs = false, doFix = false) {
+  const outPath = out ? resolve(out) : join(dirname(programPath), basename(programPath, extname(programPath)) + ".flatpack");
+  const assetsDir = assetMode === "external" ? basename(outPath, extname(outPath)) + ".assets" : "";
+  const build = (src) => buildDocFromProgram(programPath, explicitFlats, assetMode, assetsDir, noLibs, src);
+  let parseRepaired = "";
+  if (doFix) {
+    let candidate = readFileSync(programPath, "utf8");
+    for (let pass = 0; pass < 10; pass++) {
+      try {
+        build(candidate);
+        break;
+      } catch (e) {
+        if (!(e instanceof FlatSyntaxError) || !e.fix) break;
+        const { text, applied } = applyFixes(candidate, [{ scope: "scene", line: e.line, col: e.col, severity: "error", message: e.message, fix: e.fix }]);
+        if (!applied) break;
+        candidate = text;
+        parseRepaired = candidate;
+        process.stderr.write(`flatc: --fix: repaired \`${e.message.split(":")[0]}\` in ${basename(programPath)}
+`);
+      }
+    }
+  }
+  let built;
+  try {
+    built = build(parseRepaired || void 0);
+  } catch (e) {
+    process.stderr.write(`flatc: compile error: ${e.message}
+`);
+    return 1;
+  }
+  const { doc } = built;
+  const diagnostics = programDiagnostics(doc, built.src);
+  const report = formatDiagnostics(diagnostics);
+  const hasErrors = diagnostics.some((d) => d.severity === "error");
+  if (doFix) {
+    const original = parseRepaired || readFileSync(programPath, "utf8");
+    const { text, applied: total, first, errors: before } = repairLoop(original, diagnostics, (src) => programDiagnostics(buildDocFromProgram(programPath, explicitFlats, assetMode, assetsDir, noLibs, src).doc, src));
+    if (!total && !parseRepaired) {
+      process.stderr.write(`flatc: --fix: nothing to repair mechanically${hasErrors ? " \u2014 the remaining errors need a decision, not a separator\n" : "\n"}`);
+    } else {
+      writeFileSync(programPath, text);
+      process.stderr.write(`flatc: --fix: ${total} repair(s) applied to ${basename(programPath)} \xB7 errors ${first} \u2192 ${before}
+`);
+      return compileOnce(programPath, explicitFlats, out, checkOnly, assetMode, noLibs, false);
+    }
+  }
+  if (checkOnly) {
+    if (report) process.stderr.write(report + "\n");
+    if (hasErrors) return 1;
+    const warnings = diagnostics.length;
+    process.stdout.write(`flatc: check passed \u2713${warnings ? ` \xB7 ${warnings} warning(s)` : ""}
+`);
+    return 0;
+  }
+  if (report) process.stderr.write(report + "\n");
+  writeFileSync(outPath, packToJSON(doc));
+  const outDir = dirname(outPath);
+  for (const c of built.mediaCopies) {
+    const dest = join(outDir, ...c.key.split("/"));
+    if (!isWithin(outDir, dest)) continue;
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(c.src, dest);
+  }
+  const where = assetMode === "external" ? ` (external \u2192 ${assetsDir}/)` : "";
+  process.stdout.write(`flatc: ${basename(outPath)} \u2713  ${doc.symbols.length} symbol(s) \xB7 ${built.flatLibs} lib(s) \xB7 ${built.packages} package(s) \xB7 ${built.media} media${where}
+`);
+  return 0;
+}
+function programConstructsIn(src) {
+  const found = [];
+  if (/^[ \t]*scene\s*\{/m.test(src)) found.push("a `scene { \u2026 }` block");
+  if (/^[ \t]*object\s+"/m.test(src)) found.push('`object "\u2026" { \u2026 }` blocks');
+  return found;
+}
+function checkFlatLibs(flatPaths) {
+  const symbols = [];
+  for (const p of flatPaths) {
+    let src;
+    try {
+      src = readFileSync(p, "utf8");
+    } catch (e) {
+      process.stderr.write(`flatc: cannot read: ${e.message}
+`);
+      return 1;
+    }
+    const disguised = programConstructsIn(src);
+    if (disguised.length) {
+      process.stderr.write(`flatc: ${basename(p)}: this is a PROGRAM, not a symbol library \u2014 it contains ${disguised.join(" and ")}, which a .flat never carries and which --check therefore does NOT verify. Rename it to .flatink.
+`);
+      return 1;
+    }
+    try {
+      symbols.push(...parseFlatLib(src).symbols);
+    } catch (e) {
+      process.stderr.write(`flatc: ${basename(p)}: ${e.message}
+`);
+      return 1;
+    }
+  }
+  const doc = { width: 1, height: 1, timeline: { fps: 24, durationFrames: 1, tracks: [] }, variables: {}, layers: [], symbols };
+  const report = lintDocReport(doc);
+  if (report) process.stderr.write(report + "\n");
+  if (docHasErrors(doc)) return 1;
+  const warnings = report ? report.split("\n").filter(Boolean).length : 0;
+  process.stdout.write(`flatc: check passed \u2713  ${symbols.length} symbol(s)${warnings ? ` \xB7 ${warnings} warning(s)` : ""}
+`);
+  return 0;
+}
+function loadDoc(filePath, noLibs = false) {
+  if (filePath.endsWith(".flatink")) return buildDocFromProgram(filePath, [], "inline", "", noLibs).doc;
+  return sanitizeDoc(JSON.parse(readFileSync(filePath, "utf8")));
+}
+function playOnce(filePath, scriptPath, trace, noLibs = false) {
+  if (!scriptPath) {
+    process.stderr.write("flatc: --play requires --script <gestures.json>\n");
+    return 1;
+  }
+  if (!existsSync(scriptPath)) {
+    process.stderr.write(`flatc: script not found: ${scriptPath}
+`);
+    return 1;
+  }
+  let doc, gestures;
+  try {
+    doc = loadDoc(filePath, noLibs);
+  } catch (e) {
+    process.stderr.write(`flatc: cannot read: ${e.message}
+`);
+    return 1;
+  }
+  try {
+    gestures = JSON.parse(readFileSync(scriptPath, "utf8"));
+  } catch (e) {
+    process.stderr.write(`flatc: invalid JSON script: ${e.message}
+`);
+    return 1;
+  }
+  if (!Array.isArray(gestures)) {
+    process.stderr.write("flatc: the script must be an array of gestures\n");
+    return 1;
+  }
+  const res = playHeadless(doc, gestures, { trace });
+  if (!trace) process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+  else
+    for (const s of res.steps ?? []) {
+      const send = (e) => e.fields ? `${e.name}{${Object.entries(e.fields).map(([k, v]) => `${k}=${v}`).join(", ")}}` : e.value !== void 0 ? `${e.name}=${e.value}` : e.name;
+      const sends = s.sends.length ? "  sends:[" + s.sends.map(send).join(", ") + "]" : "";
+      const vars = Object.entries(s.changed).map(([k, [a, b]]) => `${k}:${JSON.stringify(a)}\u2192${JSON.stringify(b)}`);
+      process.stdout.write(`${s.gesture.padEnd(28)}${sends}${vars.length ? "  vars{" + vars.join(" ") + "}" : ""}
+`);
+    }
+  if (res.expectFailures?.length) {
+    for (const f of res.expectFailures) process.stderr.write(`flatc: \u2717 ${f}
+`);
+    return 1;
+  }
+  return 0;
+}
+function parseVars(spec, into) {
+  for (const pair of spec.split(",")) {
+    const i = pair.indexOf("=");
+    if (i < 0) continue;
+    const k = pair.slice(0, i).trim();
+    const v = Number(pair.slice(i + 1).trim());
+    if (k && Number.isFinite(v)) into[k] = v;
+  }
+}
+function autoScale(w, h) {
+  const maxSide = Math.max(1, w, h), minSide = Math.max(1, Math.min(w, h));
+  return Math.max(1, Math.min(8, Math.round(Math.max(160 / maxSide, 48 / minSide))));
+}
+async function renderDocToFile(doc, outPath, frame, vars, scale, steps, params = {}) {
+  try {
+    const { renderDocToPng } = await import("./render.js");
+    const png = await renderDocToPng(doc, { frame, vars: Object.keys(vars).length ? vars : void 0, scale, steps: steps || void 0, params: Object.keys(params).length ? params : void 0 });
+    writeFileSync(outPath, png);
+  } catch (e) {
+    process.stderr.write(`flatc: render failed: ${e.message}
+`);
+    if (process.env.FLATC_DEBUG && e.stack) process.stderr.write(`${e.stack}
+`);
+    return 1;
+  }
+  process.stdout.write(`flatc: ${basename(outPath)} \u2713  ${doc.width}\xD7${doc.height} \xD7${scale}${frame ? ` \xB7 frame ${frame}` : ""}${steps ? ` \xB7 ${steps} step(s)` : ""}${Object.keys(vars).length ? ` \xB7 ${Object.entries(vars).map(([k, v]) => `${k}=${v}`).join(" ")}` : ""}
+`);
+  return 0;
+}
+async function renderOnce(filePath, out, frame, vars, scale, steps, scaleAuto, noLibs = false, params = {}) {
+  let doc;
+  try {
+    doc = loadDoc(filePath, noLibs);
+  } catch (e) {
+    process.stderr.write(`flatc: cannot read: ${e.message}
+`);
+    return 1;
+  }
+  const dur = doc.timeline?.durationFrames ?? 0;
+  if (dur > 0 && frame >= dur) process.stderr.write(`flatc: --frame ${frame} is past the timeline (durationFrames ${dur}); the playhead WRAPS, so this renders frame ${frame % dur}
+`);
+  const outPath = out ? resolve(out) : join(dirname(filePath), basename(filePath, extname(filePath)) + ".png");
+  return renderDocToFile(doc, outPath, frame, vars, scaleAuto ? autoScale(doc.width, doc.height) : scale, steps, params);
+}
+var gcd = (a, b) => {
+  a = Math.abs(a);
+  b = Math.abs(b);
+  while (b) {
+    const t = a % b;
+    a = b;
+    b = t;
+  }
+  return a || 1;
+};
+var lcm = (a, b) => Math.max(1, Math.round(a / gcd(a, b) * b));
+function* instancesOf(sym) {
+  const stack = [];
+  for (const l of sym.layers) stack.push(...l.items);
+  for (let it = stack.pop(); it; it = stack.pop()) {
+    if (isInstance(it)) yield it;
+    else if (isGroup(it)) for (const l of it.layers) stack.push(...l.items);
+  }
+}
+function previewDuration(root, symbols) {
+  const byId = new Map(symbols.map((s) => [s.id, s]));
+  const seen = /* @__PURE__ */ new Set();
+  let seam = Math.max(1, root.timeline?.durationFrames ?? 1);
+  let longest = seam;
+  const walk = (sym) => {
+    if (!sym || seen.has(sym.id)) return;
+    seen.add(sym.id);
+    for (const it of instancesOf(sym)) {
+      const child = byId.get(it.symbolId);
+      const cdur = Math.max(1, child?.timeline?.durationFrames ?? 1);
+      const mode = it.playback?.mode;
+      if (mode === "independent") {
+        seam = lcm(seam, cdur);
+        longest = Math.max(longest, cdur);
+      } else if (mode === "once") longest = Math.max(longest, cdur);
+      walk(child);
+    }
+  };
+  walk(root);
+  let dur = seam;
+  while (dur < longest) dur += seam;
+  return Math.min(dur, 6e3);
+}
+function buildPreviewDoc(flatPath, symbolName, pad, bboxMode, setSpec = {}) {
+  const { symbols } = parseFlatLib(readFileSync(flatPath, "utf8"));
+  if (!symbols.length) throw new Error("no symbols found in this .flat library");
+  let symbol = symbols[0];
+  if (symbolName) {
+    const found = symbols.find((s) => s.name === symbolName);
+    if (!found) throw new Error(`symbol "${symbolName}" not found \u2014 available: ${symbols.map((s) => s.name).join(", ")}`);
+    symbol = found;
+  }
+  const instance = { id: "preview_instance", kind: "instance", name: symbol.name, transform: { ...IDENTITY }, symbolId: symbol.id };
+  const layer = { id: "preview_layer", name: "preview", visible: true, locked: false, opacity: 1, items: [instance] };
+  const tl = symbol.timeline;
+  const dur = previewDuration(symbol, symbols);
+  const timeline = { fps: tl?.fps ?? 24, durationFrames: dur, tracks: [] };
+  let doc = { width: 1, height: 1, layers: [layer], symbols, timeline };
+  const sampleFrames = (n) => {
+    const step = Math.max(1, Math.ceil(n / 240));
+    const fs = [];
+    for (let f = 0; f < n; f += step) fs.push(f);
+    if (fs[fs.length - 1] !== n - 1) fs.push(n - 1);
+    return fs;
+  };
+  const bb = bboxMode === "all" ? containerBBoxUnion(doc, instance, sampleFrames(dur)) : containerBBox(doc, instance, 0);
+  if (bb) {
+    doc = { ...doc, width: Math.max(1, Math.ceil(bb.maxX - bb.minX) + pad * 2), height: Math.max(1, Math.ceil(bb.maxY - bb.minY) + pad * 2) };
+    instance.transform = { ...IDENTITY, e: pad - bb.minX, f: pad - bb.minY };
+  } else {
+    doc = { ...doc, width: 512, height: 512 };
+    instance.transform = { ...IDENTITY, e: 256, f: 256 };
+  }
+  const entries = Object.entries(setSpec);
+  if (entries.length) {
+    const known = /* @__PURE__ */ new Set([...(symbol.states ?? []).map((s) => s.param), ...(symbol.params ?? []).map((p) => p.name)]);
+    for (const [k, v] of entries) {
+      if (!known.has(k)) process.stderr.write(`flatc: --set ${k}: "${symbol.name}" exposes no such param (${[...known].join(", ") || "none"})
+`);
+      else (instance.params ??= {})[k] = v;
+    }
+  }
+  return { doc, symbol, others: symbols.filter((s) => s !== symbol).map((s) => s.name) };
+}
+async function previewOnce(flatPath, symbolName, out, frame, vars, scale, steps, doRender, pad, bboxMode, setSpec, scaleAuto) {
+  let built;
+  try {
+    built = buildPreviewDoc(flatPath, symbolName, pad, bboxMode, setSpec);
+  } catch (e) {
+    process.stderr.write(`flatc: ${e.message}
+`);
+    return 1;
+  }
+  const { doc, symbol, others } = built;
+  const stem = `${basename(flatPath, extname(flatPath))}.${symbol.name}`;
+  let code;
+  if (doRender) {
+    const sc = scaleAuto ? autoScale(doc.width - 2 * pad, doc.height - 2 * pad) : scale;
+    code = await renderDocToFile(doc, out ? resolve(out) : join(dirname(flatPath), stem + ".png"), frame, vars, sc, steps);
+  } else {
+    const outPath = out ? resolve(out) : join(dirname(flatPath), stem + ".flatpack");
+    writeFileSync(outPath, packToJSON(doc));
+    process.stdout.write(`flatc: ${basename(outPath)} \u2713  preview of "${symbol.name}" \xB7 ${doc.width}\xD7${doc.height} \xB7 play it in the browser player
+`);
+    code = 0;
+  }
+  if (!symbolName && others.length) process.stderr.write(`flatc: previewed "${symbol.name}"; other symbols in this lib: ${others.join(", ")} (pick with --symbol <name>)
+`);
+  return code;
+}
+function run(argv) {
+  const args = argv.slice(2);
+  let out = "", scriptPath = "", symbolName = "";
+  let checkOnly = false, doFix = false, doWatch = false, doPlay = false, doRender = false, doTrace = false, doPreview = false, noLibs = false;
+  let frame = 0, scale = 2, steps = 0, pad = 24;
+  let scaleAuto = false;
+  let bboxMode = "all";
+  let assetMode = "inline";
+  const vars = {};
+  const setSpec = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "-o" || a === "--out") out = args[++i] ?? "";
+    else if (a === "--script") scriptPath = resolve(args[++i] ?? "");
+    else if (a === "--assets") assetMode = args[++i] === "external" ? "external" : "inline";
+    else if (a === "--check") checkOnly = true;
+    else if (a === "--fix") {
+      doFix = true;
+      checkOnly = true;
+    } else if (a === "--no-libs") noLibs = true;
+    else if (a === "--watch") doWatch = true;
+    else if (a === "--play") doPlay = true;
+    else if (a === "--trace") doTrace = true;
+    else if (a === "--render") doRender = true;
+    else if (a === "--preview") doPreview = true;
+    else if (a === "--symbol") symbolName = args[++i] ?? "";
+    else if (a === "--pad") pad = Math.max(0, Number(args[++i] ?? "24") || 0);
+    else if (a === "--bbox") bboxMode = args[++i] === "frame0" ? "frame0" : "all";
+    else if (a === "--frame") frame = Number(args[++i] ?? "0") || 0;
+    else if (a === "--steps") steps = Math.max(0, Number(args[++i] ?? "0") || 0);
+    else if (a === "--scale") {
+      const v = args[++i] ?? "2";
+      if (v === "auto") scaleAuto = true;
+      else scale = Number(v) || 2;
+    } else if (a === "--at") parseVars(args[++i] ?? "", vars);
+    else if (a === "--set") for (const pair of (args[++i] ?? "").split(",")) {
+      const j = pair.indexOf("=");
+      if (j > 0) setSpec[pair.slice(0, j).trim()] = pair.slice(j + 1).trim();
+    }
+    else if (a === "-h" || a === "--help") {
+      printHelp();
+      return 0;
+    } else positional.push(a);
+  }
+  if (!positional.length) {
+    printHelp();
+    return 1;
+  }
+  const filePath = resolve(positional[0]);
+  if (!existsSync(filePath)) {
+    process.stderr.write(`flatc: not found: ${filePath}
+`);
+    return 1;
+  }
+  const explicitFlats = positional.slice(1);
+  if (doPreview) return previewOnce(filePath, symbolName, out, frame, vars, scale, steps, doRender, pad, bboxMode, setSpec, scaleAuto);
+  if (doRender) return renderOnce(filePath, out, frame, vars, scale, steps, scaleAuto, noLibs, setSpec);
+  if (doPlay) return playOnce(filePath, scriptPath, doTrace, noLibs);
+  const action = checkOnly && filePath.endsWith(".flat") ? () => checkFlatLibs([filePath, ...explicitFlats]) : () => compileOnce(filePath, explicitFlats, out, checkOnly, assetMode, noLibs, doFix);
+  if (doWatch) {
+    const code = action();
+    const baseDir = dirname(filePath);
+    let timer;
+    watch(baseDir, { recursive: false }, (_e, filename) => {
+      if (filename && (filename.endsWith(".flatpack") || filename.endsWith(".flatpack.json"))) return;
+      clearTimeout(timer);
+      timer = setTimeout(action, 80);
+    });
+    process.stdout.write(`flatc: watching ${baseDir} \u2026 (Ctrl+C to stop)
+`);
+    return code;
+  }
+  return action();
+}
 export {
   run
 };