@ripple-ui/core 0.0.0-stage → 0.6.1-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qbtrix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+<!-- packages/core/README.md — @ripple-ui/core. Created 2026-08-25 (monorepo split). -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @ripple-ui/core
+
+Ripple's spec engine, with no renderer attached.
+
+An LLM produces a declarative JSON spec; this package turns it into a
+resolved tree of plain objects — expressions evaluated, conditions
+decided, loops expanded. What you draw that tree with is your business.
+
+```bash
+npm install @ripple-ui/core
+```
+
+```ts
+import { createHeadlessRuntime } from '@ripple-ui/core';
+
+const rt = createHeadlessRuntime({
+  spec: {
+    type: 'container',
+    children: [
+      { type: 'text', id: 'label', props: { text: 'Count: {state.count}' } },
+      {
+        type: 'button',
+        id: 'inc',
+        on_click: { action: 'set', target: 'count', value: '{state.count + 1}' }
+      }
+    ]
+  },
+  state: { count: 0 }
+});
+
+rt.findById('label').props.text;                 // 'Count: 0'
+await rt.dispatch(rt.findById('inc'), 'onclick');
+rt.findById('label').props.text;                 // 'Count: 1'
+```
+
+## What's in here
+
+- **Schema** — the `UISpec` / `UniversalSpec` zod schemas, event handlers,
+  motion, and brand tokens.
+- **Expressions** — `{state.foo}`, `{item.price}`, ternaries, comparisons,
+  arithmetic, and template strings.
+- **State** — `StateStore`, the interface every Ripple runtime implements,
+  and `HeadlessStateManager`, the dependency-free implementation.
+- **Events** — the dispatcher: 21 action verbs, multi-step flows, async
+  chaining, host delegation.
+- **Motion** — the animation compiler and presets (compilation only; playing
+  an animation needs a DOM, so that lives in a renderer).
+- **Headless runtime** — spec + state in, `ResolvedNode` tree out.
+
+No widgets. A resolved tree names widget *types*; how a `table` draws is a
+renderer's job.
+
+## Framework-agnostic, enforced
+
+Nothing reachable from this package imports Svelte, React, or any other
+framework, and nothing touches `document` at import time. That is checked
+rather than promised: `headless/purity.test.ts` crawls the transitive import
+graph and fails the build on any framework import or top-level DOM access.
+
+Practically: this runs in Node, a Worker, a test file, or under any UI
+framework.
+
+## Renderers
+
+| Package | Renders with |
+|---|---|
+| [`@ripple-ui/svelte`](../svelte) | Svelte 5 |
+
+Writing another one means implementing a function over `ResolvedNode` —
+every node carries its resolved props, its bound state path plus the
+prop/event pair to wire it to, and its raw handler specs.
+
+## Docs
+
+Full documentation: https://ripple.pocketpaw.xyz/docs. The headless runtime specifically:
+https://ripple.pocketpaw.xyz/docs/concepts/headless. API: https://ripple.pocketpaw.xyz/docs/api/core.
+
+## License
+
+MIT

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,93 @@
+# Third-party notices
+
+Ripple is MIT licensed (see `LICENSE`). It includes code from the projects
+below. Each section names the files that carry that code and reproduces the
+upstream licence in full, as the licence requires.
+
+Other credits kept next to what they cover:
+
+- `packages/svelte/NOTICE`: beautiful-ui and the other MIT design sources
+  behind the Svelte component skin.
+- `packages/svelte/static/models/CREDITS.md`: author, licence and source for
+  every 3D model in `static/models` (CC0, public domain, one CC BY 4.0).
+- `packages/svelte/static/fonts/OFL-*.txt`: the SIL Open Font License for each
+  bundled font.
+
+## Anatomy
+
+- Source: https://github.com/wheresryan22/anatomy (commit 689dcf9)
+- Project page: https://skills.wheresryan.sh/anatomy
+- Copyright (c) 2026 Ryan, MIT License (full text below)
+
+Files derived from it:
+
+- `packages/core/src/iso/kit.ts`: the camera, projection, extruded solids,
+  outlines and SVG helpers are ported from `kit/iso-kit.ts`; the `ISO_CSS`
+  selector structure is ported from `kit/iso.css` (the colour tokens are
+  Ripple's own).
+- `packages/core/src/iso/solids.ts`: frame, light, band, hull, prism and
+  sphere are ported from `kit/lathe.mjs` (cone and gear ring are new).
+- `packages/core/src/iso/scene.ts` and `packages/core/src/iso/enrich.ts` are
+  new code built on the two files above; `enrich.ts` follows Anatomy's craft
+  rules for detail.
+- `packages/svelte/src/lib/figures/*` and
+  `packages/svelte/src/lib/widgets/composite/IsoScene.svelte` draw with the
+  kit above.
+
+```
+MIT License
+
+Copyright (c) 2026 Ryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## ZzFX
+
+- Source: https://github.com/KilledByAPixel/ZzFX (v1.4.0)
+- Copyright (c) 2019 - Frank Force, MIT License (full text below)
+
+Files derived from it:
+
+- `packages/svelte/src/lib/sound/zzfx.ts`: the sample builder, vendored and
+  typed.
+
+```
+ZzFX MIT License
+
+Copyright (c) 2019 - Frank Force
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/dist/build/build-spec.d.ts

@@ -0,0 +1,148 @@
+import type { AuditItem, AuditReport } from '../core/audit-report.js';
+import { type DataGuardResult, type Fact } from '../core/data-guard.js';
+import type { ValidateCatalogOptions } from '../core/validate-catalog.js';
+import type { SlimWidgetEntry } from '../manifest/slim.js';
+import { type CraftRule, type Lens, type Waiver } from '../manifest/craft.js';
+export type Preset = 'card' | 'figure';
+export type StopReason = 'clean' | 'cap' | 'guard' | 'no-progress';
+/** What the loop asks the model for on each round. The host turns it into a prompt. */
+export interface ModelRequest {
+    preset: Preset;
+    /** The host's ask and rules, the same every round. */
+    prompt: string;
+    /** 1-based round number. */
+    round: number;
+    /** The best spec so far, for the model to fix; absent on round 1 or until a round parses. */
+    prior?: unknown;
+    /** The faults of the last round as one text block; `''` on round 1. */
+    feedback: string;
+    signal?: AbortSignal;
+}
+/** A model call. `tokens` is what the call cost; a host whose provider reports none counts before returning. */
+export type Model = (req: ModelRequest) => Promise<{
+    text: string;
+    tokens: number;
+}>;
+/** An offender's box on a render (CSS px from the shot's top left), for the critic to point at. */
+export interface Box {
+    /** The page check that found it, e.g. `overflow`. */
+    check: string;
+    /** JSON Pointer of the spec node it belongs to, when the host could map it. */
+    path?: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** One render of the spec at one width and theme. */
+export interface RenderResult {
+    width: number;
+    theme: string;
+    /** Where the host put the screenshot (a path or URL), or null when nothing was shot. */
+    png: string | null;
+    /** The render checks for this shot; every item counts as a fault. */
+    audit: AuditReport<AuditItem>[];
+    boxes: Box[];
+}
+export type Renderer = (spec: unknown) => Promise<RenderResult[]>;
+/** A finding from the host's critic (the eyes on the screenshots). */
+export interface CriticIssue extends AuditItem {
+    /** A `craft.lenses` id. */
+    lens: string;
+    /** The `craft.rules` id it breaks, when it names one. */
+    rule?: string;
+    /** The widget type at `path`, filled by the loop when it lands in `widgetFaults`. */
+    widget?: string;
+    severity: 1 | 2 | 3;
+    /** `spec`: the model can fix it. `widget`: the widget is at fault, reported, not scored. */
+    fixable: 'spec' | 'widget';
+}
+/** The craft data a critic judges by: rules with ids, and the lenses it looks through. */
+export interface CriticRules {
+    rules: readonly CraftRule[];
+    lenses: readonly Lens[];
+}
+export type Critic = (req: {
+    spec: unknown;
+    renders: RenderResult[];
+    rules: CriticRules;
+    prompt: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    issues: CriticIssue[];
+    tokens: number;
+}>;
+export interface BuildLimits {
+    /** Round cap. Default 4. */
+    rounds?: number;
+    /** Model plus critic tokens per build. Default 200,000. */
+    tokens?: number;
+}
+export interface BuildOptions extends ValidateCatalogOptions {
+    preset: Preset;
+    prompt: string;
+    model: Model;
+    renderer: Renderer;
+    critic?: Critic;
+    /** Slim widget entries for prop checks, the guard and the pre-gate. */
+    widgets?: readonly SlimWidgetEntry[];
+    /** The user's facts; the data guard's baseline when any is `given`, else the first parsed round. */
+    facts?: readonly Fact[];
+    /** Reviewed fault exceptions. Default: craft's `waivers`. */
+    waivers?: readonly Waiver[];
+    /** What the critic judges by. Default: core's `craft`. */
+    craft?: CriticRules;
+    /** The caller's clock: an ISO timestamp and an IANA zone. */
+    now: {
+        iso: string;
+        tz: string;
+    };
+    limits?: BuildLimits;
+    signal?: AbortSignal;
+    onRound?: (round: Round) => void;
+}
+export interface Round {
+    n: number;
+    /** The parsed spec, or null when the model's text was not JSON. */
+    spec: unknown;
+    /** Lossless fixes applied before the audit, in words. */
+    fixed: string[];
+    /** Pure audit, plus a `parse` report when the text did not parse. */
+    audit: AuditReport<AuditItem>[];
+    renders: RenderResult[];
+    critic: CriticIssue[];
+    /** Pure and render audit items left after waivers. */
+    faults: number;
+    /** What the `spec` critic issues cost (4, 8 or 12 each by severity). */
+    penalty: number;
+    score: number;
+    accepted: boolean;
+    /** True when round 1 took the pre-gate: one critic look, then stop. */
+    preGate?: boolean;
+    /** Items a waiver took out of the count. */
+    waived: AuditItem[];
+    /** The data guard's verdict; absent when the round did not parse. */
+    guard?: DataGuardResult;
+    /** Tokens this round's model and critic calls cost. */
+    tokens: number;
+    /** The feedback this round produced for the next one. */
+    feedback: string;
+}
+export interface BuildResult {
+    /** The best accepted spec, or null when no round parsed. */
+    spec: unknown;
+    rounds: Round[];
+    /** Faults no spec can fix: the best round's `widget` critic issues and any guard conflict. */
+    widgetFaults: CriticIssue[];
+    stopped: StopReason;
+    tokens: number;
+}
+/** The model's text as a spec: a fenced block's body, or the outermost `{...}`; trailing commas forgiven. */
+export declare function parseSpecText(text: string): {
+    spec: unknown;
+    fixed?: string;
+} | {
+    error: string;
+};
+export declare function buildSpec(opts: BuildOptions): Promise<BuildResult>;
+//# sourceMappingURL=build-spec.d.ts.map

package/dist/build/build-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-spec.d.ts","sourceRoot":"","sources":["../../src/build/build-spec.ts"],"names":[],"mappings":"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"}

package/dist/build/build-spec.js

@@ -0,0 +1,297 @@
+// @file build/build-spec.ts
+// @description The build loop: a model writes a spec in rounds, the pure audit,
+//   the data guard, the host's renderer and the host's critic check it, and
+//   every fault goes back to the model as one feedback block until a round is
+//   clean, stops improving, or a cap is hit. The model, renderer and critic are
+//   injected functions; this module holds no provider, no keys and no I/O.
+//   Invariants:
+//   - Pure. No clock, no files, no DOM. Time comes in as `now`; the wall-clock
+//     cap comes in as the caller's `signal`. An abort stops the loop with
+//     `stopped: 'cap'` and the best round so far.
+//   - Each round: model, parse (one trailing-comma retry), lossless fixes (an
+//     envelope alias moved to `ui`), pure audit, data guard, renderer, critic.
+//   - Score is 100 - 10 x faults - 2 x waived - critic penalty. Faults are the
+//     pure and render audit items left after waivers; each critic issue marked
+//     `fixable: 'spec'` costs 4, 8 or 12 by severity. `widget` issues cost
+//     nothing and go to `widgetFaults`. An item a live waiver covers (same
+//     check, on the waived widget, named by the item or found through its path) moves to its
+//     report's `waived` and to `Round.waived`: out of the count, still recorded.
+//   - A round is accepted only when guard-clean and strictly better than the
+//     best, so the returned spec is never worse than the first accepted round.
+//     A round that does not parse is recorded but never returned. Clean = no
+//     faults and no `spec` critic issue on a round the critic looked at.
+//   - The data guard runs after the pure audit on every parsed round, against
+//     the host's facts or the first parsed round. A round that fails it is
+//     never accepted and never rendered: the loop stops `guard`, keeps the
+//     best guard-clean round (null if there is none) and moves the conflict
+//     to `widgetFaults`. There is no second bend.
+//   - Token cap (`limits.tokens`, default 200k) is summed after every model
+//     and critic call. A model call that crosses it leaves its round unrendered
+//     and unaccepted; a critic call that crosses it ends the loop after that
+//     round is scored (`clean` if it is, else `cap`). The best accepted round
+//     is kept.
+//   - Pre-gate: a round-1 spec that is one data widget (in single-child
+//     wrappers) with clean audits gets one critic look and the loop stops:
+//     `clean` when the critic is quiet, else `no-progress`.
+import { dataGuard, dayAfter } from '../core/data-guard.js';
+import { specAudit } from '../core/spec-audit.js';
+import { formatSpecIssues } from '../core/spec-issues.js';
+import { craft as craftData, DATA_PROPS, waivers as craftWaivers } from '../manifest/craft.js';
+import { specEnvelope } from '../manifest/envelope.js';
+const DEFAULT_ROUNDS = 4;
+const DEFAULT_TOKENS = 200_000;
+/** Drop each comma that only a `}` or `]` follows, outside strings: the one JSON slip models make that loses nothing. */
+function dropTrailingCommas(text) {
+    let out = '';
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inString) {
+            if (c === '\\') {
+                out += c + (text[++i] ?? '');
+                continue;
+            }
+            if (c === '"')
+                inString = false;
+        }
+        else if (c === '"')
+            inString = true;
+        else if (c === ',' && /^\s*[}\]]/.test(text.slice(i + 1)))
+            continue;
+        out += c;
+    }
+    return out;
+}
+/** The model's text as a spec: a fenced block's body, or the outermost `{...}`; trailing commas forgiven. */
+export function parseSpecText(text) {
+    const fenced = /```(?:json)?\s*\n([\s\S]*?)```/.exec(text);
+    let body = fenced ? fenced[1] : text;
+    if (!fenced) {
+        const start = body.indexOf('{');
+        const end = body.lastIndexOf('}');
+        if (start >= 0 && end > start)
+            body = body.slice(start, end + 1);
+    }
+    try {
+        return { spec: JSON.parse(body) };
+    }
+    catch (e) {
+        try {
+            return { spec: JSON.parse(dropTrailingCommas(body)), fixed: 'dropped trailing commas' };
+        }
+        catch {
+            return { error: `the reply is not one JSON spec (${e.message})` };
+        }
+    }
+}
+/** Move a lone envelope alias (`root`, `tree`, ...) to `ui` when `ui` is missing. Mutates; returns what it did. */
+function fixEnvelope(spec) {
+    if (typeof spec !== 'object' || spec === null || Array.isArray(spec))
+        return [];
+    const s = spec;
+    const found = specEnvelope.aliasesNotAllowed.filter((a) => typeof s[a] === 'object' && s[a] !== null);
+    if ('ui' in s || found.length !== 1)
+        return [];
+    s.ui = s[found[0]];
+    delete s[found[0]];
+    return [`moved \`${found[0]}\` to \`ui\``];
+}
+class Aborted extends Error {
+}
+/** The widget type of the spec node an item's path points into (`/ui/children/0/props/x` → that child's type). */
+function widgetAt(spec, path) {
+    const node = /^\/ui((?:\/(?:children|else_children)\/\d+)*)/.exec(path);
+    if (!node || typeof spec !== 'object' || spec === null)
+        return undefined;
+    let at = spec.ui;
+    for (const seg of node[1].split('/').slice(1))
+        at = at?.[seg];
+    const type = at?.type;
+    return typeof type === 'string' ? type : undefined;
+}
+/** True when the spec's tree is one data widget, alone or inside single-child wrappers. */
+function oneDataWidget(spec, widgets) {
+    let node = spec?.ui;
+    while (node && Array.isArray(node.children) && node.children.length === 1)
+        node = node.children[0];
+    const type = node?.type;
+    if (typeof type !== 'string' || (Array.isArray(node?.children) && node.children.length > 0))
+        return false;
+    const entry = widgets?.find((w) => w.type === type);
+    return type in DATA_PROPS || Object.values(entry?.props ?? {}).some((p) => p?.data === true);
+}
+/**
+ * Move each item a live waiver covers out of its report's count into
+ * `waived`; returns the moved items. Matches by the item's `widget` (a
+ * render item names the widget it sits in), else the node its path points to.
+ */
+function waive(reports, spec, list, day) {
+    const live = list.filter((w) => !w.until || w.until >= day);
+    const moved = [];
+    for (const r of reports) {
+        const keep = [];
+        for (const item of r.items) {
+            const widget = live.some((w) => w.check === r.check) ? (item.widget ?? widgetAt(spec, item.path)) : undefined;
+            if (widget && live.some((w) => w.check === r.check && w.widget === widget))
+                moved.push(item);
+            else
+                keep.push(item);
+        }
+        if (keep.length === r.items.length)
+            continue;
+        r.waived = [...(r.waived ?? []), ...r.items.filter((i) => !keep.includes(i))];
+        r.items = keep;
+        r.count = keep.length;
+    }
+    return moved;
+}
+/** A critic issue as a feedback line: its lens and rule up front so the model can find the rule. */
+const criticLine = (i) => ({
+    code: i.rule ?? i.code,
+    path: i.path,
+    message: `[${i.lens}${i.rule ? `, rule:${i.rule}` : ''}] ${i.message}`
+});
+export async function buildSpec(opts) {
+    const { preset, prompt, model, renderer, critic, signal, onRound } = opts;
+    const list = opts.waivers ?? craftWaivers;
+    const rules = opts.craft ?? craftData;
+    const day = dayAfter(opts.now).today; // in the caller's zone, as the guard reads it
+    let first = undefined; // the first parsed spec, the guard's baseline without facts
+    const cap = opts.limits?.rounds ?? DEFAULT_ROUNDS;
+    const tokenCap = opts.limits?.tokens ?? DEFAULT_TOKENS;
+    const rounds = [];
+    let best = null;
+    let widgetFaults = [];
+    let tokens = 0;
+    let stopped = 'cap';
+    const check = () => {
+        if (signal?.aborted)
+            throw new Aborted();
+    };
+    /** Run a host call; an abort during it ends the loop (even if the call returns), any other error is the host's. */
+    const guarded = async (call) => {
+        check();
+        let r;
+        try {
+            r = await call();
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw new Aborted();
+            throw e;
+        }
+        check();
+        return r;
+    };
+    try {
+        for (let n = 1; n <= cap; n++) {
+            const last = rounds.at(-1);
+            const reply = await guarded(() => model({ preset, prompt, round: n, prior: best?.spec, feedback: last?.feedback ?? '', signal }));
+            tokens += reply.tokens;
+            const round = {
+                n,
+                spec: null,
+                fixed: [],
+                audit: [],
+                renders: [],
+                critic: [],
+                faults: 0,
+                penalty: 0,
+                score: 0,
+                accepted: false,
+                waived: [],
+                tokens: reply.tokens,
+                feedback: ''
+            };
+            const parsed = parseSpecText(reply.text);
+            if ('error' in parsed) {
+                round.audit = [{ check: 'parse', count: 1, items: [{ code: 'parse', path: '', message: parsed.error }] }];
+            }
+            else {
+                round.spec = parsed.spec;
+                round.fixed = [...(parsed.fixed ? [parsed.fixed] : []), ...fixEnvelope(parsed.spec)];
+                round.audit = specAudit(parsed.spec, opts);
+                round.waived = waive(round.audit, parsed.spec, list, day);
+                if (first === undefined)
+                    first = parsed.spec;
+                round.guard = dataGuard({ before: first, after: parsed.spec, facts: opts.facts, now: opts.now, widgets: opts.widgets });
+            }
+            if (round.guard && !round.guard.ok) {
+                const items = round.audit.flatMap((r) => r.items);
+                round.faults = items.length;
+                round.score = 100 - 10 * round.faults - 2 * round.waived.length;
+                round.feedback = formatSpecIssues([...round.guard.items, ...items]);
+                rounds.push(round);
+                widgetFaults = [
+                    ...widgetFaults,
+                    ...round.guard.items.map((i) => ({
+                        ...i,
+                        lens: 'data-truth',
+                        rule: i.code === 'inventedDate' ? 'no-future-dates' : 'data-fixed',
+                        severity: 3,
+                        fixable: 'widget'
+                    }))
+                ];
+                onRound?.(round);
+                stopped = 'guard';
+                break;
+            }
+            // Over the token cap after the model call: no render or critic spend, so the round is never accepted.
+            const looked = round.spec !== null && tokens < tokenCap;
+            if (looked) {
+                const spec = round.spec;
+                round.renders = await guarded(() => renderer(spec));
+                for (const r of round.renders)
+                    round.waived.push(...waive(r.audit, spec, list, day));
+                if (critic) {
+                    const seen = await guarded(() => critic({ spec, renders: round.renders, rules, prompt, signal }));
+                    tokens += seen.tokens;
+                    round.tokens += seen.tokens;
+                    round.critic = seen.issues.map((i) => (i.fixable === 'widget' ? { ...i, widget: i.widget ?? widgetAt(spec, i.path) } : i));
+                }
+            }
+            const items = [
+                ...round.audit.flatMap((r) => r.items),
+                ...round.renders.flatMap((r) => r.audit.flatMap((a) => a.items.map((i) => ({ ...i, message: `[${r.width}-${r.theme}] ${i.message}` }))))
+            ];
+            const specIssues = round.critic.filter((i) => i.fixable === 'spec');
+            round.faults = items.length;
+            round.penalty = specIssues.reduce((sum, i) => sum + 4 * i.severity, 0);
+            round.score = 100 - 10 * round.faults - 2 * round.waived.length - round.penalty;
+            round.feedback = formatSpecIssues([...items, ...specIssues.map(criticLine)]);
+            round.accepted = looked && (!best || round.score > best.score);
+            const isClean = looked && round.faults === 0 && specIssues.length === 0;
+            if (n === 1 && looked && round.faults === 0 && oneDataWidget(round.spec, opts.widgets))
+                round.preGate = true;
+            rounds.push(round);
+            if (round.accepted) {
+                best = round;
+                widgetFaults = round.critic.filter((i) => i.fixable === 'widget');
+            }
+            onRound?.(round);
+            if (round.accepted && isClean) {
+                stopped = 'clean';
+                break;
+            }
+            if (tokens >= tokenCap) {
+                stopped = 'cap';
+                break;
+            }
+            if (round.preGate) {
+                stopped = 'no-progress';
+                break;
+            }
+            if (best && round.spec !== null && !round.accepted) {
+                stopped = 'no-progress';
+                break;
+            }
+        }
+    }
+    catch (e) {
+        if (!(e instanceof Aborted))
+            throw e;
+        stopped = 'cap';
+    }
+    return { spec: best?.spec ?? null, rounds, widgetFaults, stopped, tokens };
+}
+//# sourceMappingURL=build-spec.js.map