@go-go-golems/pbui-core 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @go-go-golems/pbui-core
+
+This package is the interaction engine for presentation-based UIs, and it has no dependencies — not even React. Everything that gives the paradigm its semantics lives here: the presentation-type lattice, the presentation registry, command tables, the accept loop, undo, and the transcript. The React packages are thin bindings over this one, which is why the entire engine can be unit-tested in Node and why the same engine drives HTML, SVG, and canvas renderers.
+
+The design premise is that a UI framework's render tree records *how to draw*, not *what is meant*. This package maintains the meaning: a queryable store of which domain objects are on screen, under which types, and a state machine that interprets gestures against that store.
+
+## The five ideas
+
+1. A **ptype** (`PTypes.define`) is a named node in a subtype lattice carrying a printer, a keyboard parser, a describer, and optionally a default command. Printer and parser form a round-trip codec: what the system prints, the user can type back.
+2. An **ObjectRef** (`{kind, id}` or `valueRef(x)`) is how presentations refer to domain objects without holding them. Your `Resolver` turns refs back into objects; `undefined` means the object is gone, and the engine handles that centrally.
+3. The **PresentationRegistry** is the presentation database: every on-screen presentation registers a record, and the registry answers "which presentations of object X exist right now" (`byRef`), "which presentations of type T" (`byType`), and "what is at this point" (`at`). It is also the render-invalidation channel (`subscribePres`).
+4. A **command** declares typed arguments. Executing one with unfilled arguments starts an **input context**: eligible presentations highlight, everything else gates, and clicking, typing, or menu-choosing supplies the value. The `commandBuilder` gives this a fully typed authoring surface — `run` receives resolved domain objects, never refs.
+5. **Output records** are transcript lines built from typed parts; a `pres` part stays a live presentation forever, so printed objects can answer later commands' questions.
+
+## Minimal use (no React)
+
+```ts
+import {
+  PTypes, defineBuiltinPtypes, CommandTable, commandBuilder, arg,
+  PbuiEngine, installUndoCommands, renderTranscript, type Resolver,
+} from "@go-go-golems/pbui-core";
+
+const ptypes = new PTypes<World>();
+defineBuiltinPtypes(ptypes);                       // "number", "string"
+ptypes.define<Ship>({
+  name: "ship",
+  print: (s) => `#<SHIP ${s.name}>`,
+  parse: (text, w) => /* name prefix -> {ok, value, ref, label} */,
+});
+
+const commands = new CommandTable<World>();
+const c = commandBuilder(commands);
+c.define({
+  name: "Refuel Ship",
+  args: { ship: arg.presentation<Ship>("ship") },
+  run: ({ ship }, api) => {
+    api.snapshotUndo(world.store);                 // one-line undo opt-in
+    api.print(`Refuelled ${ship.name}.`);          // ship: Ship, resolved
+  },
+});
+
+const engine = new PbuiEngine({ ptypes, commands, world, resolver });
+installUndoCommands(engine);
+
+engine.startCommand("Refuel Ship", somePresentationRecord);
+console.log(renderTranscript(engine.transcript.lines()));
+// [echo] **Command:** Refuel Ship (ship) AURORA
+// [out ] Refuelled AURORA.
+```
+
+The engine is driven entirely through methods (`gesture`, `startCommand`, `submitTyped`, `escape`, `undoInvocation`) and observed through subscriptions (`subscribe`, `registry.subscribePres`, `transcript.subscribe`, `invocations.subscribe`) — which is exactly how the tests exercise it and how `@go-go-golems/pbui-react` binds it.
+
+## Key exports
+
+| Export | Role |
+|---|---|
+| `PTypes`, `defineBuiltinPtypes` | type lattice + print/parse codecs |
+| `PresentationRegistry` | the presentation database + invalidation channel |
+| `CommandTable`, `commandBuilder`, `arg` | commands as data; typed authoring |
+| `PbuiEngine` | gestures, accept loop, menus, coercions, focus |
+| `InvocationLog`, `installUndoCommands` | command history, linear undo |
+| `Transcript`, `S`/`B`/`E`/`P`, `renderTranscript` | output records + the golden-tested text form |
+| `pointerDoc`, `modeLabel` | pure derivations for the doc/status lines |
+
+## Contracts worth knowing before you build
+
+- Printers never receive `undefined`; the doc line and describe resolve first and fall back to a generic `#<TYPE label>` form.
+- The echo grammar (`renderTranscript` output) is pinned by golden tests. Treat it as a specification.
+- `duringAccept` commands must be seed-complete (at most one presentation argument); `CommandTable.define` throws otherwise.
+- Undo is linear-only; `snapshotUndo` restores the *whole* store, including unrelated concurrent mutations — prefer `api.undoable` with an explicit inverse in live-ticking worlds.
+- `where`/`validate` predicates run eagerly for every candidate presentation on each accept transition. Keep them cheap and pure.
+
+Deeper material: `docs/getting-started.md`, `docs/user-guide.md`, `docs/api-reference.md` at the repository root.

package/builder.d.ts

@@ -0,0 +1,74 @@
+import type { CommandApi, CommandSpec } from "./command.js";
+import { CommandTable } from "./command.js";
+type SoFar<A> = Partial<ResolvedArgs<A>>;
+export interface PresOpts<T, A, W> {
+    prompt?: string;
+    distinct?: boolean;
+    /** receive T | undefined instead of aborting on stale entities */
+    allowStale?: boolean;
+    where?: (candidate: T, soFar: SoFar<A>, world: W) => boolean;
+    validate?: (value: T, soFar: SoFar<A>, world: W) => true | string;
+}
+export interface TextOpts<A, W> {
+    prompt?: string;
+    default?: string | ((soFar: SoFar<A>, world: W) => string);
+    validate?: (value: string, soFar: SoFar<A>, world: W) => true | string;
+}
+export interface NumOpts<A, W> {
+    prompt?: string;
+    default?: number | ((soFar: SoFar<A>, world: W) => number);
+    min?: number;
+    max?: number;
+    integer?: boolean;
+    validate?: (value: number, soFar: SoFar<A>, world: W) => true | string;
+}
+export interface ChoiceOpts<T extends string, A, W> {
+    prompt?: string;
+    options: (soFar: SoFar<A>, world: W) => {
+        label: string;
+        value: T;
+    }[];
+}
+export interface ArgDesc<T = unknown> {
+    readonly ptype: string;
+    readonly kind: "presentation" | "text" | "number" | "choice";
+    /** builder-level callbacks, wrapped during compilation */
+    readonly opts: Record<string, unknown>;
+    /** phantom carrier for the resolved value type */
+    readonly __t?: T;
+}
+export declare const arg: {
+    /** an object supplied by pointing (or via the ptype's parse) */
+    presentation<T>(ptype: string, opts?: PresOpts<T, any, any>): ArgDesc<T>;
+    /** typed text -> string */
+    text(opts?: TextOpts<any, any>): ArgDesc<string>;
+    /** typed text -> number, with range/integer sugar */
+    number(opts?: NumOpts<any, any>): ArgDesc<number>;
+    /** menu choice over a closed string set */
+    choice<T extends string>(opts: ChoiceOpts<T, any, any>): ArgDesc<T>;
+};
+export type ResolvedArgs<A> = {
+    [K in keyof A]: A[K] extends ArgDesc<infer T> ? T : never;
+};
+export interface BuiltCommand<A extends Record<string, ArgDesc<any>>, W> {
+    name: string;
+    doc?: string;
+    /** insertion order of keys = accept order; key = display name */
+    args?: A;
+    /** applicability, with the first argument already resolved */
+    appliesTo?: (first: ResolvedArgs<A>[keyof A], world: W) => boolean;
+    isDefaultFor?: string[];
+    global?: boolean;
+    hidden?: boolean;
+    /** see CommandSpec.duringAccept (seed-complete rule applies) */
+    duringAccept?: boolean;
+    run: (args: ResolvedArgs<A>, api: CommandApi<W>) => void | Promise<void>;
+}
+export declare class CommandBuilder<W> {
+    private table;
+    constructor(table: CommandTable<W>);
+    define<A extends Record<string, ArgDesc<any>>>(built: BuiltCommand<A, W>): CommandSpec<W>;
+    defineAll<A extends Record<string, ArgDesc<any>>>(builts: BuiltCommand<A, W>[]): void;
+}
+export declare function commandBuilder<W>(table: CommandTable<W>): CommandBuilder<W>;
+export {};

package/builder.js

@@ -0,0 +1,191 @@
+/* The typed command builder (CLIM-JSX-004 §5).
+ *
+ * Argument descriptors carry the TypeScript type of the value a command
+ * body will receive; the builder compiles them into the existing
+ * CommandSpec/ArgSpec runtime (command.ts) and wraps `run` with
+ * resolve-then-run: entity refs are resolved through the engine's
+ * Resolver, value refs are unwrapped, and any stale entity aborts the
+ * command centrally with the standardized message — command bodies never
+ * see an ObjectRef again.
+ *
+ * Design decisions D1 (compile-to-v1) and D2 (resolve-then-run) of the
+ * CLIM-JSX-004 design doc.
+ */
+import { valueRef } from "./types.js";
+/* the arg namespace — deliberately monomorphic for readable type errors */
+export const arg = {
+    /** an object supplied by pointing (or via the ptype's parse) */
+    presentation(ptype, opts = {}) {
+        return { ptype, kind: "presentation", opts: opts };
+    },
+    /** typed text -> string */
+    text(opts = {}) {
+        return { ptype: "string", kind: "text", opts: opts };
+    },
+    /** typed text -> number, with range/integer sugar */
+    number(opts = {}) {
+        return { ptype: "number", kind: "number", opts: opts };
+    },
+    /** menu choice over a closed string set */
+    choice(opts) {
+        return { ptype: "string", kind: "choice", opts: opts };
+    },
+};
+/* ------------------------------- resolution -------------------------------- */
+const STALE = (label) => `${label} no longer exists — presentation was stale;`;
+function resolveOne(desc, v, resolve) {
+    if ("value" in v.ref) {
+        // immediates: unwrap; number descriptors coerce
+        const raw = v.ref.value;
+        return { ok: true, value: desc.kind === "number" ? Number(raw) : raw };
+    }
+    const obj = resolve(v.ref);
+    if (obj === undefined && !desc.opts["allowStale"])
+        return { ok: false, staleLabel: v.label };
+    return { ok: true, value: obj };
+}
+function resolveAll(descs, values, resolve) {
+    const resolved = {};
+    for (const [name, desc] of descs) {
+        const v = values[name];
+        if (v === undefined)
+            continue; // partial (soFar) resolution
+        const r = resolveOne(desc, v, resolve);
+        if (!r.ok)
+            return r;
+        resolved[name] = r.value;
+    }
+    return { ok: true, resolved };
+}
+/* ------------------------------- compilation ------------------------------- */
+function compileArg(name, desc, allDescs) {
+    const opts = desc.opts;
+    const soFarOf = (values, resolve) => {
+        if (!resolve)
+            return {};
+        const r = resolveAll(allDescs, values, resolve);
+        return r.ok ? r.resolved : {};
+    };
+    const spec = { name, type: desc.ptype };
+    if (opts["prompt"])
+        spec.prompt = opts["prompt"];
+    if (opts["distinct"])
+        spec.distinct = true;
+    if (desc.kind === "presentation") {
+        if (opts["where"]) {
+            const where = opts["where"];
+            spec.where = (pres, soFar, world, resolve) => {
+                if (!resolve)
+                    return true;
+                const r = resolveOne(desc, { type: pres.type, ref: pres.ref, label: pres.label }, resolve);
+                if (!r.ok)
+                    return false;
+                return where(r.value, soFarOf(soFar, resolve), world);
+            };
+        }
+        if (opts["validate"]) {
+            const validate = opts["validate"];
+            spec.validate = (v, soFar, world, resolve) => {
+                if (!resolve)
+                    return true;
+                const r = resolveOne(desc, v, resolve);
+                if (!r.ok)
+                    return `${v.label} no longer exists`;
+                return validate(r.value, soFarOf(soFar, resolve), world);
+            };
+        }
+        return spec;
+    }
+    if (desc.kind === "choice") {
+        spec.input = "menu";
+        const options = opts["options"];
+        spec.options = (soFar, world, resolve) => options(soFarOf(soFar, resolve), world).map((c) => ({
+            label: c.label,
+            ref: valueRef(c.value),
+        }));
+        return spec;
+    }
+    // text / number
+    spec.input = "typed";
+    const dflt = opts["default"];
+    if (dflt !== undefined) {
+        spec.default = (soFar, world, resolve) => {
+            const raw = typeof dflt === "function"
+                ? dflt(soFarOf(soFar, resolve), world)
+                : dflt;
+            return { type: desc.ptype, ref: valueRef(raw), label: String(raw) };
+        };
+    }
+    const userValidate = opts["validate"];
+    const { min, max, integer } = opts;
+    if (userValidate || min !== undefined || max !== undefined || integer) {
+        spec.validate = (v, soFar, world, resolve) => {
+            const raw = "value" in v.ref ? v.ref.value : undefined;
+            if (desc.kind === "number") {
+                const n = Number(raw);
+                if (integer && !Number.isInteger(n))
+                    return `${name} must be an integer`;
+                if (min !== undefined && n < min)
+                    return `${name} must be at least ${min}`;
+                if (max !== undefined && n > max)
+                    return `${name} must be at most ${max}`;
+                if (userValidate)
+                    return userValidate(n, soFarOf(soFar, resolve ?? (() => undefined)), world);
+                return true;
+            }
+            if (userValidate)
+                return userValidate(String(raw), soFarOf(soFar, resolve ?? (() => undefined)), world);
+            return true;
+        };
+    }
+    return spec;
+}
+/* -------------------------------- the builder ------------------------------ */
+export class CommandBuilder {
+    table;
+    constructor(table) {
+        this.table = table;
+    }
+    define(built) {
+        const descs = Object.entries(built.args ?? {});
+        const argSpecs = descs.map(([name, d]) => compileArg(name, d, descs));
+        const spec = {
+            name: built.name,
+            doc: built.doc,
+            args: argSpecs,
+            isDefaultFor: built.isDefaultFor,
+            global: built.global,
+            hidden: built.hidden,
+            duringAccept: built.duringAccept,
+            run: async (values, api) => {
+                const r = resolveAll(descs, values, (ref) => api.resolve({ type: "", ref, label: "" }));
+                if (!r.ok) {
+                    api.fail(STALE(r.staleLabel));
+                    return;
+                }
+                await built.run(r.resolved, api);
+            },
+        };
+        if (built.appliesTo) {
+            const appliesTo = built.appliesTo;
+            const firstDesc = descs[0]?.[1];
+            spec.appliesTo = (pres, world, resolve) => {
+                if (!firstDesc || !resolve)
+                    return true;
+                const r = resolveOne(firstDesc, { type: pres.type, ref: pres.ref, label: pres.label }, resolve);
+                if (!r.ok)
+                    return false;
+                return appliesTo(r.value, world);
+            };
+        }
+        this.table.define(spec);
+        return spec;
+    }
+    defineAll(builts) {
+        for (const b of builts)
+            this.define(b);
+    }
+}
+export function commandBuilder(table) {
+    return new CommandBuilder(table);
+}

package/command.d.ts

@@ -0,0 +1,91 @@
+import type { ArgValue, ArgValues, ObjectRef, PartLike, PresentationRecord } from "./types.js";
+export interface Choice {
+    label: string;
+    ref: ObjectRef;
+}
+/** engine-supplied ref resolution, passed to spec callbacks so layered
+ * authoring APIs (the typed builder) can hand user code live objects */
+export type ResolveFn = (ref: ObjectRef) => unknown | undefined;
+export interface ArgSpec {
+    name: string;
+    /** ptype name; "number"/"string" use typed input by default */
+    type: string;
+    /** how the value is acquired. Default: "presentation" (supply by
+     * pointing). Typed entry at the prompt works regardless whenever the
+     * ptype has a parse function; "typed" additionally focuses the input
+     * and skips presentation supply. */
+    input?: "presentation" | "typed" | "menu";
+    prompt?: string;
+    /** dependent choices for menu-valued args (design-kit.jsx:253) */
+    options?: (soFar: ArgValues, world: unknown, resolve?: ResolveFn) => Choice[];
+    /** CLIM-style default, offered as `[default …]` and taken on empty Enter */
+    default?: (soFar: ArgValues, world: unknown, resolve?: ResolveFn) => ArgValue | undefined;
+    /** must differ from every previously collected arg (scheduler:296) */
+    distinct?: boolean;
+    /** extra predicate on candidate presentations (e.g. port direction) */
+    where?: (pres: PresentationRecord, soFar: ArgValues, world: unknown, resolve?: ResolveFn) => boolean;
+    /** validate a supplied value; return an error string to reject */
+    validate?: (v: ArgValue, soFar: ArgValues, world: unknown, resolve?: ResolveFn) => true | string;
+}
+export interface CommandApi<W> {
+    print: (...parts: PartLike[]) => void;
+    printErr: (...parts: PartLike[]) => void;
+    /** standardized command failure ("<reason> <Command> aborted.") */
+    fail: (...parts: PartLike[]) => void;
+    /** opt this invocation into undo: capture runs now, returns the inverse */
+    undoable: (capture: () => () => void | Promise<void>) => void;
+    /** snapshot-undo sugar for immutable stores: captures the store state AT
+     * THE MOMENT OF THE CALL (put it before mutations, after guard clauses);
+     * undo replaces the whole store with that snapshot */
+    snapshotUndo: <S>(store: {
+        get(): S;
+        set(state: S): void;
+    }) => void;
+    world: W;
+    /** resolve a collected ArgValue to the live domain object (undefined = stale) */
+    resolve: (v: ArgValue) => unknown | undefined;
+    /** mid-body accept (promise facade, D6); null on abort */
+    accept: (spec: ArgSpec) => Promise<ArgValue | null>;
+    /** invoke another command, optionally with preset args (command chaining) */
+    invoke: (name: string, preset?: ArgValues) => void;
+}
+export interface CommandSpec<W = unknown> {
+    name: string;
+    doc?: string;
+    args?: ArgSpec[];
+    /** extra applicability beyond first-arg type matching (metrics(2):1043) */
+    appliesTo?: (pres: PresentationRecord, world: W, resolve?: ResolveFn) => boolean;
+    /** ptypes this command is the left-click default for; first match wins */
+    isDefaultFor?: string[];
+    /** reachable from the background menu / command line only */
+    global?: boolean;
+    /** hide from menus entirely (command line only) */
+    hidden?: boolean;
+    /** may run while an input context is pending, without aborting it —
+     * must be seed-complete: at most one argument, supplied by the invoking
+     * presentation (CLIM-JSX-005 D2: one input context at a time) */
+    duringAccept?: boolean;
+    run: (args: ArgValues, api: CommandApi<W>) => void | Promise<void>;
+}
+export declare class CommandTable<W = unknown> {
+    private list;
+    private byName;
+    define(spec: CommandSpec<W>): CommandSpec<W>;
+    defineAll(specs: CommandSpec<W>[]): void;
+    get(name: string): CommandSpec<W> | undefined;
+    all(): CommandSpec<W>[];
+    /** case-insensitive exact-then-prefix match; reports ambiguity */
+    match(text: string): {
+        kind: "found";
+        cmd: CommandSpec<W>;
+    } | {
+        kind: "ambiguous";
+        names: string[];
+    } | {
+        kind: "none";
+    };
+    completions(text: string): string[];
+}
+export declare function firstArg<W>(cmd: CommandSpec<W>): ArgSpec | undefined;
+/** does this command's first argument accept objects supplied by pointing? */
+export declare function takesPresentationFirst<W>(cmd: CommandSpec<W>): boolean;

package/command.js

@@ -0,0 +1,64 @@
+/* Command tables: commands as data (the converged corpus shape, §6.4).
+ *
+ * Commands declare typed arguments; menus, prompting, the mouse-doc line
+ * and the command line all derive from these declarations. Command bodies
+ * receive an injected CommandApi and never touch UI state directly
+ * (care-examiner's capability-facade rule).
+ */
+export class CommandTable {
+    list = [];
+    byName = new Map();
+    define(spec) {
+        if (this.byName.has(spec.name))
+            throw new Error(`duplicate command "${spec.name}"`);
+        if (spec.duringAccept) {
+            const args = spec.args ?? [];
+            const seedable = args.length === 0 ||
+                (args.length === 1 && (args[0].input ?? "presentation") === "presentation");
+            if (!seedable)
+                throw new Error(`duringAccept command "${spec.name}" must be seed-complete: at most one presentation argument (decision D2, one input context at a time)`);
+        }
+        this.list.push(spec);
+        this.byName.set(spec.name, spec);
+        return spec;
+    }
+    defineAll(specs) {
+        for (const s of specs)
+            this.define(s);
+    }
+    get(name) {
+        return this.byName.get(name);
+    }
+    all() {
+        return [...this.list];
+    }
+    /** case-insensitive exact-then-prefix match; reports ambiguity */
+    match(text) {
+        const t = text.trim().toLowerCase().replace(/^:/, "");
+        if (!t)
+            return { kind: "none" };
+        const exact = this.list.find((c) => c.name.toLowerCase() === t);
+        if (exact)
+            return { kind: "found", cmd: exact };
+        const hits = this.list.filter((c) => c.name.toLowerCase().startsWith(t));
+        if (hits.length === 1)
+            return { kind: "found", cmd: hits[0] };
+        if (hits.length > 1)
+            return { kind: "ambiguous", names: hits.map((c) => c.name) };
+        return { kind: "none" };
+    }
+    completions(text) {
+        const t = text.trim().toLowerCase().replace(/^:/, "");
+        return this.list
+            .filter((c) => c.name.toLowerCase().startsWith(t))
+            .map((c) => c.name);
+    }
+}
+export function firstArg(cmd) {
+    return cmd.args?.[0];
+}
+/** does this command's first argument accept objects supplied by pointing? */
+export function takesPresentationFirst(cmd) {
+    const a = firstArg(cmd);
+    return !!a && (a.input ?? "presentation") === "presentation";
+}

package/docline.d.ts

@@ -0,0 +1,5 @@
+import type { PbuiEngine } from "./engine.js";
+/** the classic Genera idle line, available as a default */
+export declare const GENERA_IDLE_DOC = "To see other commands, press Shift, Control, Meta-Shift, or Super.";
+export declare function pointerDoc(engine: PbuiEngine<any>): string;
+export declare function modeLabel(engine: PbuiEngine<any>): string;

package/docline.js

@@ -0,0 +1,43 @@
+/* Pure derivations for the mouse-doc line and the status-line mode label
+ * (decision D8: pull, never push). */
+/** the classic Genera idle line, available as a default */
+export const GENERA_IDLE_DOC = "To see other commands, press Shift, Control, Meta-Shift, or Super.";
+export function pointerDoc(engine) {
+    const { accept, menu } = engine.getState();
+    // the keyboard focus cursor documents itself exactly like hover
+    const hover = engine.getState().hover ?? engine.focusRecord();
+    if (menu)
+        return "Choose an item — Mouse-L selects; [Escape] dismisses.";
+    if (accept) {
+        const wanted = accept.spec.type.toUpperCase();
+        if (hover) {
+            if (engine.eligible(hover))
+                return `⟨${accept.spec.name}⟩${accept.cmd ? " of " + accept.cmd.name : ""} — L: use ${hover.label}   Esc: abort`;
+            if (hover.mode === "active") {
+                const dflt = engine.defaultCommandFor(hover);
+                if (dflt?.duringAccept)
+                    return `${hover.label} — L: ${dflt.name} (the pending ${accept.cmd?.name ?? "accept"} keeps waiting).`;
+            }
+            return `Accepting a ${wanted} — ${hover.label} is not applicable here. [Escape] aborts.`;
+        }
+        const pt = engine.ptypes.get(accept.spec.type);
+        const kbd = pt?.parse ? " or type it at the prompt" : "";
+        return `Accepting a ${wanted} — Mouse-L on a highlighted presentation supplies it${kbd}. [Escape] aborts.`;
+    }
+    if (hover) {
+        const dflt = engine.defaultCommandFor(hover);
+        const n = engine.applicableCommands(hover).length;
+        const left = dflt ? dflt.name : "Describe";
+        const obj = "value" in hover.ref ? hover.ref.value : engine.resolver.resolve(hover.ref);
+        return `${engine.ptypes.print(hover.type, obj, hover.label)} — L: ${left}; M: Describe; R: menu of ${n} command${n === 1 ? "" : "s"}.`;
+    }
+    return engine.idleDoc;
+}
+export function modeLabel(engine) {
+    const { accept, menu } = engine.getState();
+    if (menu)
+        return "Menu Choose";
+    if (accept)
+        return `Accept ${accept.spec.type.toUpperCase()}`;
+    return "User Input";
+}