@flatkit/compiler 0.23.0 → 0.25.0

package/dist/{chunk-HRWULWIL.js → chunk-MRRRN2CS.js}

@@ -1,84 +1,6 @@
-// src/lint.ts
-import { analyzeExpr, STD_CONSTANTS, STD_FUNCTIONS, STD_IDS, STD_OBJECTS } from "@flatkit/engine/expr";
-import { packageFunctionNames } from "@flatkit/engine/stdlib";
-import { parseUnits } from "@flatkit/engine/dsl";
-function collectAssigned(actions, into) {
-  for (const a of actions) {
-    if (a.do === "setVar") into.add(a.name);
-    else if (a.do === "if") {
-      collectAssigned(a.then, into);
-      if (a.else) collectAssigned(a.else, into);
-    } else if (a.do === "repeat") collectAssigned(a.body, into);
-    else if (a.do === "repeatRange") {
-      into.add(a.var);
-      collectAssigned(a.body, into);
-    }
-  }
-}
-function localVariables(units) {
-  const vars = /* @__PURE__ */ new Set();
-  for (const u of units) {
-    if (u.kind === "declare") vars.add(u.name);
-    else if (u.kind === "event" || u.kind === "frameActions") collectAssigned(u.body, vars);
-    else if (u.kind === "each") vars.add(u.as);
-    else if (u.kind === "interactor") {
-      if (u.varX) vars.add(u.varX);
-      if (u.varY) vars.add(u.varY);
-    } else if (u.kind === "drop") collectAssigned(u.body, vars);
-    else if (u.kind === "func") {
-      for (const p of u.func.params) vars.add(p);
-      if (u.func.kind === "proc") collectAssigned(u.func.body, vars);
-    }
-  }
-  return vars;
-}
-var TEXT_CALL = /\btext\s*\(/;
-var SECOND_ASSIGN = /[\w\]]\s*=(?![=])/;
-var SECOND_ACTION = /\b(send|play|pause|sound|set|go|repeat)\b/;
-function lint(src, ctx = {}) {
-  const { units, diagnostics, sites } = parseUnits(src);
-  const out = [...diagnostics];
-  const variables = localVariables(units);
-  for (const v of ctx.variables ?? []) variables.add(v);
-  const knownIds = /* @__PURE__ */ new Set([...STD_IDS, ...STD_CONSTANTS, ...variables]);
-  const knownFns = new Set(STD_FUNCTIONS);
-  knownFns.add("velocity");
-  for (const u of units) {
-    if (u.kind === "func") knownFns.add(u.func.name);
-    else if (u.kind === "use") for (const name of packageFunctionNames(u.name)) knownFns.add(name);
-  }
-  for (const f of ctx.functions ?? []) knownFns.add(f);
-  const knownObjs = new Set(STD_OBJECTS);
-  for (const o of ctx.objects ?? []) knownObjs.add(o);
-  const labels = ctx.labels ? new Set(ctx.labels) : null;
-  for (const s of sites) {
-    if (s.kind === "expr") {
-      if (TEXT_CALL.test(s.text)) {
-        out.push({ line: s.line, col: s.col, message: 'text("\u2026") is only allowed as an argument to "send"' });
-        continue;
-      }
-      const a = analyzeExpr(s.text);
-      if (!a.ok) {
-        const leftover = SECOND_ASSIGN.test(s.text) ? "an assignment" : SECOND_ACTION.test(s.text) ? `\`${SECOND_ACTION.exec(s.text)[1]} \u2026\`` : "";
-        const message = leftover ? `two statements on one line \u2014 ${leftover} was swallowed into the expression before it. FlatInk ends a statement at the NEWLINE: put each action on its own line.` : `invalid expression: ${a.error}`;
-        out.push({ line: s.line, col: s.col, message });
-        continue;
-      }
-      for (const fn of a.refs.calls) if (!knownFns.has(fn)) out.push({ line: s.line, col: s.col, message: `unknown function "${fn}"` });
-      for (const o of a.refs.members)
-        if (!knownObjs.has(o)) out.push({ line: s.line, col: s.col, message: `unknown object "${o}" (expected: ${[...knownObjs].join(", ")})` });
-      for (const id of a.refs.ids)
-        if (!knownIds.has(id))
-          out.push({ line: s.line, col: s.col, message: `unknown variable "${id}"${variables.size ? "" : ' \u2014 declare it with "let"'}` });
-    } else if (labels && !labels.has(s.name)) {
-      out.push({ line: s.line, col: s.col, message: `unknown label "${s.name}"` });
-    }
-  }
-  return out.sort((a, b) => a.line - b.line || a.col - b.col);
-}
-function lintReport(src, ctx = {}) {
-  return lint(src, ctx).map((d) => `${d.line}:${d.col}: ${d.message}`).join("\n");
-}
+import {
+  compileFlatpack
+} from "./chunk-KXKX2RMX.js";
 
 // src/scopeProgram.ts
 function matchBrace(s, open) {
@@ -165,17 +87,170 @@ function joinScopeProgram(rest, objects) {
   return parts.length ? parts.join("\n\n") + "\n" : "";
 }
 
+// src/lint.ts
+import { analyzeExpr, STD_CONSTANTS, STD_FUNCTIONS, STD_IDS, STD_OBJECTS } from "@flatkit/engine/expr";
+import { packageFunctionNames } from "@flatkit/engine/stdlib";
+import { parseUnits } from "@flatkit/engine/dsl";
+function collectAssigned(actions, into) {
+  for (const a of actions) {
+    if (a.do === "setVar") into.add(a.name);
+    else if (a.do === "if") {
+      collectAssigned(a.then, into);
+      if (a.else) collectAssigned(a.else, into);
+    } else if (a.do === "repeat") collectAssigned(a.body, into);
+    else if (a.do === "repeatRange") {
+      into.add(a.var);
+      collectAssigned(a.body, into);
+    }
+  }
+}
+function localVariables(units) {
+  const vars = /* @__PURE__ */ new Set();
+  for (const u of units) {
+    if (u.kind === "declare") vars.add(u.name);
+    else if (u.kind === "event" || u.kind === "frameActions") collectAssigned(u.body, vars);
+    else if (u.kind === "each") vars.add(u.as);
+    else if (u.kind === "interactor") {
+      if (u.varX) vars.add(u.varX);
+      if (u.varY) vars.add(u.varY);
+    } else if (u.kind === "drop") collectAssigned(u.body, vars);
+    else if (u.kind === "func") {
+      for (const p of u.func.params) vars.add(p);
+      if (u.func.kind === "proc") collectAssigned(u.func.body, vars);
+    }
+  }
+  return vars;
+}
+var TEXT_CALL = /\btext\s*\(/;
+var SECOND_ASSIGN = /[\w\]]\s*=(?![=])/;
+var SECOND_ACTION = /\b(send|play|pause|sound|set|go|repeat)\b/;
+function lint(src, ctx = {}) {
+  const { units, diagnostics, sites } = parseUnits(src);
+  const out = [...diagnostics];
+  const variables = localVariables(units);
+  for (const v of ctx.variables ?? []) variables.add(v);
+  const knownIds = /* @__PURE__ */ new Set([...STD_IDS, ...STD_CONSTANTS, ...variables]);
+  const knownFns = new Set(STD_FUNCTIONS);
+  knownFns.add("velocity");
+  for (const u of units) {
+    if (u.kind === "func") knownFns.add(u.func.name);
+    else if (u.kind === "use") for (const name of packageFunctionNames(u.name)) knownFns.add(name);
+  }
+  for (const f of ctx.functions ?? []) knownFns.add(f);
+  const knownObjs = new Set(STD_OBJECTS);
+  for (const o of ctx.objects ?? []) knownObjs.add(o);
+  const labels = ctx.labels ? new Set(ctx.labels) : null;
+  for (const s of sites) {
+    if (s.kind === "expr") {
+      if (TEXT_CALL.test(s.text)) {
+        out.push({ line: s.line, col: s.col, message: 'text("\u2026") is only allowed as an argument to "send"' });
+        continue;
+      }
+      const a = analyzeExpr(s.text);
+      if (!a.ok) {
+        const leftover = SECOND_ASSIGN.test(s.text) ? "an assignment" : SECOND_ACTION.test(s.text) ? `\`${SECOND_ACTION.exec(s.text)[1]} \u2026\`` : "";
+        const message = leftover ? `two statements on one line \u2014 ${leftover} was swallowed into the expression before it. FlatInk ends a statement at the NEWLINE: put each action on its own line.` : `invalid expression: ${a.error}`;
+        out.push({ line: s.line, col: s.col, message });
+        continue;
+      }
+      for (const fn of a.refs.calls) if (!knownFns.has(fn)) out.push({ line: s.line, col: s.col, message: `unknown function "${fn}"` });
+      for (const o of a.refs.members)
+        if (!knownObjs.has(o)) out.push({ line: s.line, col: s.col, message: `unknown object "${o}" (expected: ${[...knownObjs].join(", ")})` });
+      for (const id of a.refs.ids)
+        if (!knownIds.has(id))
+          out.push({ line: s.line, col: s.col, message: `unknown variable "${id}"${variables.size ? "" : ' \u2014 declare it with "let"'}` });
+    } else if (labels && !labels.has(s.name)) {
+      out.push({ line: s.line, col: s.col, message: `unknown label "${s.name}"` });
+    }
+  }
+  return out.sort((a, b) => a.line - b.line || a.col - b.col);
+}
+function lintReport(src, ctx = {}) {
+  return lint(src, ctx).map((d) => `${d.line}:${d.col}: ${d.message}`).join("\n");
+}
+
 // src/programDoc.ts
 import { printUnits } from "@flatkit/engine/dsl";
 import { functionsToUnits, importsToUnits, objectToUnits, timelineToUnits, variablesToUnits } from "@flatkit/engine/scriptDoc";
-import { contextLayers, getScopeTimeline, isContainer, isGroup, isText, isImage, isPoseable, isRegion } from "@flatkit/engine/layers";
+import { contextLayers, getScopeTimeline, isContainer, isGroup as isGroup2, isInstance, isText, isImage, isPoseable as isPoseable2, isRegion } from "@flatkit/engine/layers";
 import { importedFunctions } from "@flatkit/engine/stdlib";
-import { EXPR_CHANNELS } from "@flatkit/engine/timeline";
+import { EXPR_CHANNELS as EXPR_CHANNELS2 } from "@flatkit/engine/timeline";
 import { objectNames } from "@flatkit/engine/sceneRefs";
 import { behaviorRegions } from "@flatkit/engine/flatFormat";
-import { itemBBox, dropZoneBounds } from "@flatkit/engine/groups";
+import { itemBBox, dropZoneBounds, transformBBox } from "@flatkit/engine/groups";
+import { IDENTITY, apply, compose } from "@flatkit/engine/transform";
 import { makePathSampler } from "@flatkit/engine/path";
 import { bboxIntersects } from "@flatkit/engine/bbox";
+
+// src/docWalk.ts
+import { isGroup, isPoseable } from "@flatkit/engine/layers";
+import { EXPR_CHANNELS } from "@flatkit/engine/timeline";
+function forEachActionIn(actions, fn) {
+  for (const a of actions ?? []) {
+    fn(a);
+    if (a.do === "if") {
+      forEachActionIn(a.then, fn);
+      forEachActionIn(a.else, fn);
+    } else if (a.do === "repeat" || a.do === "repeatRange") forEachActionIn(a.body, fn);
+  }
+}
+function forEachAction(doc, fn) {
+  for (const i of doc.interactions ?? []) forEachActionIn(i.actions, fn);
+  for (const f of doc.functions ?? []) if (f.kind === "proc") forEachActionIn(f.body, fn);
+  for (const t of [doc.timeline, ...(doc.symbols ?? []).map((s) => s.timeline)]) {
+    if (!t) continue;
+    forEachActionIn(t.onLoad, fn);
+    forEachActionIn(t.onEnterFrame, fn);
+    for (const fa of t.frameActions ?? []) forEachActionIn(fa.actions, fn);
+  }
+}
+function forEachActionExpression(actions, fn) {
+  forEachActionIn(actions, (a) => {
+    if (a.do === "setVar" || a.do === "setParam") fn(a.value);
+    else if (a.do === "setIndex") {
+      fn(a.value);
+      fn(a.index);
+    } else if (a.do === "if") fn(a.cond);
+    else if (a.do === "repeat") fn(a.count);
+    else if (a.do === "repeatRange") {
+      fn(a.from);
+      fn(a.to);
+    } else if (a.do === "call") for (const arg of a.args) fn(arg);
+    else if (a.do === "send" && a.payload?.kind === "expr") fn(a.payload.expr);
+    else if (a.do === "send" && a.payload?.kind === "record") for (const f of a.payload.fields) fn(f.expr);
+  });
+}
+function forEachItemExpression(it, fn) {
+  if (!isPoseable(it)) return;
+  if (it.expressions) for (const k of Object.keys(it.expressions)) {
+    const e = it.expressions[k];
+    if (e) fn(e, k);
+  }
+  if (it.modifiers) for (const ch of EXPR_CHANNELS) {
+    const m = it.modifiers[ch];
+    if (m) fn(m.target, ch);
+  }
+}
+function forEachExpression(doc, fn) {
+  const visit = (items) => {
+    for (const it of items) {
+      forEachItemExpression(it, (e) => fn(e));
+      if (isGroup(it)) for (const l of it.layers) visit(l.items);
+    }
+  };
+  for (const l of doc.layers) visit(l.items);
+  for (const s of doc.symbols ?? []) for (const l of s.layers) visit(l.items);
+  for (const i of doc.interactions ?? []) forEachActionExpression(i.actions, fn);
+  for (const f of doc.functions ?? []) if (f.kind === "proc") forEachActionExpression(f.body, fn);
+  for (const t of [doc.timeline, ...(doc.symbols ?? []).map((s) => s.timeline)]) {
+    if (!t) continue;
+    forEachActionExpression(t.onLoad, fn);
+    forEachActionExpression(t.onEnterFrame, fn);
+    for (const fa of t.frameActions ?? []) forEachActionExpression(fa.actions, fn);
+  }
+}
+
+// src/programDoc.ts
 import { parseUnits as parseUnits2 } from "@flatkit/engine/dsl";
 function scopeProgram(doc, editPath = []) {
   const atRoot = editPath.length === 0;
@@ -227,7 +302,7 @@ function itemNameById(doc, id) {
         found = it.name ?? null;
         return;
       }
-      if (isGroup(it)) walk(it.layers);
+      if (isGroup2(it)) walk(it.layers);
     }
   };
   walk(doc.layers);
@@ -254,6 +329,39 @@ function functionsReadingTime(doc) {
     if (reads.size === before) return [...reads];
   }
 }
+function callArguments(src, name) {
+  const out = [];
+  const re = new RegExp(`(?<![\\w.])${escapeRe(name)}\\s*\\(`, "g");
+  let m;
+  while (m = re.exec(src)) {
+    const args = [];
+    let depth = 1;
+    let start = m.index + m[0].length;
+    let i = start;
+    for (; i < src.length; i++) {
+      const c = src[i];
+      if (c === "(") depth++;
+      else if (c === ")") {
+        depth--;
+        if (depth === 0) break;
+      } else if (c === "," && depth === 1) {
+        args.push(src.slice(start, i));
+        start = i + 1;
+      }
+    }
+    args.push(src.slice(start, i));
+    out.push(args.map((a) => a.trim()));
+  }
+  return out;
+}
+var INSTANT_ARG = { pulse: 0, shake: 1 };
+function timeCapturedVars(doc) {
+  const out = /* @__PURE__ */ new Set();
+  forEachAction(doc, (a) => {
+    if (a.do === "setVar" && /\btime\b/.test(a.value) && !/\bclock\b/.test(a.value)) out.add(a.name);
+  });
+  return out;
+}
 function docStructureWarnings(doc) {
   const out = [];
   const names = new Set(objectNames(doc.layers));
@@ -268,11 +376,11 @@ function docStructureWarnings(doc) {
     const modTargets = [];
     const collectMods = (items) => {
       for (const it of items) {
-        if (isPoseable(it) && it.modifiers) for (const ch of EXPR_CHANNELS) {
+        if (isPoseable2(it) && it.modifiers) for (const ch of EXPR_CHANNELS2) {
           const mm = it.modifiers[ch];
           if (mm) modTargets.push(mm.target);
         }
-        if (isGroup(it)) for (const l of it.layers) collectMods(l.items);
+        if (isGroup2(it)) for (const l of it.layers) collectMods(l.items);
       }
     };
     for (const l of doc.layers) collectMods(l.items);
@@ -283,6 +391,19 @@ function docStructureWarnings(doc) {
       if ((m?.length ?? 0) <= 1) out.push({ scope: "scene", diag: { line: 1, col: 1, severity: "warning", message: `global variable "${name}" never used (declared, but neither read nor written)` } });
     }
   }
+  const missing = /* @__PURE__ */ new Set();
+  const scanRefs = (items) => {
+    for (const it of items) {
+      if (isInstance(it) && it.symbolId.startsWith("@")) missing.add(it.symbolId.slice(1));
+      if (isGroup2(it)) for (const l of it.layers) scanRefs(l.items);
+    }
+  };
+  for (const l of doc.layers) scanRefs(l.items);
+  for (const s of doc.symbols ?? []) for (const l of s.layers) scanRefs(l.items);
+  if (missing.size) {
+    const names2 = [...missing].map((n) => `"${n}"`).join(", ");
+    out.push(warn(`instance resolves to no symbol: ${names2} \u2014 nothing is drawn where it stands. Pass the .flat library that defines it (\`flatc <program> <lib.flat>\`, or place it beside the program), or fix the name.`));
+  }
   const dur = doc.timeline?.durationFrames ?? 60;
   const fps = doc.timeline?.fps ?? 24;
   if (dur <= 120) {
@@ -290,12 +411,12 @@ function docStructureWarnings(doc) {
     const culprits = /* @__PURE__ */ new Set();
     const scan = (layers) => {
       for (const l of layers) for (const it of l.items) {
-        if (isPoseable(it) && it.expressions) for (const k in it.expressions) {
+        if (isPoseable2(it) && it.expressions) for (const k in it.expressions) {
           const expr = it.expressions[k] ?? "";
           if (/\btime\b/.test(expr)) culprits.add("`time`");
           for (const fn of viaFn) if (new RegExp(`\\b${escapeRe(fn)}\\s*\\(`).test(expr)) culprits.add(`\`${fn}()\` (which reads \`time\`)`);
         }
-        if (isGroup(it)) scan(it.layers);
+        if (isGroup2(it)) scan(it.layers);
       }
     };
     scan(doc.layers);
@@ -304,6 +425,28 @@ function docStructureWarnings(doc) {
       out.push(warn(`a channel expression uses ${[...culprits].join(" and ")}, but the timeline loops every ${secs}s (durationFrames ${dur}) \u2014 \`time\` resets each loop, so the motion jumps (a one-shot ramp REPLAYS forever). Use the monotone \`clock\` (never wraps), drive it by \`frame/${dur}\`, or set a longer \`timeline\`.`));
     }
   }
+  const captured = timeCapturedVars(doc);
+  if (captured.size) {
+    const readers = /* @__PURE__ */ new Map();
+    forEachExpression(doc, (expr) => {
+      for (const fnName of Object.keys(INSTANT_ARG)) {
+        for (const args of callArguments(expr, fnName)) {
+          const arg = args[INSTANT_ARG[fnName]];
+          if (!arg) continue;
+          for (const v of captured) {
+            if (!new RegExp(`(?<![\\w-])${escapeRe(v)}(?![\\w-])`).test(arg)) continue;
+            const seen = readers.get(v) ?? /* @__PURE__ */ new Set();
+            seen.add(fnName);
+            readers.set(v, seen);
+          }
+        }
+      }
+    });
+    for (const [v, fns] of readers) {
+      const who = [...fns].map((f) => `\`${f}()\``).join(" and ");
+      out.push(warn(`"${v}" is captured on \`time\` but read as an INSTANT by ${who}, which compares it against the monotone \`clock\` \u2014 the two axes never meet, so the ramp never fires and nothing on screen says so. Capture it with \`clock\` instead: \`${v} = clock\`.`));
+    }
+  }
   out.push(...docPaintParamWarnings(doc));
   out.push(...docCelLayerWarnings(doc));
   out.push(...docLayoutWarnings(doc));
@@ -321,9 +464,9 @@ function docCelLayerWarnings(doc) {
           const posed = /* @__PURE__ */ new Set();
           for (const c of l.cels) for (const p of c.poses) posed.add(p.id);
           for (const id of posed) if (id.startsWith("@")) push(`layer "${l.name}": \`pose "${id.slice(1)}"\` matches no item of this layer \u2014 the pose draws nothing (roster: ${l.items.map(itemLabel).join(", ") || "empty"}).`);
-          for (const it of l.items) if (isPoseable(it) && !posed.has(it.id)) push(`layer "${l.name}": "${itemLabel(it)}" is never posed by a cel \u2014 it is never drawn. Add \`pose "${itemLabel(it)}"\` to the cels where it should show.`);
+          for (const it of l.items) if (isPoseable2(it) && !posed.has(it.id)) push(`layer "${l.name}": "${itemLabel(it)}" is never posed by a cel \u2014 it is never drawn. Add \`pose "${itemLabel(it)}"\` to the cels where it should show.`);
         }
-        for (const it of l.items) if (isGroup(it)) visit(it.layers);
+        for (const it of l.items) if (isGroup2(it)) visit(it.layers);
       }
     };
     visit(layers);
@@ -349,8 +492,8 @@ function docPaintParamWarnings(doc) {
         const stops = it.paint && it.paint.type !== "solid" ? it.paint.stops : [];
         for (const s of stops) if (s.param) flag(s.param, "a gradient stop", who);
       }
-      if (isPoseable(it) && it.tint?.param) flag(it.tint.param, "a tint", who);
-      if (isGroup(it)) for (const l of it.layers) for (const c of l.items) visit(c);
+      if (isPoseable2(it) && it.tint?.param) flag(it.tint.param, "a tint", who);
+      if (isGroup2(it)) for (const l of it.layers) for (const c of l.items) visit(c);
     };
     for (const l of layers) for (const it of l.items) visit(it);
   };
@@ -360,44 +503,85 @@ function docPaintParamWarnings(doc) {
 }
 var warn = (message) => ({ scope: "scene", diag: { line: 1, col: 1, severity: "warning", message } });
 var itemLabel = (it) => "name" in it && it.name ? it.name : "kind" in it ? it.kind : "path";
+var glyphAdvance = (t) => (t.weight && t.weight >= 700 ? 0.56 : 0.52) * t.size;
 function estTextWidth(t) {
-  const advance = (t.weight && t.weight >= 700 ? 0.56 : 0.52) * t.size;
+  const advance = glyphAdvance(t);
   let longest = 0;
   for (const line of t.content.split("\n")) longest = Math.max(longest, line.length);
   return longest * advance;
 }
+function wrapMetrics(t) {
+  const advance = glyphAdvance(t);
+  const width = (s) => s.length * advance;
+  let lines = 0;
+  let widestWord = 0;
+  for (const paragraph of t.content.split("\n")) {
+    lines++;
+    let current = "";
+    for (const word of paragraph.split(/\s+/).filter(Boolean)) {
+      widestWord = Math.max(widestWord, width(word));
+      const joined = current ? `${current} ${word}` : word;
+      if (current && width(joined) > t.box.w) {
+        lines++;
+        current = word;
+      } else current = joined;
+    }
+  }
+  return { lines, widestWord };
+}
 function docLayoutWarnings(doc) {
   const out = [];
   const W = doc.width, H = doc.height;
   const TOL = 8;
   const r0 = (n) => Math.round(n);
-  const dynamicPos = (it) => "expressions" in it && it.expressions && (it.expressions.x != null || it.expressions.y != null || it.expressions.dx != null || it.expressions.dy != null);
-  for (const layer of doc.layers) {
-    for (const it of layer.items) {
-      if (!(isText(it) || isImage(it)) || dynamicPos(it) || isText(it) && it.textPath) continue;
-      const b = itemBBox(doc, it);
-      if (!b) continue;
-      const visible = b.maxX > 0 && b.minX < W && b.maxY > 0 && b.minY < H;
-      const clipped = b.minX < -TOL || b.minY < -TOL || b.maxX > W + TOL || b.maxY > H + TOL;
-      if (visible && clipped) {
-        out.push(warn(`"${itemLabel(it)}" clipped at the canvas edge: bbox [${r0(b.minX)},${r0(b.minY)} -> ${r0(b.maxX)},${r0(b.maxY)}] outside 0,0 -> ${W},${H}`));
-      }
+  const dynamicPos = (it) => "expressions" in it && it.expressions && (it.expressions.x != null || it.expressions.y != null || it.expressions.dx != null || it.expressions.dy != null) || !!doc.interactors?.some((i) => i.targetId === it.id);
+  const placed = [];
+  const collect = (layers, matrix, dynamic) => {
+    for (const l of layers) for (const it of l.items) {
+      if (isText(it) || isImage(it)) placed.push({ it, parent: matrix, dynamic: dynamic || dynamicPos(it) });
+      if (isGroup2(it)) collect(it.layers, compose(matrix, it.transform), dynamic || dynamicPos(it));
+    }
+  };
+  collect(doc.layers, IDENTITY, false);
+  for (const { it, parent, dynamic } of placed) {
+    if (dynamic || isText(it) && it.textPath) continue;
+    const local = itemBBox(doc, it);
+    if (!local) continue;
+    const b = transformBBox(local, parent);
+    const visible = b.maxX > 0 && b.minX < W && b.maxY > 0 && b.minY < H;
+    const clipped = b.minX < -TOL || b.minY < -TOL || b.maxX > W + TOL || b.maxY > H + TOL;
+    if (visible && clipped) {
+      out.push(warn(`"${itemLabel(it)}" clipped at the canvas edge: bbox [${r0(b.minX)},${r0(b.minY)} -> ${r0(b.maxX)},${r0(b.maxY)}] outside 0,0 -> ${W},${H}`));
     }
   }
-  for (const it of doc.layers.flatMap((l) => l.items)) {
-    if (!isText(it) || it.wrap || it.textPath || dynamicPos(it)) continue;
+  for (const { it, parent, dynamic } of placed) {
+    if (!isText(it) || it.wrap || it.textPath || dynamic) continue;
     const estW = estTextWidth(it);
     const left = it.align === "left" ? 0 : it.align === "right" ? it.box.w - estW : it.box.w / 2 - estW / 2;
-    const wl = it.transform.e + left, wr = wl + estW;
+    const m = compose(parent, it.transform);
+    const p0 = apply(m, { x: left, y: 0 }), p1 = apply(m, { x: left + estW, y: 0 });
+    const wl = Math.min(p0.x, p1.x), wr = Math.max(p0.x, p1.x);
     if (wr > W + TOL || wl < -TOL) {
       out.push(warn(`text "${it.content.slice(0, 24)}${it.content.length > 24 ? "\u2026" : ""}" overflows the canvas (estimated ~${r0(estW)} px, edge ${r0(wl)}->${r0(wr)} outside 0->${W}) \u2014 add "wrap"`));
     }
   }
+  for (const { it } of placed) {
+    if (!isText(it) || !it.wrap || it.textPath) continue;
+    const { lines, widestWord } = wrapMetrics(it);
+    const label = `${it.content.slice(0, 24).replace(/\n/g, " ")}${it.content.length > 24 ? "\u2026" : ""}`;
+    const tall = lines * it.size * it.lineHeight;
+    if (tall > it.box.h + TOL) {
+      out.push(warn(`text "${label}" overflows its box: ~${lines} wrapped line(s) \u2248 ${r0(tall)} px for a box ${r0(it.box.h)} px tall \u2014 raise the box height, shorten the text, or reduce the size`));
+    }
+    if (widestWord > it.box.w + TOL) {
+      out.push(warn(`text "${label}" has a word too wide for its box (~${r0(widestWord)} px > ${r0(it.box.w)} px) \u2014 a single word cannot be broken, so it spills past the frame whatever "wrap" says`));
+    }
+  }
   const pathTexts = [];
   const walkPathTexts = (layers) => {
     for (const l of layers) for (const it of l.items) {
       if (isText(it) && it.textPath) pathTexts.push(it);
-      else if (isGroup(it)) walkPathTexts(it.layers);
+      else if (isGroup2(it)) walkPathTexts(it.layers);
     }
   };
   walkPathTexts(doc.layers);
@@ -413,11 +597,11 @@ function docLayoutWarnings(doc) {
   const zones = [];
   const collectZones = (layers) => {
     for (const l of layers) for (const it of l.items) {
-      if (isGroup(it) && it.hitbox && it.name) {
+      if (isGroup2(it) && it.hitbox && it.name) {
         const b = dropZoneBounds(doc, it.name);
         if (b) zones.push({ name: it.name, b });
       }
-      if (isGroup(it)) collectZones(it.layers);
+      if (isGroup2(it)) collectZones(it.layers);
     }
   };
   collectZones(doc.layers);
@@ -445,13 +629,13 @@ function docModifierWarnings(doc) {
     const ctx = docLintContext(doc, editPath, allVars);
     const visit = (items) => {
       for (const it of items) {
-        if (isPoseable(it) && it.modifiers) for (const ch of EXPR_CHANNELS) {
+        if (isPoseable2(it) && it.modifiers) for (const ch of EXPR_CHANNELS2) {
           const m = it.modifiers[ch];
           if (!m) continue;
           for (const d of lint(`${ch} = ${m.target}`, ctx)) out.push({ scope: label, diag: { ...d, line: 1, col: 1, message: `${m.kind} ${ch}: ${d.message}` } });
           if (m.kind === "spring" && !(m.damping > 0 && m.damping < 1)) out.push({ scope: label, diag: { line: 1, col: 1, severity: "warning", message: `spring ${ch}: damping ${m.damping} should be in (0,1) \u2014 clamped at runtime` } });
         }
-        if (isGroup(it)) for (const l of it.layers) visit(l.items);
+        if (isGroup2(it)) for (const l of it.layers) visit(l.items);
       }
     };
     visit(contextLayers(doc, editPath).flatMap((l) => l.items));
@@ -468,14 +652,65 @@ function docHasErrors(doc, src) {
   return lintDoc(doc, src).some(({ diag }) => sev(diag) === "error");
 }
 
+// src/check.ts
+import { behaviorDiagnostics, objectTargetDiagnostics } from "@flatkit/engine/flatFormat";
+var line1 = (d) => `[${d.scope}] ${d.line}:${d.col}: ${d.severity}: ${d.message}`;
+var formatDiagnostics = (diagnostics) => diagnostics.map(line1).join("\n");
+function sourceDiagnostics(src) {
+  return [...behaviorDiagnostics(src), ...objectTargetDiagnostics(src)].map(({ scope, diag }) => ({ scope, line: diag.line, col: diag.col, severity: "error", message: diag.message }));
+}
+var SIZE_HEADER = /^[ \t]*size[ \t]+-?[\d.]+[ \t]+-?[\d.]+/m;
+function missingSizeDiagnostic(src, doc) {
+  if (SIZE_HEADER.test(src)) return null;
+  return {
+    scope: "scene",
+    line: 1,
+    col: 1,
+    severity: "warning",
+    message: `no \`size W H\` line \u2014 it is the REQUIRED first statement of a program, and this document silently defaults to ${doc.width}x${doc.height}. Anything laid out past that edge is clipped with nothing to say so. Declare the canvas you drew for.`
+  };
+}
+function programDiagnostics(doc, src) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (d) => {
+    const k = line1(d);
+    if (!seen.has(k)) {
+      seen.add(k);
+      out.push(d);
+    }
+  };
+  for (const d of sourceDiagnostics(src)) push(d);
+  const noSize = missingSizeDiagnostic(src, doc);
+  if (noSize) push(noSize);
+  for (const { scope, diag } of lintDoc(doc, src)) push({ scope, line: diag.line, col: diag.col, severity: diag.severity === "warning" ? "warning" : "error", message: diag.message });
+  return out;
+}
+var tally = (diagnostics, doc) => {
+  const errors = diagnostics.filter((d) => d.severity === "error").length;
+  return { ok: errors === 0, errors, warnings: diagnostics.length - errors, diagnostics, report: formatDiagnostics(diagnostics), doc };
+};
+function checkProgram(src, opts = {}) {
+  let doc;
+  try {
+    doc = compileFlatpack(src, opts.assetSrcs ?? [], opts.media ?? {});
+  } catch (e) {
+    return tally([{ scope: "scene", line: 1, col: 1, severity: "error", message: `compile error: ${e.message}` }], null);
+  }
+  return tally(programDiagnostics(doc, src), doc);
+}
+
 export {
-  localVariables,
-  lint,
-  lintReport,
   splitScopeProgram,
   scopeRegions,
   formatObjectBlock,
   joinScopeProgram,
+  localVariables,
+  lint,
+  lintReport,
+  forEachAction,
+  forEachActionExpression,
+  forEachItemExpression,
   scopeProgram,
   docLintContext,
   allScopeVariables,
@@ -486,6 +721,9 @@ export {
   lintDoc,
   docModifierWarnings,
   lintDocReport,
-  docHasErrors
+  docHasErrors,
+  formatDiagnostics,
+  programDiagnostics,
+  checkProgram
 };
-//# sourceMappingURL=chunk-HRWULWIL.js.map
+//# sourceMappingURL=chunk-MRRRN2CS.js.map