@m0saic/templates 0.2.0

package/dist/m0saic/dsl-tutorial/v1/panels/inspector/v1/dsl-inspector.js

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/dsl-tutorial/inspector/v1 — live geometry inspector (internal)
+ * ============================================================================
+ *
+ * The IDE's right-hand inspector: the active node's Kind/Status chips over a
+ * grid of X/Y/W/H/Z fields whose values MUTATE as the parser walks — driven by
+ * per-field `%{eif:…}` exprs on the global clock (see pipeline/inspector.ts), so
+ * they move in lockstep with the canvas highlight + camera + step pill.
+ *
+ * Each field that changes on a step gets a git-diff "just changed" pulse: a soft
+ * positive-coloured pill behind the value, flashing once and decaying. Depth-safe
+ * by construction — one text layer per value (not one per step), a few
+ * enable-gated chip variants, one pulse layer per row.
+ *
+ * Width-fitted (gate 33): every font is picked from the row height AND capped by
+ * its cell under the CLI width model — the value cell by the LONGEST value the
+ * walk ever shows, the chips by the longest chip label ("Overlay"), the captions
+ * by their cells — so a narrow (portrait) panel shrinks its type instead of
+ * clipping "1080" to "80". Rows are capped to the panel WIDTH (a tall portrait
+ * panel keeps proportionate rows + bottom slack, not 140px rows), and the
+ * section rule is sized in px so a tiny panel never quantizes it to a 0-size
+ * frame (the 480×270 crash). Text sources are tagged for the parent's contract.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DslInspector = void 0;
+exports.inspectorTypeRamp = inspectorTypeRamp;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const node_kit_1 = require("../../../_shared/node-kit");
+const tokens_1 = require("../../../theme/tokens");
+const text_fit_1 = require("../../../_shared/text-fit");
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    preset: { type: "string", required: false, description: "Theme preset." },
+    fields: { type: "json", required: false, description: "Per-field value + change exprs." },
+    kindVariants: { type: "json", required: false, description: "Kind chip variants (enable-gated)." },
+    statusVariants: { type: "json", required: false, description: "Status chip variants (enable-gated)." },
+    axisVariants: { type: "json", required: false, description: "cols/rows chip variants for the N row (enable-gated)." },
+});
+/** The live value as ONE video text source whose enable-gated LAYERS are the
+ *  distinct values (the narration-collapse idiom): a literal per value, lit over
+ *  its windows. Only one is visible at a time, so stacking them at the same
+ *  placement is free. Replaces a per-frame `%{eif:…}` expr — that single
+ *  expression hit drawtext's ~80-boundary parser ceiling on dense grids. */
+function valueText(variants, fontSize, color, hAlign) {
+    const layers = (variants.length ? variants : [{ label: " ", enableExpr: "1" }]).map((v) => ({
+        content: { kind: "literal", text: v.label || " " },
+        style: { fontSize, fontColor: color },
+        placement: { fit: "contain", hAlign, vAlign: "middle" },
+        overlay: { enable: v.enableExpr },
+    }));
+    return {
+        type: "text",
+        // VIDEO: per-layer enable=… is evaluated per frame (a still would freeze at t=0).
+        renderMode: { kind: "video" },
+        visual: { backgroundColor: "black@0" },
+        layers,
+    };
+}
+/** A literal text cell that is only visible while `enableExpr` is nonzero. */
+function enableText(label, enableExpr, fontSize, color) {
+    return {
+        type: "text",
+        visual: { backgroundColor: "black@0" },
+        layers: [
+            {
+                content: { kind: "literal", text: label || " " },
+                style: { fontSize, fontColor: color },
+                placement: { fit: "contain", hAlign: "center", vAlign: "middle" },
+            },
+        ],
+        overlay: { enable: enableExpr },
+    };
+}
+/** Horizontal padding helper (safe — never subdivides a thin height). */
+function hpad(node, left, mid, right) {
+    return (0, node_kit_1.colSplit)([
+        { weight: left, node: node_kit_1.EMPTY },
+        { weight: mid, node },
+        { weight: right, node: node_kit_1.EMPTY },
+    ]);
+}
+/** A rounded chip holding stacked enable-gated label variants (only one lit). */
+function chip(variants, theme, font, ink) {
+    const bg = (0, node_kit_1.paint)((0, node_kit_1.colorTile)(theme.surfaceRaised, {
+        cornerRadius: 0.34,
+        cornerStyle: "rounded",
+        border: { color: theme.border, width: 0.006, alpha: theme.borderAlpha },
+    }));
+    const labels = (variants !== null && variants !== void 0 ? variants : []).map((v) => (0, node_kit_1.paint)((0, template_utils_1.tag)(enableText(v.label, v.enableExpr, font, ink), "chip")));
+    return (0, node_kit_1.overlay)([bg, hpad((0, node_kit_1.overlay)(labels.length ? labels : [node_kit_1.EMPTY]), 1, 8, 1)]);
+}
+/** Internal-state field names — shown below the divider (engine bookkeeping,
+ *  not properties of the single rect). */
+const INTERNAL_FIELDS = new Set(["N", "R", "C"]);
+/** Section divider column weights (basis 100): pad · caption · gap · rule · pad. */
+const SECTION_COLS = { pad: 4, caption: 38, gap: 2, rule: 52 };
+/** Inspector row column weights (basis 64): pad · label · gap · axis chip · gap · value · pad. */
+const ROW_COLS = { pad: 4, label: 12, gap1: 2, axis: 14, gap2: 4, value: 24 };
+/** Title row column weights (basis 72): pad · INSPECTOR · gap · kind chip · gap · status chip · pad. */
+const TITLE_COLS = { pad: 4, title: 26, gap1: 4, chip: 16, gap2: 2 };
+/** hpad(…, 1, 8, 1) / hpad(…, 1, 10, 1): the text gets the middle 8/10 (chips) or 10/12 (values). */
+const CHIP_INNER_FRAC = 0.8;
+const VALUE_INNER_FRAC = 10 / 12;
+/** Row height cap as a fraction of the panel WIDTH — a tall portrait panel keeps
+ *  proportionate rows (+ bottom slack) instead of stretching them to fill. */
+const ROW_H_MAX_OF_W = 0.3;
+/** Section rule: a 1-unit hairline in a band quantized at ≥ RULE_PX_PER_UNIT px
+ *  per unit — the engine's floor quantization can zero a unit under ~1px (the
+ *  480×270 / 704×396 "0-size frame" refusals), and the band's own px shifts ±1
+ *  between the child's slot and the flattened parent, so the granularity is
+ *  chosen from the band, never assumed. A band too short for 3 such units (pad
+ *  · rule · pad) gets the caption only. */
+const RULE_PX_PER_UNIT = 2.5;
+/** A labelled section divider: a small muted caption + a thin rule line sized in
+ *  px against its band (never a 0-size frame). */
+function sectionDivider(label, theme, font, bandH, captionW) {
+    const units = Math.floor(bandH / RULE_PX_PER_UNIT);
+    const above = Math.floor((units - 1) / 2);
+    const rule = units >= 3
+        ? (0, node_kit_1.rowSplit)([
+            { weight: above, node: node_kit_1.EMPTY },
+            { weight: 1, node: (0, node_kit_1.paint)((0, node_kit_1.colorTile)(theme.border)) },
+            { weight: units - 1 - above, node: node_kit_1.EMPTY },
+        ])
+        : node_kit_1.EMPTY;
+    return (0, node_kit_1.colSplit)([
+        { weight: SECTION_COLS.pad, node: node_kit_1.EMPTY },
+        { weight: SECTION_COLS.caption, node: (0, node_kit_1.paint)((0, template_utils_1.tag)((0, node_kit_1.textCell)(captionOrBlank(label, font, captionW), font, theme.muted, "left", "middle"), "section-title")) },
+        { weight: SECTION_COLS.gap, node: node_kit_1.EMPTY },
+        { weight: SECTION_COLS.rule, node: rule },
+        { weight: SECTION_COLS.pad, node: node_kit_1.EMPTY },
+    ]);
+}
+/** A caption that can't fit its cell even at the floor font paints BLANK (the
+ *  rule / chips still identify the row) rather than clipping mid-word. The
+ *  blank keeps the source (and its contract label) in place. */
+function captionOrBlank(label, font, availW) {
+    return (0, text_fit_1.textWidthPx)(label, font, text_fit_1.CAPS_EM) <= availW ? label : " ";
+}
+/** The longest label a set of chip variants ever shows (drives the shared chip font). */
+function longestLabel(variants) {
+    var _a;
+    let best = " ";
+    for (const v of variants !== null && variants !== void 0 ? variants : [])
+        if (((_a = v.label) !== null && _a !== void 0 ? _a : "").length > best.length)
+            best = v.label;
+    return best;
+}
+/**
+ * The inspector's type ramp, WIDTH-FITTED: each size starts from the row height
+ * (the design) and is capped by its cell + the longest string it must hold under
+ * the CLI width model. Exported for the gate-33 locks.
+ */
+function inspectorTypeRamp(W, rowH, fields, chips) {
+    const titleBasis = TITLE_COLS.pad * 2 + TITLE_COLS.title + TITLE_COLS.gap1 + TITLE_COLS.chip * 2 + TITLE_COLS.gap2;
+    const rowBasis = ROW_COLS.pad * 2 + ROW_COLS.label + ROW_COLS.gap1 + ROW_COLS.axis + ROW_COLS.gap2 + ROW_COLS.value;
+    const titleW = (0, text_fit_1.fitBudget)((TITLE_COLS.title / titleBasis) * W);
+    const chipW = (0, text_fit_1.fitBudget)((TITLE_COLS.chip / titleBasis) * W * CHIP_INNER_FRAC);
+    const axisChipW = (0, text_fit_1.fitBudget)((ROW_COLS.axis / rowBasis) * W * CHIP_INNER_FRAC);
+    const labelW = (0, text_fit_1.fitBudget)((ROW_COLS.label / rowBasis) * W);
+    const valueW = (0, text_fit_1.fitBudget)((ROW_COLS.value / rowBasis) * W * VALUE_INNER_FRAC);
+    const sectionW = (0, text_fit_1.fitBudget)((SECTION_COLS.caption / 100) * W);
+    const longestValue = fields.reduce((best, f) => {
+        const l = longestLabel(f.valueVariants);
+        return l.length > best.length ? l : best;
+    }, "0");
+    const longestField = fields.reduce((best, f) => (f.name.length > best.length ? f.name : best), "X");
+    return {
+        titleFont: (0, text_fit_1.fitFontPx)("INSPECTOR", titleW, Math.max(11, Math.round(rowH * 0.34)), 8, text_fit_1.CAPS_EM),
+        chipFont: (0, text_fit_1.fitFontPxAll)([
+            { text: longestLabel(chips), availW: Math.min(chipW, axisChipW), em: text_fit_1.PROSE_EM },
+        ], Math.max(10, Math.round(rowH * 0.3)), 7),
+        labelFont: (0, text_fit_1.fitFontPx)(longestField, labelW, Math.max(12, Math.round(rowH * 0.36)), 8, text_fit_1.CAPS_EM),
+        valueFont: (0, text_fit_1.fitFontPx)(longestValue, valueW, Math.max(14, Math.round(rowH * 0.46)), 8, text_fit_1.DIGIT_EM),
+        sectionFont: (0, text_fit_1.fitFontPx)("ENGINE STATE", sectionW, Math.max(9, Math.round(rowH * 0.26)), 7, text_fit_1.CAPS_EM),
+        titleW,
+        sectionW,
+    };
+}
+/** One inspector row: `LABEL` (muted) … optional axis tag … value (live expr)
+ *  with a change pulse. The axis tag (only the N row passes one) reads "cols" /
+ *  "rows" so the arity is qualified — a 2 that means columns vs rows. */
+function fieldRow(field, theme, labelFont, valueFont, axisChip) {
+    const label = (0, node_kit_1.paint)((0, template_utils_1.tag)((0, node_kit_1.textCell)(field.name, labelFont, theme.label, "left", "middle"), "field-label"));
+    // Pulse pill behind the value — positive (git "added") wash, flashing on change.
+    // ENABLE-ONLY at a baked-in tile alpha, NOT a time-varying `overlay.alpha`: an
+    // alpha expr (or enable folded into alpha) becomes a per-pixel `geq`, and 8
+    // fields of that overflowed the inspector filtergraph on dense grids. With the
+    // 0.35 alpha baked into the COLOR, `overlay.enable` alone gates the tile per
+    // frame — no geq. Square (no rounding) so it needs no corner-mask geq either.
+    const pulse = (0, node_kit_1.paint)({
+        ...(0, node_kit_1.colorTile)(`${theme.positive}@0.35`),
+        overlay: { enable: field.changeEnable },
+    });
+    const value = (0, node_kit_1.paint)((0, template_utils_1.tag)(valueText(field.valueVariants, valueFont, theme.title, "right"), "field-value"));
+    const valueCell = (0, node_kit_1.overlay)([pulse, hpad(value, 1, 10, 1)]);
+    return (0, node_kit_1.colSplit)([
+        { weight: ROW_COLS.pad, node: node_kit_1.EMPTY },
+        { weight: ROW_COLS.label, node: label },
+        { weight: ROW_COLS.gap1, node: node_kit_1.EMPTY },
+        { weight: ROW_COLS.axis, node: axisChip !== null && axisChip !== void 0 ? axisChip : node_kit_1.EMPTY }, // axis tag on N; blank elsewhere
+        { weight: ROW_COLS.gap2, node: node_kit_1.EMPTY },
+        { weight: ROW_COLS.value, node: valueCell },
+        { weight: ROW_COLS.pad, node: node_kit_1.EMPTY },
+    ]);
+}
+exports.DslInspector = {
+    id: (0, types_1.asTemplateId)("@m0saic/dsl-tutorial/inspector/v1"),
+    label: "DSL Tutorial — Inspector",
+    version: 1,
+    description: "Internal: live geometry inspector (X/Y/W/H/Z mutating with the walk + Kind/Status chips) for dsl-tutorial.",
+    capabilities: { tier: "core" },
+    tags: ["developer", "dsl-tutorial", "internal", "inspector"],
+    internal: true,
+    outputHints: { width: 480, height: 450, fps: 30, durationMs: 12000, note: "Live geometry inspector." }, // 480×450 not 460×430: 5-smooth axes (latticeSmooth)
+    propsSchema,
+    defaultProps: { preset: "dark" },
+    render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f;
+        const theme = (0, tokens_1.dslTutorialTheme)(props.preset);
+        const W = ctx.target.width;
+        const H = ctx.target.height;
+        const fields = (_a = props.fields) !== null && _a !== void 0 ? _a : [];
+        // Row height ≈ panel / (title + one row per field + divider + padding), CAPPED
+        // to the panel width so a tall portrait panel keeps proportionate rows (the
+        // slack becomes bottom padding). Fonts scale off it AND are width-fitted
+        // (inspectorTypeRamp), so adding/removing a field re-fits the grid and a
+        // narrow panel never clips a value.
+        const contentH = H * 0.96;
+        const rowH = Math.min(contentH / (Math.max(1, fields.length) + 4), W * ROW_H_MAX_OF_W);
+        const unit = rowH / 12; // px per row-weight unit (a 12-weight band = one row)
+        const chips = [...((_b = props.kindVariants) !== null && _b !== void 0 ? _b : []), ...((_c = props.statusVariants) !== null && _c !== void 0 ? _c : []), ...((_d = props.axisVariants) !== null && _d !== void 0 ? _d : [])];
+        const { titleFont, chipFont, labelFont, valueFont, sectionFont, titleW, sectionW } = inspectorTypeRamp(W, rowH, fields, chips);
+        // Output fields (X/Y/W/H/Z — the one rect) on top; internal engine state
+        // (N/R/C) below a labelled divider.
+        const outputFields = fields.filter((f) => !INTERNAL_FIELDS.has(f.name));
+        const internalFields = fields.filter((f) => INTERNAL_FIELDS.has(f.name));
+        // ── Title row: INSPECTOR · Kind chip · Status chip ──
+        const titleRow = (0, node_kit_1.colSplit)([
+            { weight: TITLE_COLS.pad, node: node_kit_1.EMPTY },
+            { weight: TITLE_COLS.title, node: (0, node_kit_1.paint)((0, template_utils_1.tag)((0, node_kit_1.textCell)(captionOrBlank("INSPECTOR", titleFont, titleW), titleFont, theme.muted, "left", "middle"), "inspector-title")) },
+            { weight: TITLE_COLS.gap1, node: node_kit_1.EMPTY },
+            { weight: TITLE_COLS.chip, node: chip((_e = props.kindVariants) !== null && _e !== void 0 ? _e : [], theme, chipFont, theme.accent) },
+            { weight: TITLE_COLS.gap2, node: node_kit_1.EMPTY },
+            { weight: TITLE_COLS.chip, node: chip((_f = props.statusVariants) !== null && _f !== void 0 ? _f : [], theme, chipFont, theme.label) },
+            { weight: TITLE_COLS.pad, node: node_kit_1.EMPTY },
+        ]);
+        // ── Field grid: OUTPUT (the rect) · divider · INTERNAL (engine state) ──
+        // Gap bands are skipped when a weight unit is under a pixel — a 1-unit gap
+        // would quantize to a 0-size frame and refuse the whole render.
+        const gaps = unit >= 1;
+        const rowBands = [{ weight: 13, node: titleRow }];
+        for (const f of outputFields) {
+            if (gaps)
+                rowBands.push({ weight: 2, node: node_kit_1.EMPTY }); // gap
+            rowBands.push({ weight: 12, node: fieldRow(f, theme, labelFont, valueFont) });
+        }
+        if (internalFields.length > 0) {
+            // "cols"/"rows" tag for the arity row, lit per step from the split in focus.
+            const axisChip = props.axisVariants && props.axisVariants.length > 0
+                ? chip(props.axisVariants, theme, chipFont, theme.muted)
+                : undefined;
+            if (gaps)
+                rowBands.push({ weight: 5, node: node_kit_1.EMPTY }); // section gap
+            rowBands.push({ weight: 7, node: sectionDivider("ENGINE STATE", theme, sectionFont, 7 * unit, sectionW) });
+            if (gaps)
+                rowBands.push({ weight: 1, node: node_kit_1.EMPTY });
+            for (const f of internalFields) {
+                if (gaps)
+                    rowBands.push({ weight: 2, node: node_kit_1.EMPTY }); // gap
+                rowBands.push({
+                    weight: 12,
+                    node: fieldRow(f, theme, labelFont, valueFont, f.name === "N" ? axisChip : undefined),
+                });
+            }
+        }
+        rowBands.push({ weight: 3, node: node_kit_1.EMPTY }); // bottom pad
+        // Slack below the capped rows (portrait) so the rows keep their height.
+        const usedUnits = rowBands.reduce((a, b) => a + b.weight, 0);
+        const slackUnits = contentH / unit - usedUnits;
+        if (slackUnits >= 1)
+            rowBands.push({ weight: slackUnits, node: node_kit_1.EMPTY });
+        const content = (0, node_kit_1.rowSplit)(rowBands);
+        // Content is FLUSH to the top of the panel rect (so the inspector's first row
+        // lines up with the canvas/viewframe top); only a small bottom pad remains.
+        const padded = (0, node_kit_1.rowSplit)([
+            { weight: 96, node: content },
+            { weight: 4, node: node_kit_1.EMPTY },
+        ]);
+        return Promise.resolve({
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0: (0, dsl_stdlib_1.toM0String)(padded.m0, "DslInspector"),
+            sources: padded.sources,
+            backgroundColor: theme.surface,
+        });
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.DslInspector);

package/dist/m0saic/dsl-tutorial/v1/pipeline/buildSteps.d.ts

@@ -0,0 +1,110 @@
+/**
+ * ============================================================================
+ * dsl-tutorial — Step[] pipeline (CHARACTER-LEVEL parse model)
+ * ============================================================================
+ *
+ * The m0 DSL is parsed one CHARACTER at a time, and EVERY significant character
+ * is a real step that transforms the geometry cursor (X/Y/W/H) or emits a frame:
+ *
+ *   digit  `2`      — read a split count (no geometry change yet)
+ *   open   `(` `[`  — split the cursor into N children; cursor → first child
+ *                     (so W halves on a `(` 2-split, H divides on a `[` 3-split)
+ *   comma  `,`      — advance to the next sibling; cursor X (col) or Y (row) moves
+ *   leaf   `1` `F`  — EMIT a frame at the cursor (paints; no geometry change)
+ *   close  `)` `]`  — pop the split; cursor RESTORES to the parent region
+ *   pass   `0` `>`  — a passthrough slot (donates space; no paint)
+ *   null   `-`      — a reserved-but-empty slot
+ *   overlay`{` `}`  — change the overlay LAYER depth (Z); cursor unchanged
+ *
+ * Step 0 (before the first character) is the unparsed canvas — the root's own
+ * full rect. The cursor RECTS are pulled from the real parse tree (exact, so
+ * weighted/passthrough layouts are honest), keyed by source span; the character
+ * walk only drives the ORDER + which op each character performs.
+ *
+ * `Z` is the OVERLAY nesting depth (inside `{}`), NOT a logical/stack index —
+ * for a flat layout it stays 0 the whole walk.
+ *
+ * Pure function of (m0, width, height): same inputs → byte-identical `Step[]`.
+ * ============================================================================
+ */
+import type { M0String, M0Rect, M0NodeKind } from "@m0saic/dsl";
+/** A before→after numeric diff. */
+export type FieldDiff = {
+    before: number | null;
+    after: number;
+};
+/** The inspector fields, in display order. `N` = arity of the split in focus
+ *  (the count just read / the split the cursor sits inside) — so a count-read
+ *  step registers a value instead of looking like a no-op. */
+export type InspectorField = "X" | "Y" | "W" | "H" | "Z" | "N" | "R" | "C";
+/** What a character does in the parse. */
+export type StepEventType = "count" | "enter" | "sibling" | "emitLeaf" | "exit" | "passthrough" | "null" | "overlay";
+export type Step = {
+    /** 1-based step number. */
+    index: number;
+    /** Total step count (same on every step). */
+    total: number;
+    eventType: StepEventType;
+    /** Character index into the DSL string this step corresponds to. */
+    charIndex: number;
+    kind: M0NodeKind;
+    stableKey: string;
+    /** Leaf index (0-based) for emitLeaf steps; undefined otherwise. */
+    leafIndex?: number;
+    /** Single-character source span [i, i+1) for the DSL-string caret. */
+    span: {
+        start: number;
+        end: number;
+    } | null;
+    /** The geometry CURSOR rect after this step (the active region). */
+    rect: M0Rect;
+    /** Inspector diffs (cursor + overlay depth) vs the previous step. */
+    fields: Record<InspectorField, FieldDiff>;
+    /** Real trace-derived accumulator, each as a before→after diff. */
+    accumulator: Record<string, FieldDiff>;
+    /** Human narration for the parse banner. */
+    narration: string;
+    /** Approximate symbol index into the DSL string (1-based significant token). */
+    tokenIndex: number;
+    /**
+     * For `enter` (open) steps: the split's axis + INTERNAL divider positions as
+     * fractions (0..1) of the REGION being split. Drives the canvas dotted
+     * subdivision drawn the instant a split opens.
+     */
+    split?: {
+        axis: "row" | "col";
+        dividers: number[];
+    };
+    /**
+     * For `enter` (open) steps: the rect of the region being subdivided (the
+     * parent), so the canvas can place the dotted dividers. (Distinct from `rect`,
+     * which is the cursor = the FIRST child after the split.)
+     */
+    splitRegion?: M0Rect;
+    /** Remainder px THIS child claimed from the enclosing split (drives the R
+     *  count-down + the "tile N takes a remainder px" callout). 0 / undefined when
+     *  the tile sits on the floor size. */
+    remainderClaim?: number;
+    /** Passthrough carry px THIS tile absorbed (a `0`/`>` donation landing). */
+    carryAbsorbed?: number;
+    /** Axis of the split N refers to (the count just read / the enclosing split) —
+     *  so the inspector can tag the arity field "cols" vs "rows". Undefined at the
+     *  root (no split in focus). */
+    axisInFocus?: "row" | "col";
+};
+/** Retained for API compatibility; the character model always walks every char. */
+export type StepEventMode = "enter+leaf" | "all";
+export type BuildStepsResult = {
+    m0: string;
+    steps: Step[];
+    /** Lexical token count (status bar "Tokens: N"). */
+    tokenCount: number;
+    /** Structural node count (status bar "Nodes: N"). */
+    nodeCount: number;
+};
+/** Count significant lexical tokens: each maximal digit-run is one token. */
+export declare function countTokens(m0: string): number;
+/** Build the ordered, character-level Step[] for an m0 layout at a canvas size. */
+export declare function buildSteps(m0: M0String | string, width: number, height: number, _opts?: {
+    stepEvents?: StepEventMode;
+}): BuildStepsResult;