ugly-game 0.5.0 → 0.5.1

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './dmath';
 export * from './mat4';
 export * from './noise';
 export * from './moat';
+export * from './stateIR';
 export * from './gpuShadow';
 export * from './input/resolve';
 export * from './input/browserBackend';

package/dist/index.js

@@ -4,6 +4,7 @@ export * from './dmath';
 export * from './mat4';
 export * from './noise';
 export * from './moat';
+export * from './stateIR';
 export * from './gpuShadow';
 export * from './input/resolve';
 export * from './input/browserBackend';

package/dist/stateIR.d.ts

@@ -0,0 +1,30 @@
+/** A sim/scene that can explain itself to an agent from structured state (not pixels). */
+export interface AgentDebuggable<Snap> {
+    /** Typed, JSON-able structured snapshot of the current state (a pure read). */
+    snapshot(): Snap;
+    /** One-screen play-by-play of the current state, highlighting the actionable "why" (built with Narrator). */
+    describe(): string;
+}
+/** Accumulates a readable, sectioned report with FIRST-CLASS warnings — the "why isn't it working?" view.
+ *  Warnings are recorded both inline (so they appear in the narration) and separately (so an agent can
+ *  branch on `warnings` without re-parsing the text). Chainable. */
+export declare class Narrator {
+    private lines;
+    private warns;
+    /** Append a raw line. */
+    line(text: string): this;
+    /** A compact "label: k1 v1 · k2 v2 · …" status line. */
+    status(label: string, kv: Record<string, string | number>): this;
+    /** A ⚠ warning: shown inline AND collected in `warnings` so an agent can act on it programmatically. */
+    warn(text: string): this;
+    /** Warn only when `cond` holds. Returns this for chaining either way. */
+    warnIf(cond: boolean, text: string): this;
+    /** The bare warning strings (no ⚠ prefix), for agent branching. */
+    get warnings(): string[];
+    /** Was any warning raised? (a quick "is something wrong?" for an agent loop). */
+    get healthy(): boolean;
+    /** Render the whole report as one string. */
+    toString(): string;
+}
+/** Tally names into a "3 miner, 2 smelter" style histogram string, preserving first-seen order. */
+export declare function histogram(names: Iterable<string>): string;

package/dist/stateIR.js

@@ -0,0 +1,43 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ugly-game STATE IR — "debug from state, not screenshots"
+//
+// A general helper for turning ANY deterministic sim's CURRENT state into (a) a typed, JSON-able
+// structured snapshot and (b) a one-screen, sectioned, WARNING-annotated narration that surfaces the
+// actionable "why isn't it working?" — the view an AI (or a human) reads to diagnose without a picture.
+//
+// Complements the replay IR (ir.ts): that reconstructs state over TIME by re-running the sim; this
+// explains a SINGLE state readably, right now. A game exposes `AgentDebuggable` (snapshot + describe);
+// `Narrator` + `histogram` are the tools its describe() is built from. Graduated from the Cogsworth
+// factory game, where it caught starved crafters, unpowered machines, and idle logistics at a glance.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Accumulates a readable, sectioned report with FIRST-CLASS warnings — the "why isn't it working?" view.
+ *  Warnings are recorded both inline (so they appear in the narration) and separately (so an agent can
+ *  branch on `warnings` without re-parsing the text). Chainable. */
+export class Narrator {
+    lines = [];
+    warns = [];
+    /** Append a raw line. */
+    line(text) { this.lines.push(text); return this; }
+    /** A compact "label: k1 v1 · k2 v2 · …" status line. */
+    status(label, kv) {
+        this.lines.push(`${label}: ${Object.entries(kv).map(([k, v]) => `${k} ${v}`).join(' · ')}`);
+        return this;
+    }
+    /** A ⚠ warning: shown inline AND collected in `warnings` so an agent can act on it programmatically. */
+    warn(text) { this.warns.push(text); this.lines.push(`⚠ ${text}`); return this; }
+    /** Warn only when `cond` holds. Returns this for chaining either way. */
+    warnIf(cond, text) { return cond ? this.warn(text) : this; }
+    /** The bare warning strings (no ⚠ prefix), for agent branching. */
+    get warnings() { return this.warns.slice(); }
+    /** Was any warning raised? (a quick "is something wrong?" for an agent loop). */
+    get healthy() { return this.warns.length === 0; }
+    /** Render the whole report as one string. */
+    toString() { return this.lines.join('\n'); }
+}
+/** Tally names into a "3 miner, 2 smelter" style histogram string, preserving first-seen order. */
+export function histogram(names) {
+    const m = new Map();
+    for (const n of names)
+        m.set(n, (m.get(n) ?? 0) + 1);
+    return [...m].map(([k, v]) => `${v} ${k}`).join(', ');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-game",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "exports": {
     ".": {