@go-go-golems/pbui-core 0.1.0

package/engine.d.ts

@@ -0,0 +1,177 @@
+import type { ArgValue, ArgValues, ObjectRef, PartLike, PresentationRecord, Unsubscribe } from "./types.js";
+import type { ArgSpec, CommandSpec } from "./command.js";
+import { CommandTable } from "./command.js";
+import { PTypes } from "./ptype.js";
+import { PresentationRegistry } from "./registry.js";
+import { Transcript } from "./transcript.js";
+import { InvocationLog } from "./invocation.js";
+import type { Resolver } from "./types.js";
+export interface AcceptState {
+    /** command being filled; null for an ad-hoc api.accept() */
+    cmd: CommandSpec<any> | null;
+    values: ArgValues;
+    spec: ArgSpec;
+    resolveAdhoc?: (v: ArgValue | null) => void;
+}
+export interface MenuItem {
+    label: string;
+    doc?: string;
+    disabled?: boolean;
+    run: () => void;
+}
+export interface MenuState {
+    x: number;
+    y: number;
+    title: string;
+    items: MenuItem[];
+}
+export interface EngineState {
+    accept: AcceptState | null;
+    hover: PresentationRecord | null;
+    menu: MenuState | null;
+    pointer: {
+        x: number;
+        y: number;
+    };
+    /** keyboard focus cursor over presentations (CLIM-JSX-004 §6.1) */
+    focus: string | null;
+}
+export interface Coercion {
+    from: string;
+    to: string;
+    coerce: (pres: PresentationRecord) => ArgValue;
+}
+export interface EngineOptions<W> {
+    ptypes: PTypes<W>;
+    commands: CommandTable<W>;
+    world: W;
+    resolver: Resolver;
+    transcriptCap?: number;
+    /** idle mouse-doc line text */
+    idleDoc?: string;
+}
+export type GestureKind = "click" | "aux" | "context" | "enter" | "leave";
+export declare class PbuiEngine<W = unknown> {
+    readonly ptypes: PTypes<W>;
+    readonly commands: CommandTable<W>;
+    readonly registry: PresentationRegistry;
+    readonly transcript: Transcript;
+    readonly world: W;
+    readonly resolver: Resolver;
+    readonly idleDoc: string;
+    /** every executed command, with lifecycle state (CLIM-JSX-004 §7) */
+    readonly invocations: InvocationLog;
+    /** transcript echo line awaiting its invocation (set by startCommand*) */
+    private pendingEchoLineId;
+    /** bound resolver passthrough handed to spec callbacks (ResolveFn).
+     * Invocation refs resolve from the engine's own log; everything else
+     * delegates to the app resolver. */
+    readonly resolveFn: (ref: ObjectRef) => unknown | undefined;
+    private coercions;
+    private listeners;
+    /** ids of registered presentations eligible for the current accept
+     * (CLIM-JSX-005 §6.3); null when no accept is active */
+    private eligibleIds;
+    private state;
+    constructor(opts: EngineOptions<W>);
+    getState(): EngineState;
+    subscribe(fn: () => void): Unsubscribe;
+    private setState;
+    /** hover transitions notify exactly the affected presentations: the old
+     * and new hover targets plus every presentation of the same objects
+     * (related-hover outlines). This is the mouse-frequency hot path. */
+    private setHover;
+    print(...parts: PartLike[]): void;
+    printErr(...parts: PartLike[]): void;
+    /** standardized command failure (stale arguments etc.): prints the
+     * error line only. api.fail (the wrapper commands receive) additionally
+     * marks the current invocation as failed — prefer it inside commands. */
+    failInvocation(cmdName: string, ...reason: PartLike[]): void;
+    defineCoercion(c: Coercion): void;
+    /** turn a presentation into the ArgValue a spec wants, or null */
+    private coerceFor;
+    /** the full predicate — used to (re)build the cache and for ad-hoc
+     * (unregistered) records such as test fixtures */
+    private eligibleUncached;
+    /** would clicking this presentation supply the currently wanted arg?
+     * O(1) for registered presentations via the eligible-set cache. */
+    eligible(pres: Pick<PresentationRecord, "type" | "ref" | "label"> & {
+        id?: string;
+    }): boolean;
+    /** registered presentations eligible right now (keyboard Tab-cycling) */
+    eligibleList(): PresentationRecord[];
+    private recomputeEligible;
+    /** accept transitions recompute the cache and broadcast (D3: accept
+     * changes are user-paced; hover changes are the targeted hot path) */
+    private setAccept;
+    /** an input context is active and this presentation does not match */
+    inert(pres: Pick<PresentationRecord, "type" | "ref" | "label">): boolean;
+    startCommand(nameOrCmd: string | CommandSpec<W>, seed?: PresentationRecord): void;
+    /** run with preset values (from the command line's positional args) */
+    startCommandWithValues(cmd: CommandSpec<W>, values: ArgValues): void;
+    private advance;
+    /** supply the current argument by pointing at a presentation */
+    supply(pres: PresentationRecord): void;
+    /** supply the current argument with an already-built value */
+    supplyValue(v: ArgValue): void;
+    abort(silent?: boolean): void;
+    private execute;
+    private makeApi;
+    /** promise facade over the FSM (metrics(1)'s prompt(), D6) */
+    acceptAdhoc(spec: ArgSpec): Promise<ArgValue | null>;
+    /** Enter pressed in the listener input. Routes to the pending argument or
+     * to the command line. Returns true if the text was consumed. */
+    submitTyped(text: string): boolean;
+    /** command line: longest-prefix command match + greedy positional args */
+    submitCommandLine(text: string): boolean;
+    completions(text: string): string[];
+    notePointer(x: number, y: number): void;
+    gesture(kind: GestureKind, pres: PresentationRecord, x?: number, y?: number): void;
+    backgroundContext(x: number, y: number): void;
+    escape(): void;
+    /** left-click outside an input context: per-type default command, else Describe */
+    defaultAction(pres: PresentationRecord): void;
+    defaultCommandFor(pres: PresentationRecord): CommandSpec<W> | undefined;
+    /** run a seed-complete duringAccept command WITHOUT touching the pending
+     * input context; eligibility recomputes afterwards in case the command's
+     * effects changed where-clauses */
+    private executeImmediate;
+    /** reduced menu on active presentations mid-accept: duringAccept commands
+     * only (plus the chrome's Abort footer) */
+    private openDuringAcceptMenu;
+    describePres(pres: Pick<PresentationRecord, "type" | "ref" | "label">): void;
+    commandApplies(cmd: CommandSpec<W>, pres: PresentationRecord): boolean;
+    applicableCommands(pres: PresentationRecord): CommandSpec<W>[];
+    openCommandMenu(pres: PresentationRecord, x: number, y: number): void;
+    openGlobalMenu(x: number, y: number): void;
+    private openChoiceMenu;
+    closeMenu(): void;
+    /** set the keyboard focus cursor; targeted notification like hover */
+    setFocus(id: string | null): void;
+    /** the presentation that should carry tabIndex=0: the focus cursor if it
+     * still exists, else the first registered presentation */
+    focusTarget(): string | null;
+    /** the focused presentation record, for the doc line */
+    focusRecord(): PresentationRecord | null;
+    /** move the focus cursor through registry order (arrow keys) */
+    moveFocus(dir: 1 | -1): string | null;
+    /** Tab during an accept: cycle the eligible presentations */
+    moveFocusEligible(dir: 1 | -1): string | null;
+    /** Undo the most recent undoable invocation. Linear-only (D4): passing an
+     * id that is not the last undoable is refused with a coaching message. */
+    undoInvocation(id?: string): Promise<boolean>;
+    promptInfo(): {
+        accepting: boolean;
+        cmdName?: string;
+        filled: {
+            name: string;
+            label: string;
+        }[];
+        spec?: ArgSpec;
+        defaultLabel?: string;
+        typedInput: boolean;
+    };
+}
+/** Register the builtin Undo command, the "invocation" ptype, and the
+ * per-invocation Undo command (used by transcript/activity menus). */
+export declare function installUndoCommands<W>(engine: PbuiEngine<W>): void;