@m0saic/templates 0.2.0

package/dist/gen-precision-sweep.js

@@ -0,0 +1,219 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var _a, _b, _c, _d, _e, _f, _g;
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Generate PRECISION-SWEEP.md — the DENSE precision probe.
+ *
+ * `gen-template-audit` samples ~12 "standard" canvases per template and reports
+ * a ratio/absolute verdict from the precision slope. That's cheap but BLIND to
+ * the specific canvases where a template's baked edges are coprime with the
+ * canvas and its m0 pins to 100% precision (`maxSplit === axisLen`). A template
+ * can read "ratio" on the sampled canvases yet still blow up on the ones in
+ * between.
+ *
+ * This heavier probe sweeps EVERY integer dimension over a range, per axis
+ * (holding the other axis at a fixed reference — placeRects X-edges depend on W,
+ * Y on H), and reports for each template the FRACTION and EXAMPLES of canvases
+ * that hit 100% precision. Use it to see how "spotty" an absolute leaf is, and
+ * to verify a drift-snap migration actually flattened the pin surface (not just
+ * dodged the sampled canvases).
+ *
+ * SLOW by design (minutes for the full shelf). Scope it while iterating:
+ *   SWEEP_IDS=@m0saic/alpine/stat-card/v1,@m0saic/alpine/kpi-card/v1 \
+ *     SWEEP_MIN=240 SWEEP_MAX=1280 SWEEP_STEP=1 SWEEP_FIXED=720 \
+ *     node dist/gen-precision-sweep.js
+ *
+ * Deterministic: renders `defaultProps` (no wall-clock/random).
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const dsl_1 = require("@m0saic/dsl");
+const platform_1 = require("@m0saic/platform");
+const template_utils_1 = require("@m0saic/template-utils");
+require("./m0saic"); // side-effect: register every template
+const ROOT = path.resolve(__dirname, "..");
+const OUT = path.join(ROOT, "PRECISION-SWEEP.md");
+const MIN = Number((_a = process.env.SWEEP_MIN) !== null && _a !== void 0 ? _a : 240);
+const MAX = Number((_b = process.env.SWEEP_MAX) !== null && _b !== void 0 ? _b : 1280);
+const STEP = Math.max(1, Number((_c = process.env.SWEEP_STEP) !== null && _c !== void 0 ? _c : 1));
+const FIXED = Number((_d = process.env.SWEEP_FIXED) !== null && _d !== void 0 ? _d : 720);
+/** precision ÷ axis ≥ this ⇒ a 100% pin. */
+const PIN = 0.999;
+/** Only these ids (comma-separated) when set — otherwise all core templates. */
+const ONLY = ((_e = process.env.SWEEP_IDS) !== null && _e !== void 0 ? _e : "").split(",").map((s) => s.trim()).filter(Boolean);
+/** Same heavy/side-effecting skips as the audit. */
+const SKIP_SUBSTRINGS = ["benchmark/", "media/video_to_png", "media/screencap", "brand/logo", "/scatter-bake/"];
+const HEAVY_FRAMES = 4000;
+/** Skip a template whose representative render is slower than this (ms) — the
+ *  sweep does ~2×(MAX−MIN)/STEP renders, so a slow-per-canvas template would
+ *  take minutes. Raise it (`SWEEP_SLOW_MS`) to include heavier templates. */
+const SLOW_MS = Number((_f = process.env.SWEEP_SLOW_MS) !== null && _f !== void 0 ? _f : 120);
+/** Hard wall per axis (ms). If a template turns slow only at some canvases, cut
+ *  the sweep short and report a partial (truncated) result rather than hang. */
+const AXIS_BUDGET_MS = Number((_g = process.env.SWEEP_AXIS_BUDGET_MS) !== null && _g !== void 0 ? _g : 20000);
+function ctxFor(w, h) {
+    const t = { width: w, height: h, fps: 30, durationMs: 2000 };
+    return { mode: "render", target: t, output: { ...t, workspaceDir: "/tmp/tpl-sweep" }, media: {} };
+}
+/** Render defaultProps at (w,h) → the m0 that describes the layout (flattened if nested). */
+async function m0For(tpl, w, h) {
+    var _a;
+    const doc = await tpl.render({ ...((_a = tpl.defaultProps) !== null && _a !== void 0 ? _a : {}) }, ctxFor(w, h));
+    if (!doc || doc.kind !== "mosaic_document")
+        return null;
+    const mdoc = doc;
+    const nested = !!(mdoc.children && Object.keys(mdoc.children).length > 0);
+    if (!nested)
+        return String(mdoc.m0);
+    const flat = (0, platform_1.flattenMosaicDocument)({ file: mdoc, width: w, height: h, resolveRef: () => null });
+    return flat.ok ? String(flat.file.m0) : null;
+}
+async function sweepAxis(tpl, axis) {
+    const pins = [];
+    let n = 0;
+    let maxPct = 0;
+    let truncated = false;
+    const deadline = Date.now() + AXIS_BUDGET_MS;
+    for (let v = MIN; v <= MAX; v += STEP) {
+        if (Date.now() > deadline) {
+            truncated = true;
+            break;
+        }
+        const w = axis === "W" ? v : FIXED;
+        const h = axis === "H" ? v : FIXED;
+        let m0;
+        try {
+            m0 = await m0For(tpl, w, h);
+        }
+        catch {
+            continue;
+        }
+        if (!m0)
+            continue;
+        const p = (0, dsl_1.getComplexityMetricsFast)(m0).precision;
+        const pct = axis === "W" ? p.maxSplitX / w : p.maxSplitY / h;
+        n++;
+        maxPct = Math.max(maxPct, pct);
+        if (pct >= PIN)
+            pins.push(v);
+    }
+    return { n, pins, maxPct, truncated };
+}
+function verdict(wPct, hPct) {
+    const worst = Math.max(wPct, hPct);
+    if (worst < 0.02)
+        return "clean"; //   <2% of canvases pin — safe to nest anywhere
+    if (worst < 0.4)
+        return "spotty"; //   pins on some canvases — a drift/ratio fix helps
+    return "pinned"; //                    pins on ~half+ — a raw absolute leaf
+}
+async function main() {
+    var _a, _b, _c;
+    let ids = ONLY.length > 0 ? ONLY : (0, template_utils_1.listRegisteredTemplateIds)();
+    ids = ids.filter((id) => !SKIP_SUBSTRINGS.some((s) => id.includes(s)));
+    ids.sort();
+    const rows = [];
+    const skipped = [];
+    for (const id of ids) {
+        const tpl = (0, template_utils_1.getTemplate)(id);
+        if (!tpl)
+            continue;
+        // Core-tier only (capability-tier may hit APIs / side effects), unless explicitly asked.
+        if (ONLY.length === 0 && ((_a = tpl.capabilities) === null || _a === void 0 ? void 0 : _a.tier) !== "core")
+            continue;
+        // Heavy + SLOW guard: time a representative render; skip bitmaps and
+        // anything too slow to render thousands of times.
+        let probeMs = 0;
+        try {
+            const t0 = Date.now();
+            const first = await m0For(tpl, FIXED, FIXED);
+            probeMs = Date.now() - t0;
+            if (!first)
+                continue;
+            if ((0, dsl_1.getComplexityMetricsFast)(first).frameCount > HEAVY_FRAMES) {
+                skipped.push(`${id} (heavy)`);
+                console.log(`[precision-sweep] ${id}: skip (heavy)`);
+                continue;
+            }
+            if (probeMs > SLOW_MS) {
+                skipped.push(`${id} (slow ~${probeMs}ms)`);
+                console.log(`[precision-sweep] ${id}: skip (slow ~${probeMs}ms/render; raise SWEEP_SLOW_MS to include)`);
+                continue;
+            }
+        }
+        catch {
+            continue;
+        }
+        const role = tpl.primitive ? "primitive" : ((_c = (_b = tpl.capabilities) === null || _b === void 0 ? void 0 : _b.tier) !== null && _c !== void 0 ? _c : "");
+        const swept0 = Date.now();
+        const w = await sweepAxis(tpl, "W");
+        const h = await sweepAxis(tpl, "H");
+        if (w.n === 0 && h.n === 0)
+            continue;
+        const wPct = w.n ? w.pins.length / w.n : 0;
+        const hPct = h.n ? h.pins.length / h.n : 0;
+        const r = { id, role, wPins: w.pins.length, wN: w.n, hPins: h.pins.length, hN: h.n, verdict: verdict(wPct, hPct), wEx: w.pins.slice(0, 10), hEx: h.pins.slice(0, 10) };
+        rows.push(r);
+        const trunc = w.truncated || h.truncated ? " ⚠ TRUNCATED (slow at some canvases)" : "";
+        // eslint-disable-next-line no-console
+        console.log(`[precision-sweep] ${id}: W ${r.wPins}/${r.wN} · H ${r.hPins}/${r.hN} · ${r.verdict} · ${((Date.now() - swept0) / 1000).toFixed(1)}s (${probeMs}ms/render)${trunc}`);
+    }
+    rows.sort((a, b) => b.wPins / Math.max(1, b.wN) + b.hPins / Math.max(1, b.hN) - (a.wPins / Math.max(1, a.wN) + a.hPins / Math.max(1, a.hN)));
+    const pct = (a, b) => (b ? `${((a / b) * 100).toFixed(0)}%` : "—");
+    const lines = [];
+    lines.push("# Template precision sweep\n");
+    lines.push(`> Auto-generated by \`gen-precision-sweep\` (do NOT edit by hand). Sweeps every integer dimension in **${MIN}–${MAX} step ${STEP}** per axis (other axis fixed at **${FIXED}**), and reports the fraction of canvases where the flattened m0 hits **100% precision** (\`maxSplit === axisLen\` — the coprime-edge pin). Unlike \`TEMPLATE-AUDIT.md\` (which samples ~12 canvases), this sees the pins BETWEEN the sampled sizes. Verdict: **clean** <2% · **spotty** <40% · **pinned** ≥40%. Sorted worst-first.\n`);
+    lines.push(`_${rows.length} templates swept._\n`);
+    lines.push("| template | role | verdict | W 100%-pins | H 100%-pins | example pin widths |");
+    lines.push("|---|---|---|---|---|---|");
+    for (const r of rows) {
+        lines.push(`| \`${r.id}\` | ${r.role} | **${r.verdict}** | ${r.wPins}/${r.wN} (${pct(r.wPins, r.wN)}) | ${r.hPins}/${r.hN} (${pct(r.hPins, r.hN)}) | ${r.wEx.length ? r.wEx.join(", ") : "—"} |`);
+    }
+    lines.push("");
+    lines.push("_A **clean** template composes at any canvas; **spotty** / **pinned** ones pin their parent to 100% precision on the listed dims — migrate them onto `placeOptimizedPieces` (lock only animation-critical geometry). Note even a drift-snapped leaf stays **spotty** at small canvases where the % budget is only a pixel or two._");
+    if (skipped.length) {
+        lines.push("");
+        lines.push(`**Skipped (${skipped.length})** — too heavy / slow to sweep thousands of times (raise \`SWEEP_SLOW_MS\` to include): ${skipped.map((s) => `\`${s}\``).join(", ")}.`);
+    }
+    fs.writeFileSync(OUT, lines.join("\n") + "\n", "utf8");
+    // eslint-disable-next-line no-console
+    console.log(`[precision-sweep] wrote PRECISION-SWEEP.md — ${rows.length} templates`);
+}
+main().catch((e) => {
+    // eslint-disable-next-line no-console
+    console.error(e);
+    process.exit(1);
+});

package/dist/gen-props-shape.d.ts

@@ -0,0 +1 @@
+import "./m0saic";

package/dist/gen-props-shape.js

@@ -0,0 +1,269 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Generate PROPS-SHAPE.md — the prop-surface audit for the template shelf.
+ *
+ * Usage:  node dist/gen-props-shape.js   (or: npm run audit:props)
+ *
+ * Companion to TEMPLATE-AUDIT.md. That one PROBES GEOMETRY (renders defaultProps
+ * across canvases to classify ratio/absolute positioning). This one is a purely
+ * STATIC read of every registered template's `propsSchema` — no rendering — to
+ * surface the PROP SURFACE for two things:
+ *
+ *   1. Per-template UX shape — required vs optional split, how many loose flat
+ *      props vs collapsible groups, groups missing `fields` (which render as a
+ *      raw JSON bag in the Make panel), agent-only props.
+ *   2. Cross-template CONSISTENCY — do the same concepts use the same prop names
+ *      and shapes across templates? (e.g. `title` vs `titles`, `barColor` vs
+ *      `lineColor` vs `color`, who exposes `theme` / `renderMode` / a background
+ *      knob.) A concept under different names/shapes is a rename/normalize target.
+ *
+ * Deterministic: reads static schema objects (no wall-clock/random), reproducible.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const template_utils_1 = require("@m0saic/template-utils");
+require("./m0saic"); // side-effect: register every template
+const ROOT = path.resolve(__dirname, "..");
+const OUT = path.join(ROOT, "PROPS-SHAPE.md");
+/** Concepts we WANT to be consistent across the shelf, with the name variants
+ *  seen in the wild. Presence is checked by any of the aliases. */
+const STANDARD_KNOBS = [
+    { key: "theme", label: "theme", aliases: ["theme"] },
+    { key: "anim", label: "anim", aliases: ["anim", "animate", "animation", "reduceMotion"] },
+    { key: "renderMode", label: "renderMode", aliases: ["renderMode"] },
+    { key: "title", label: "title", aliases: ["title", "titles"] },
+    { key: "bg", label: "background", aliases: ["backgroundColor", "background", "bg"] },
+    { key: "preset", label: "preset", aliases: ["preset"] },
+    { key: "seed", label: "seed", aliases: ["seed"] },
+];
+function shapeOf(id) {
+    var _a, _b, _c, _d, _e;
+    let tpl;
+    try {
+        tpl = (0, template_utils_1.getTemplate)(id);
+    }
+    catch {
+        return null;
+    }
+    if (!tpl)
+        return null;
+    const schema = (_a = tpl.propsSchema) !== null && _a !== void 0 ? _a : {};
+    const props = Object.entries(schema).map(([name, def]) => {
+        var _a, _b, _c;
+        const ui = (_b = (_a = def === null || def === void 0 ? void 0 : def.meta) === null || _a === void 0 ? void 0 : _a.ui) !== null && _b !== void 0 ? _b : {};
+        const isGroup = (def === null || def === void 0 ? void 0 : def.type) === "group";
+        const fieldNames = (def === null || def === void 0 ? void 0 : def.fields) ? Object.keys(def.fields) : [];
+        return {
+            name,
+            type: String((_c = def === null || def === void 0 ? void 0 : def.type) !== null && _c !== void 0 ? _c : "?"),
+            required: !!(def === null || def === void 0 ? void 0 : def.required),
+            primary: !!ui.primary,
+            agent: ui.consumer === "agent",
+            hidden: !!ui.hidden,
+            isGroup,
+            hasFields: fieldNames.length > 0,
+            fieldNames,
+        };
+    });
+    return {
+        id,
+        role: String((_b = tpl.role) !== null && _b !== void 0 ? _b : (tpl.primitive ? "primitive" : "—")),
+        tier: String((_d = (_c = tpl.capabilities) === null || _c === void 0 ? void 0 : _c.tier) !== null && _d !== void 0 ? _d : "—"),
+        version: String((_e = tpl.version) !== null && _e !== void 0 ? _e : "—"),
+        props,
+    };
+}
+// ── Collect ────────────────────────────────────────────────────────────────
+const ids = (0, template_utils_1.listRegisteredTemplateIds)().sort();
+const shapes = [];
+for (const id of ids) {
+    const s = shapeOf(id);
+    if (s)
+        shapes.push(s);
+}
+// ── Aggregates ───────────────────────────────────────────────────────────────
+const isReqBlock = (p) => p.required || p.primary; // what the Make panel shows up top
+const isFlatOptional = (p) => !isReqBlock(p) && !p.isGroup && !p.agent && !p.hidden;
+// Prop-name frequency across the shelf.
+const nameFreq = new Map();
+for (const s of shapes) {
+    for (const p of s.props) {
+        if (p.hidden)
+            continue;
+        const e = (_a = nameFreq.get(p.name)) !== null && _a !== void 0 ? _a : { count: 0, types: new Set(), templates: [] };
+        e.count += 1;
+        e.types.add(p.type);
+        e.templates.push(shortId(s.id));
+        nameFreq.set(p.name, e);
+    }
+}
+function shortId(id) {
+    return id.replace(/^@m0saic\//, "");
+}
+// ── Render report ────────────────────────────────────────────────────────────
+const lines = [];
+const push = (s = "") => lines.push(s);
+push("# Template Props-Shape Audit");
+push();
+push("> Generated by `gen-props-shape.ts` (static read of every registered `propsSchema` — no rendering).");
+push("> Companion to `TEMPLATE-AUDIT.md`: that one probes GEOMETRY (ratio/absolute); this inspects the PROP SURFACE for UX + cross-template consistency.");
+push(`> ${shapes.length} templates.`);
+push();
+// 1. Standard-knob coverage
+push("## 1. Standard-knob coverage");
+push();
+push("Which templates expose the common knobs (by any known alias). A gap on a chart/primitive, or the same concept under different names, is a consistency target.");
+push();
+push(`| template | role | req | opt-flat | groups | agent | ${STANDARD_KNOBS.map((k) => k.label).join(" | ")} |`);
+push(`|---|---|--:|--:|--:|--:|${STANDARD_KNOBS.map(() => ":--:").join("|")}|`);
+for (const s of shapes) {
+    const names = new Set(s.props.map((p) => p.name));
+    const req = s.props.filter(isReqBlock).length;
+    const flat = s.props.filter(isFlatOptional).length;
+    const groups = s.props.filter((p) => p.isGroup).length;
+    const agent = s.props.filter((p) => p.agent).length;
+    const cells = STANDARD_KNOBS.map((k) => {
+        const hit = k.aliases.find((a) => names.has(a));
+        return hit ? (hit === k.label ? "✓" : hit) : "—";
+    });
+    push(`| \`${shortId(s.id)}\` | ${s.role} | ${req} | ${flat} | ${groups} | ${agent} | ${cells.join(" | ")} |`);
+}
+push();
+// 2. Prop-name frequency
+push("## 2. Prop-name frequency (top-level)");
+push();
+push("Every top-level prop name across the shelf. **Same concept under different names or types = a rename/normalize target.** Watch for near-duplicates (e.g. `title` vs `titles`, `barColor`/`lineColor`/`color`).");
+push();
+push("| prop | # | type(s) | templates |");
+push("|---|--:|---|---|");
+const freqRows = [...nameFreq.entries()].sort((a, b) => b[1].count - a[1].count || a[0].localeCompare(b[0]));
+for (const [name, e] of freqRows) {
+    const tmpls = e.templates.length <= 6 ? e.templates.join(", ") : `${e.templates.slice(0, 6).join(", ")} +${e.templates.length - 6}`;
+    push(`| \`${name}\` | ${e.count} | ${[...e.types].join(", ")} | ${tmpls} |`);
+}
+push();
+// 3. JSON-bag risk: group props without fields
+push("## 3. JSON-bag risk — `type:\"group\"` without `fields`");
+push();
+push("A group with no `fields:` schema renders as a raw `{ }` JSON textarea in the Make panel (no labeled sub-fields). Add `fields`.");
+push();
+const bagRows = [];
+for (const s of shapes) {
+    for (const p of s.props) {
+        if (p.isGroup && !p.hasFields)
+            bagRows.push(`| \`${shortId(s.id)}\` | \`${p.name}\` |`);
+    }
+}
+if (bagRows.length) {
+    push("| template | prop |");
+    push("|---|---|");
+    bagRows.forEach(push);
+}
+else {
+    push("_None — every group declares `fields`._");
+}
+push();
+// 4. Flat-heavy templates (grouping candidates)
+push("## 4. Flat-heavy templates (grouping candidates)");
+push();
+push("Templates with many loose flat optional props (no group) — a long, un-collapsible Optional list (what `charts/bar-graph/v2` looked like before its reorg). Candidates for a prop-UX grouping pass.");
+push();
+const flatHeavy = shapes
+    .map((s) => ({ id: s.id, flat: s.props.filter(isFlatOptional) }))
+    .filter((x) => x.flat.length >= 4)
+    .sort((a, b) => b.flat.length - a.flat.length);
+if (flatHeavy.length) {
+    push("| template | flat-optional | props |");
+    push("|---|--:|---|");
+    for (const x of flatHeavy)
+        push(`| \`${shortId(x.id)}\` | ${x.flat.length} | ${x.flat.map((p) => p.name).join(", ")} |`);
+}
+else {
+    push("_None — no template has ≥4 loose flat optional props._");
+}
+push();
+// 4b. Intermixed flat/group ordering — a flat optional appearing AFTER a group
+// in declaration order (= display order on the Make page). Reads messy; flat
+// props should come first, groups last.
+push("## 4b. Intermixed flat / group ordering");
+push();
+push("Templates where a loose flat optional is declared **after** a group prop, so the Make panel sandwiches flat fields between collapsible groups. Fix = reorder (flat first, groups last) — non-breaking. (`charts/stat-card/v1` and `charts/bar-graph/v2` are already clean.)");
+push();
+const intermixRows = [];
+for (const s of shapes) {
+    const optionals = s.props.filter((p) => !isReqBlock(p) && !p.hidden && !p.agent);
+    let seenGroup = false;
+    let firstFlatAfterGroup = null;
+    for (const p of optionals) {
+        if (p.isGroup)
+            seenGroup = true;
+        else if (seenGroup && firstFlatAfterGroup == null)
+            firstFlatAfterGroup = p.name;
+    }
+    if (firstFlatAfterGroup) {
+        const order = optionals.map((p) => (p.isGroup ? `▸${p.name}` : p.name)).join(", ");
+        intermixRows.push(`| \`${shortId(s.id)}\` | \`${firstFlatAfterGroup}\` | ${order} |`);
+    }
+}
+if (intermixRows.length) {
+    push("| template | first flat-after-group | optional order (▸ = group) |");
+    push("|---|---|---|");
+    intermixRows.forEach(push);
+}
+else {
+    push("_None — every template keeps flat optionals before its groups._");
+}
+push();
+// 5. Per-template shape
+push("## 5. Per-template shape");
+push();
+for (const s of shapes) {
+    const req = s.props.filter(isReqBlock);
+    const groups = s.props.filter((p) => p.isGroup);
+    const flat = s.props.filter(isFlatOptional);
+    const agent = s.props.filter((p) => p.agent);
+    push(`### \`${shortId(s.id)}\`  — ${s.role} · ${s.tier} · v${s.version}`);
+    push(`- **required/primary:** ${req.length ? req.map((p) => `${p.name}${p.required ? "*" : ""} (${p.type})`).join(", ") : "—"}`);
+    push(`- **groups:** ${groups.length ? groups.map((p) => `${p.name}${p.hasFields ? `{${p.fieldNames.join(", ")}}` : " ⚠️no-fields"}`).join(" · ") : "—"}`);
+    push(`- **flat optional:** ${flat.length ? flat.map((p) => `${p.name} (${p.type})`).join(", ") : "—"}`);
+    if (agent.length)
+        push(`- **agent:** ${agent.map((p) => p.name).join(", ")}`);
+    push();
+}
+fs.writeFileSync(OUT, lines.join("\n"));
+console.log(`[gen-props-shape] wrote ${path.relative(ROOT, OUT)} (${shapes.length} templates, ${nameFreq.size} distinct prop names)`);

package/dist/gen-template-audit.d.ts

@@ -0,0 +1 @@
+import "./m0saic";