@go-go-golems/pbui-core 0.1.0

package/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export * from "./ptype.js";
+export * from "./registry.js";
+export * from "./command.js";
+export * from "./transcript.js";
+export * from "./engine.js";
+export * from "./docline.js";
+export * from "./transcript-text.js";
+export * from "./builder.js";
+export * from "./invocation.js";

package/index.js

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export * from "./ptype.js";
+export * from "./registry.js";
+export * from "./command.js";
+export * from "./transcript.js";
+export * from "./engine.js";
+export * from "./docline.js";
+export * from "./transcript-text.js";
+export * from "./builder.js";
+export * from "./invocation.js";

package/invocation.d.ts

@@ -0,0 +1,34 @@
+import type { ArgValues, Unsubscribe } from "./types.js";
+export type InvocationStatus = "executing" | "completed" | "failed" | "undone";
+export interface CommandInvocation {
+    id: string;
+    name: string;
+    /** args as collected — refs, so records survive world GC */
+    argValues: ArgValues;
+    status: InvocationStatus;
+    error?: string;
+    /** present iff the command opted into undo and completed */
+    undo?: () => void | Promise<void>;
+    /** monotonic ordering */
+    seq: number;
+    /** transcript echo line this invocation belongs to, if any */
+    echoLineId?: string;
+}
+export declare class InvocationLog {
+    private cap;
+    private records;
+    private listeners;
+    constructor(cap?: number);
+    record(name: string, argValues: ArgValues, echoLineId?: string): CommandInvocation;
+    private patch;
+    complete(id: string, undo?: () => void | Promise<void>): void;
+    fail(id: string, error: string): void;
+    markUndone(id: string): void;
+    byId(id: string): CommandInvocation | undefined;
+    byEchoLine(lineId: string): CommandInvocation | undefined;
+    /** the only invocation Undo will touch — linear undo (D4) */
+    lastUndoable(): CommandInvocation | undefined;
+    list(): CommandInvocation[];
+    subscribe(fn: () => void): Unsubscribe;
+    private emit;
+}

package/invocation.js

@@ -0,0 +1,71 @@
+/* Command invocation records (CLIM-JSX-004 §7) — the thesis's "command
+ * application": every executed command becomes a first-class record with
+ * lifecycle state, presentable and (when the command opted in) undoable.
+ *
+ * Core stays clock-free (decision D5): `seq` orders records; apps map to
+ * wall time at display if they want it. Undo is linear-only (decision D4).
+ */
+let nextSeq = 1;
+export class InvocationLog {
+    cap;
+    records = [];
+    listeners = new Set();
+    constructor(cap = 100) {
+        this.cap = cap;
+    }
+    record(name, argValues, echoLineId) {
+        const seq = nextSeq++;
+        const inv = {
+            id: `inv-${seq}`,
+            name,
+            argValues,
+            status: "executing",
+            seq,
+            echoLineId,
+        };
+        this.records = [...this.records, inv];
+        if (this.records.length > this.cap)
+            this.records = this.records.slice(this.records.length - this.cap);
+        this.emit();
+        return inv;
+    }
+    patch(id, p) {
+        this.records = this.records.map((r) => (r.id === id ? { ...r, ...p } : r));
+        this.emit();
+    }
+    complete(id, undo) {
+        this.patch(id, { status: "completed", undo });
+    }
+    fail(id, error) {
+        this.patch(id, { status: "failed", error });
+    }
+    markUndone(id) {
+        this.patch(id, { status: "undone", undo: undefined });
+    }
+    byId(id) {
+        return this.records.find((r) => r.id === id);
+    }
+    byEchoLine(lineId) {
+        return this.records.find((r) => r.echoLineId === lineId);
+    }
+    /** the only invocation Undo will touch — linear undo (D4) */
+    lastUndoable() {
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const r = this.records[i];
+            if (r.status === "completed" && r.undo)
+                return r;
+        }
+        return undefined;
+    }
+    list() {
+        return this.records;
+    }
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    emit() {
+        for (const fn of this.listeners)
+            fn();
+    }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@go-go-golems/pbui-core",
+  "version": "0.1.0",
+  "description": "PBUI core package.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Manuel Odendahl",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/go-go-golems/react-pbui.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/go-go-golems/react-pbui/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/go-go-golems/react-pbui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": "./index.js"
+  }
+}

package/ptype.d.ts

@@ -0,0 +1,40 @@
+import type { ObjectRef, PartLike } from "./types.js";
+export type ParseResult<T = unknown> = {
+    ok: true;
+    value: T;
+    ref: ObjectRef;
+    label: string;
+} | {
+    ok: false;
+    err: string;
+};
+export interface PTypeSpec<T = unknown, W = unknown> {
+    name: string;
+    /** direct supertypes; omitted = child of "any" */
+    supertypes?: string[];
+    /** printed representation, e.g. `#<TASK T-3>` */
+    print?: (obj: T) => string;
+    /** keyboard half of accept: parse typed text against the world */
+    parse?: (text: string, world: W) => ParseResult<T>;
+    /** rich Describe output; falls back to the printed representation */
+    describe?: (obj: T, world: W) => PartLike[];
+    /** command started on plain left-click outside an input context */
+    defaultCommand?: string;
+}
+export interface PType<T = unknown, W = unknown> extends PTypeSpec<T, W> {
+    supertypes: string[];
+}
+export declare class PTypes<W = unknown> {
+    private byName;
+    define<T>(spec: PTypeSpec<T, W>): PType<T, W>;
+    get(name: string): PType<unknown, W> | undefined;
+    /** is `t` a subtype of `want`? Everything is a subtype of "any". */
+    subtypep(t: string, want: string): boolean;
+    /** ["milestone","task","any"] — first parent chain, for lattice display */
+    latticePath(t: string): string[];
+    /** "MILESTONE ⊂ TASK ⊂ ANY" — the context-menu title convention */
+    latticeLabel(t: string): string;
+    print(type: string, obj: unknown, label?: string): string;
+}
+/** Register the "number" and "string" argument ptypes used by typed input. */
+export declare function defineBuiltinPtypes<W>(ptypes: PTypes<W>): void;

package/ptype.js

@@ -0,0 +1,103 @@
+/* Presentation types (ptypes): a named lattice with per-type codecs.
+ *
+ * Types form a parent lattice ("milestone" ⊂ "task" ⊂ ...); "any" is the
+ * implicit top. Each type may carry a printer, a keyboard parser (the two
+ * halves of the round-trip codec, aitr-794.md:856-880), a describer, and
+ * the name of its default left-click command.
+ */
+export class PTypes {
+    byName = new Map();
+    define(spec) {
+        if (spec.name === "any")
+            throw new Error(`"any" is reserved`);
+        const t = { ...spec, supertypes: spec.supertypes ?? [] };
+        for (const s of t.supertypes) {
+            if (s !== "any" && !this.byName.has(s))
+                throw new Error(`unknown supertype "${s}" of "${spec.name}"`);
+        }
+        // reject cycles (supertypes must already exist, so cycles are impossible
+        // by construction, but guard against self-reference)
+        if (t.supertypes.includes(spec.name))
+            throw new Error(`ptype "${spec.name}" cannot be its own supertype`);
+        this.byName.set(spec.name, t);
+        return t;
+    }
+    get(name) {
+        return this.byName.get(name);
+    }
+    /** is `t` a subtype of `want`? Everything is a subtype of "any". */
+    subtypep(t, want) {
+        if (want === "any" || t === want)
+            return true;
+        const seen = new Set();
+        const stack = [t];
+        while (stack.length) {
+            const cur = stack.pop();
+            if (cur === want)
+                return true;
+            if (seen.has(cur))
+                continue;
+            seen.add(cur);
+            const def = this.byName.get(cur);
+            if (def)
+                stack.push(...def.supertypes);
+        }
+        return false;
+    }
+    /** ["milestone","task","any"] — first parent chain, for lattice display */
+    latticePath(t) {
+        const chain = [t];
+        let cur = this.byName.get(t);
+        while (cur && cur.supertypes.length > 0) {
+            const parent = cur.supertypes[0];
+            chain.push(parent);
+            cur = this.byName.get(parent);
+        }
+        if (chain[chain.length - 1] !== "any")
+            chain.push("any");
+        return chain;
+    }
+    /** "MILESTONE ⊂ TASK ⊂ ANY" — the context-menu title convention */
+    latticeLabel(t) {
+        return this.latticePath(t)
+            .map((x) => x.toUpperCase())
+            .join(" ⊂ ");
+    }
+    print(type, obj, label) {
+        const def = this.byName.get(type);
+        if (def?.print && obj !== undefined) {
+            try {
+                return def.print(obj);
+            }
+            catch {
+                // fall through to the generic form on printer errors
+            }
+        }
+        return `#<${type.toUpperCase()}${label ? " " + label : ""}>`;
+    }
+}
+/* ------------------------- built-in argument ptypes ----------------------- */
+import { valueRef } from "./types.js";
+/** Register the "number" and "string" argument ptypes used by typed input. */
+export function defineBuiltinPtypes(ptypes) {
+    ptypes.define({
+        name: "number",
+        print: (n) => String(n),
+        parse: (text) => {
+            const n = Number(text.trim());
+            if (text.trim() === "" || Number.isNaN(n))
+                return { ok: false, err: `${text.trim() || "??"} is not a valid NUMBER` };
+            return { ok: true, value: n, ref: valueRef(n), label: String(n) };
+        },
+    });
+    ptypes.define({
+        name: "string",
+        print: (s) => JSON.stringify(s),
+        parse: (text) => {
+            const s = text.trim();
+            if (!s)
+                return { ok: false, err: "empty STRING" };
+            return { ok: true, value: s, ref: valueRef(s), label: s };
+        },
+    });
+}

package/registry.d.ts

@@ -0,0 +1,40 @@
+import type { ObjectRef, PresentationRecord, PresId, Rect, Unsubscribe } from "./types.js";
+export type RegistryEvent = {
+    kind: "register";
+    rec: PresentationRecord;
+} | {
+    kind: "update";
+    rec: PresentationRecord;
+} | {
+    kind: "unregister";
+    id: PresId;
+};
+export declare function refKey(r: ObjectRef): string;
+export declare class PresentationRegistry {
+    private recs;
+    private listeners;
+    private presListeners;
+    private presVersions;
+    private byRefIdx;
+    /** bump one presentation's flag version and wake its subscribers */
+    notifyPres(id: PresId): void;
+    /** accept transitions legitimately change everyone's flags (D3) */
+    notifyAllPres(): void;
+    subscribePres(id: PresId, fn: () => void): Unsubscribe;
+    presVersion(id: PresId): number;
+    register(rec: Omit<PresentationRecord, "id">): PresId;
+    private indexRef;
+    private unindexRef;
+    update(id: PresId, patch: Partial<Omit<PresentationRecord, "id">>): void;
+    unregister(id: PresId): void;
+    get(id: PresId): PresentationRecord | undefined;
+    all(): PresentationRecord[];
+    /** every presentation of the given object — cross-pane highlighting */
+    byRef(ref: ObjectRef): PresentationRecord[];
+    byType(type: string): PresentationRecord[];
+    /** smallest hit-testable presentation containing the point */
+    at(x: number, y: number): PresentationRecord | undefined;
+    subscribe(fn: (ev: RegistryEvent) => void): Unsubscribe;
+    private emit;
+}
+export type { Rect };

package/registry.js

@@ -0,0 +1,143 @@
+/* The PresentationRegistry — the thesis's "presentation data base" (D2).
+ *
+ * A subscribable store of every presentation currently on screen (or in the
+ * transcript). Presenters register on mount and unregister on unmount;
+ * consumers query by object ref, by ptype, or by screen point.
+ */
+let nextId = 1;
+export function refKey(r) {
+    return "value" in r ? `v:${String(r.value)}` : `${r.kind}:${r.id}`;
+}
+export class PresentationRegistry {
+    recs = new Map();
+    listeners = new Set();
+    /* per-presentation invalidation channel (CLIM-JSX-005 §6.2): hover-paced
+     * flag changes notify exactly the affected presentations */
+    presListeners = new Map();
+    presVersions = new Map();
+    /* refKey -> ids index so byRef is O(presentations-of-that-object) */
+    byRefIdx = new Map();
+    /** bump one presentation's flag version and wake its subscribers */
+    notifyPres(id) {
+        this.presVersions.set(id, (this.presVersions.get(id) ?? 0) + 1);
+        const set = this.presListeners.get(id);
+        if (set)
+            for (const fn of set)
+                fn();
+    }
+    /** accept transitions legitimately change everyone's flags (D3) */
+    notifyAllPres() {
+        for (const id of this.recs.keys())
+            this.notifyPres(id);
+    }
+    subscribePres(id, fn) {
+        let set = this.presListeners.get(id);
+        if (!set) {
+            set = new Set();
+            this.presListeners.set(id, set);
+        }
+        set.add(fn);
+        return () => {
+            set.delete(fn);
+            if (set.size === 0)
+                this.presListeners.delete(id);
+        };
+    }
+    presVersion(id) {
+        return this.presVersions.get(id) ?? 0;
+    }
+    register(rec) {
+        const id = `p${nextId++}`;
+        const full = { ...rec, id };
+        this.recs.set(id, full);
+        this.indexRef(full);
+        this.emit({ kind: "register", rec: full });
+        return id;
+    }
+    indexRef(rec) {
+        const k = refKey(rec.ref);
+        let set = this.byRefIdx.get(k);
+        if (!set) {
+            set = new Set();
+            this.byRefIdx.set(k, set);
+        }
+        set.add(rec.id);
+    }
+    unindexRef(rec) {
+        const k = refKey(rec.ref);
+        const set = this.byRefIdx.get(k);
+        if (set) {
+            set.delete(rec.id);
+            if (set.size === 0)
+                this.byRefIdx.delete(k);
+        }
+    }
+    update(id, patch) {
+        const cur = this.recs.get(id);
+        if (!cur)
+            return;
+        const next = { ...cur, ...patch };
+        this.unindexRef(cur);
+        this.recs.set(id, next);
+        this.indexRef(next);
+        this.emit({ kind: "update", rec: next });
+    }
+    unregister(id) {
+        const cur = this.recs.get(id);
+        if (!cur)
+            return;
+        this.recs.delete(id);
+        this.unindexRef(cur);
+        this.presListeners.delete(id);
+        this.presVersions.delete(id);
+        this.emit({ kind: "unregister", id });
+    }
+    get(id) {
+        return this.recs.get(id);
+    }
+    all() {
+        return [...this.recs.values()];
+    }
+    /** every presentation of the given object — cross-pane highlighting */
+    byRef(ref) {
+        const ids = this.byRefIdx.get(refKey(ref));
+        if (!ids)
+            return [];
+        const out = [];
+        for (const id of ids) {
+            const r = this.recs.get(id);
+            if (r)
+                out.push(r);
+        }
+        return out;
+    }
+    byType(type) {
+        return this.all().filter((r) => r.type === type);
+    }
+    /** smallest hit-testable presentation containing the point */
+    at(x, y) {
+        let best;
+        let bestArea = Infinity;
+        for (const r of this.recs.values()) {
+            const b = r.bounds?.();
+            if (!b)
+                continue;
+            if (x >= b.x && x <= b.x + b.w && y >= b.y && y <= b.y + b.h) {
+                const area = b.w * b.h;
+                if (area < bestArea) {
+                    bestArea = area;
+                    best = r;
+                }
+            }
+        }
+        return best;
+    }
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    emit(ev) {
+        for (const fn of this.listeners)
+            fn(ev);
+    }
+}

package/transcript-text.d.ts

@@ -0,0 +1,3 @@
+import type { OutputRecord } from "./types.js";
+export declare function renderRecord(rec: OutputRecord): string;
+export declare function renderTranscript(records: OutputRecord[]): string;

package/transcript-text.js

@@ -0,0 +1,31 @@
+/* Canonical text rendering of transcript records.
+ *
+ * This is the format the golden-transcript tests pin: the echo grammar is
+ * a specification, and refactors must not move a character of it.
+ *
+ *   [echo] Command: Compare Sites (site-a) {site SITE-ALPHA}
+ *   [out]  Compared **SITE-ALPHA** with ...
+ *   [err]  ...
+ *
+ * pres parts render as {type label}, bold as **text**.
+ */
+export function renderRecord(rec) {
+    const body = rec.parts
+        .map((p) => {
+        switch (p.t) {
+            case "text":
+                return p.s;
+            case "bold":
+                return `**${p.s}**`;
+            case "err":
+                return p.s;
+            case "pres":
+                return `{${p.type} ${p.label}}`;
+        }
+    })
+        .join("");
+    return `[${rec.kind.padEnd(4)}] ${body}`;
+}
+export function renderTranscript(records) {
+    return records.map(renderRecord).join("\n") + "\n";
+}

package/transcript.d.ts

@@ -0,0 +1,16 @@
+import type { OutputKind, OutputRecord, PartLike, Unsubscribe } from "./types.js";
+export declare class Transcript {
+    private cap;
+    private records;
+    private listeners;
+    constructor(cap?: number);
+    print(kind: OutputKind, ...parts: PartLike[]): OutputRecord;
+    out(...parts: PartLike[]): OutputRecord;
+    echo(...parts: PartLike[]): OutputRecord;
+    err(...parts: PartLike[]): OutputRecord;
+    clear(): void;
+    /** stable snapshot for useSyncExternalStore */
+    lines(): OutputRecord[];
+    subscribe(fn: () => void): Unsubscribe;
+    private emit;
+}

package/transcript.js

@@ -0,0 +1,49 @@
+/* The transcript: a capped, subscribable list of output records whose
+ * object parts remain live presentations (D7). */
+import { toPart } from "./types.js";
+let nextLineId = 1;
+export class Transcript {
+    cap;
+    records = [];
+    listeners = new Set();
+    constructor(cap = 300) {
+        this.cap = cap;
+    }
+    print(kind, ...parts) {
+        const rec = {
+            id: `l${nextLineId++}`,
+            kind,
+            parts: parts.map(toPart),
+        };
+        this.records = [...this.records, rec];
+        if (this.records.length > this.cap)
+            this.records = this.records.slice(this.records.length - this.cap);
+        this.emit();
+        return rec;
+    }
+    out(...parts) {
+        return this.print("out", ...parts);
+    }
+    echo(...parts) {
+        return this.print("echo", ...parts);
+    }
+    err(...parts) {
+        return this.print("err", ...parts);
+    }
+    clear() {
+        this.records = [];
+        this.emit();
+    }
+    /** stable snapshot for useSyncExternalStore */
+    lines() {
+        return this.records;
+    }
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    emit() {
+        for (const fn of this.listeners)
+            fn();
+    }
+}

package/types.d.ts

@@ -0,0 +1,83 @@
+/** Reference to a domain object. `kind` names the object family, `id` its key.
+ * Immediate values (numbers, strings, enum choices) use kind "value". */
+export type ObjectRef = {
+    kind: string;
+    id: string;
+} | {
+    kind: "value";
+    value: unknown;
+};
+export declare function valueRef(value: unknown): ObjectRef;
+export declare function refEquals(a: ObjectRef, b: ObjectRef): boolean;
+/** Apps supply a resolver from refs to live domain objects.
+ * `undefined` means the object no longer exists (stale presentation). */
+export interface Resolver {
+    resolve(ref: ObjectRef): unknown | undefined;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type PresId = string;
+/** A presentation: a typed, on-screen (or in-transcript) handle to a domain
+ * object. This is the record stored in the PresentationRegistry — the
+ * thesis's "presentation data base". */
+export interface PresentationRecord {
+    id: PresId;
+    /** ptype name */
+    type: string;
+    ref: ObjectRef;
+    /** display label used in echoes, menus and the mouse-doc line */
+    label: string;
+    paneId?: string;
+    parentId?: PresId;
+    /** participation during a foreign input context (CLIM-JSX-005 §5):
+     *  gated (default) — dimmed and swallowed; active — stays interactive,
+     *  left-click may run a duringAccept command without aborting the
+     *  context; fallthrough — gesture-transparent (canvas overlays) */
+    mode?: "gated" | "active" | "fallthrough";
+    /** lazily measured screen bounds; null/undefined = not hit-testable */
+    bounds?: () => Rect | null;
+}
+/** The subset of a presentation needed to supply/echo an argument.
+ * Argument values collected by the accept loop are stored in this shape,
+ * whether they came from a click, the keyboard, or a menu. */
+export interface ArgValue {
+    type: string;
+    ref: ObjectRef;
+    label: string;
+}
+export type ArgValues = Record<string, ArgValue>;
+export type OutputPart = {
+    t: "text";
+    s: string;
+} | {
+    t: "bold";
+    s: string;
+} | {
+    t: "err";
+    s: string;
+}
+/** a live presentation embedded in transcript output — stays sensitive */
+ | {
+    t: "pres";
+    type: string;
+    ref: ObjectRef;
+    label: string;
+};
+export type OutputKind = "out" | "echo" | "err";
+export interface OutputRecord {
+    id: string;
+    kind: OutputKind;
+    parts: OutputPart[];
+}
+/** Loose input accepted by print helpers: strings become text parts. */
+export type PartLike = OutputPart | string;
+export declare function toPart(p: PartLike): OutputPart;
+export declare const S: (s: string) => OutputPart;
+export declare const B: (s: string) => OutputPart;
+export declare const E: (s: string) => OutputPart;
+export declare const P: (type: string, ref: ObjectRef, label: string) => OutputPart;
+export type Unsubscribe = () => void;