toolcraft-openapi 0.0.151 → 0.0.153

package/node_modules/toolcraft-design/dist/explorer/runtime.js

@@ -1,10 +1,11 @@
-import { ScreenBuffer, cellToAnsi, diff } from "../dashboard/buffer.js";
-import { createTerminalDriver } from "../dashboard/terminal.js";
+import { Screen } from "../screen/screen.js";
+import { appendFileSync } from "node:fs";
+import { createTerminalDriver } from "../terminal/driver.js";
 import { createDetailJobs } from "./jobs.js";
 import { computeExplorerLayout } from "./layout.js";
 import { renderExplorer } from "./render/index.js";
 import { step } from "./reducer.js";
-import { createInitialState, REGION_ALL, REGION_MODAL, REGION_TOAST } from "./state.js";
+import { createInitialState, REGION_ALL, REGION_MODAL, REGION_TOAST, normalizeExplorerConfig } from "./state.js";
 const TOAST_MS = 2500;
 export async function runExplorer(config) {
     if (process.stdout.isTTY !== true) {
@@ -15,10 +16,10 @@ export async function runExplorer(config) {
     return runtime.run();
 }
 class ExplorerRuntime {
-    config;
     driver;
+    config;
     state;
-    previousBuffer = new ScreenBuffer(0, 0);
+    screen;
     detailJobs;
     runtimeHandles;
     pendingEffects = new Set();
@@ -28,11 +29,14 @@ class ExplorerRuntime {
     rowsRequestToken = 0;
     reorderToken = 0;
     stopped = false;
+    renderScheduled = false;
+    tracePath = process.env.POE_CODE_TUI_TRACE;
     settle;
     constructor(config, driver) {
-        this.config = config;
         this.driver = driver;
-        this.state = createInitialState(config, driver.getSize());
+        this.config = normalizeExplorerConfig(config);
+        this.state = createInitialState(this.config, driver.getSize());
+        this.screen = new Screen(driver.getSize());
         this.detailJobs = createDetailJobs((event) => {
             if (event.type === "detailLoaded") {
                 this.loadDetailContent(event.rowId, event.token, event.items);
@@ -69,7 +73,7 @@ class ExplorerRuntime {
                     // Seed list/detail before first paint so callers with known rows avoid an empty flash.
                     this.dispatch({ type: "rowsLoaded", rows: this.config.initialRows });
                 }
-                this.render();
+                this.renderNow();
                 this.loadRows().catch((error) => {
                     this.fail(error);
                 });
@@ -80,13 +84,9 @@ class ExplorerRuntime {
         });
     }
     startTerminal() {
-        this.driver.enterRawMode();
-        this.driver.enterAltScreen();
-        this.driver.disableLineWrap();
-        this.driver.hideCursor();
+        this.driver.start();
         this.subscribeKeypress();
-        this.unsubscribeResize = this.driver.onResize(() => {
-            const size = this.driver.getSize();
+        this.unsubscribeResize = this.driver.onResize((size) => {
             this.dispatch({ type: "resize", cols: size.cols, rows: size.rows });
         });
     }
@@ -94,8 +94,19 @@ class ExplorerRuntime {
         if (this.unsubscribeKeypress !== undefined) {
             return;
         }
-        this.unsubscribeKeypress = this.driver.onKeypress((key) => {
-            this.dispatch({ type: "key", key });
+        this.unsubscribeKeypress = this.driver.onEvent((event) => {
+            this.trace("input", { event });
+            if (event.type === "paste") {
+                for (const ch of event.text.replaceAll("\n", "").replaceAll("\r", "")) {
+                    this.dispatch({ type: "key", key: { ch, name: ch, ctrl: false, meta: false, shift: false } });
+                }
+                return;
+            }
+            if (event.type === "wheel") {
+                this.dispatch({ type: "key", key: { name: event.direction, ctrl: false, meta: false, shift: false } });
+                return;
+            }
+            this.dispatch({ type: "key", key: { name: event.name, ch: event.ch, ctrl: event.ctrl, meta: event.alt, shift: event.shift } });
         });
     }
     pauseKeypress() {
@@ -120,13 +131,13 @@ class ExplorerRuntime {
         const previousState = this.state;
         const next = step(this.state, event, this.runtimeHandles);
         this.state = next.state;
-        this.render();
+        this.scheduleRender();
         this.applyEffects(next.effects, previousState);
     }
     applyEffects(effects, previousState) {
         for (const effect of effects) {
             if (effect.type === "renderDetail") {
-                this.renderDetail(effect.rowId);
+                this.renderDetail(effect.rowId, effect.token);
                 continue;
             }
             if (effect.type === "persistOrder") {
@@ -142,7 +153,7 @@ class ExplorerRuntime {
             }
         }
     }
-    renderDetail(rowId) {
+    renderDetail(rowId, token) {
         const row = this.state.rows.find((candidate) => candidate.id === rowId);
         if (row === undefined) {
             return;
@@ -150,10 +161,11 @@ class ExplorerRuntime {
         const layout = computeExplorerLayout({
             cols: this.state.size.cols,
             rows: this.state.size.rows,
-            detailHidden: this.state.layout === "narrow-list-only" || this.state.layout === "too-narrow"
+            detailHidden: this.state.layout === "narrow-list-only" || this.state.layout === "too-narrow",
+            focused: this.state.focused
         });
         const reloadDetail = () => this.reloadFocusedDetail(rowId);
-        void this.detailJobs.schedule(rowId, (ctx) => this.config.detail.items(row, { ...ctx, reloadDetail }), {
+        void this.detailJobs.schedule(rowId, token, (ctx) => this.config.detail.items(row, { ...ctx, reloadDetail }), {
             width: layout.detail.width,
             height: layout.detail.height,
             row,
@@ -169,7 +181,9 @@ class ExplorerRuntime {
         if (rowId !== undefined && rowId !== focusedId) {
             return;
         }
-        this.renderDetail(focusedId);
+        const token = this.state.detail.token + 1;
+        this.state = { ...this.state, detail: { ...this.state.detail, token } };
+        this.renderDetail(focusedId, token);
     }
     loadDetailContent(rowId, token, items) {
         const row = this.state.rows.find((candidate) => candidate.id === rowId);
@@ -179,7 +193,8 @@ class ExplorerRuntime {
         const layout = computeExplorerLayout({
             cols: this.state.size.cols,
             rows: this.state.size.rows,
-            detailHidden: this.state.layout === "narrow-list-only" || this.state.layout === "too-narrow"
+            detailHidden: this.state.layout === "narrow-list-only" || this.state.layout === "too-narrow",
+            focused: this.state.focused
         });
         const context = {
             width: layout.detail.width,
@@ -243,19 +258,15 @@ class ExplorerRuntime {
     }
     async suspendAnd(fn) {
         this.pauseKeypress();
-        this.driver.exitAltScreen();
-        this.driver.enableLineWrap();
-        this.driver.showCursor();
-        this.driver.exitRawMode();
+        this.state = { ...this.state, suspended: true };
+        this.driver.stop();
         try {
             return await fn();
         }
         finally {
             if (!this.stopped) {
-                this.driver.enterRawMode();
-                this.driver.enterAltScreen();
-                this.driver.disableLineWrap();
-                this.driver.hideCursor();
+                this.driver.start();
+                this.state = { ...this.state, suspended: false };
                 this.subscribeKeypress();
                 const size = this.driver.getSize();
                 this.dispatch({
@@ -284,7 +295,7 @@ class ExplorerRuntime {
                 },
                 dirty: REGION_MODAL
             };
-            this.render();
+            this.scheduleRender();
         });
     }
     showToast(message, tone = "info") {
@@ -299,7 +310,7 @@ class ExplorerRuntime {
             toast: { message, tone, expiresAt: Date.now() + TOAST_MS },
             dirty: REGION_TOAST
         };
-        this.render();
+        this.scheduleRender();
         this.toastTimer = setTimeout(() => {
             this.dispatch({ type: "toastExpired" });
         }, TOAST_MS);
@@ -307,20 +318,29 @@ class ExplorerRuntime {
     currentRow() {
         return this.state.rows[this.state.filtered[this.state.cursor] ?? -1];
     }
-    render() {
-        if (this.stopped) {
+    scheduleRender() {
+        if (this.stopped || this.state.suspended || this.renderScheduled) {
             return;
         }
+        this.renderScheduled = true;
+        setImmediate(() => {
+            this.renderScheduled = false;
+            this.renderNow();
+        });
+    }
+    renderNow() {
+        if (this.stopped || this.state.suspended)
+            return;
         const size = this.driver.getSize();
         if (size.cols !== this.state.size.cols || size.rows !== this.state.size.rows) {
             this.state = step(this.state, { type: "resize", cols: size.cols, rows: size.rows }, this.runtimeHandles).state;
         }
-        const nextBuffer = this.state.dirty === REGION_ALL
-            ? new ScreenBuffer(this.state.size.cols, this.state.size.rows)
-            : cloneBuffer(this.previousBuffer);
-        renderExplorer(this.state, nextBuffer);
-        this.driver.write(changesToAnsi(diff(this.previousBuffer, nextBuffer)));
-        this.previousBuffer = nextBuffer;
+        if (this.screen.width !== this.state.size.cols || this.screen.height !== this.state.size.rows)
+            this.screen.resize(this.state.size);
+        renderExplorer({ ...this.state, dirty: REGION_ALL }, this.screen);
+        const frame = this.screen.flush();
+        this.driver.writeFrame(frame);
+        this.trace("frame", { bytes: Buffer.byteLength(frame), cols: this.state.size.cols, rows: this.state.size.rows });
         this.state = { ...this.state, dirty: 0 };
     }
     track(promise) {
@@ -340,8 +360,8 @@ class ExplorerRuntime {
         if (this.toastTimer !== undefined) {
             clearTimeout(this.toastTimer);
         }
-        this.driver.destroy();
-        Promise.resolve()
+        this.driver.stop();
+        Promise.allSettled([...this.pendingEffects])
             .then(() => after?.())
             .then(() => {
             this.settle?.resolve(result);
@@ -353,28 +373,13 @@ class ExplorerRuntime {
     fail(error) {
         if (!this.stopped) {
             this.stopped = true;
-            this.driver.destroy();
+            this.driver.stop();
         }
         this.settle?.reject(error);
     }
-}
-function cloneBuffer(buffer) {
-    const next = new ScreenBuffer(buffer.width, buffer.height);
-    for (let y = 0; y < buffer.height; y += 1) {
-        for (let x = 0; x < buffer.width; x += 1) {
-            const cell = buffer.get(x, y);
-            next.put(x, y, cell.ch, cell.style);
-        }
-    }
-    return next;
-}
-function changesToAnsi(changes) {
-    let output = "";
-    for (const change of changes) {
-        output += `${cursorPositionAnsi(change.x, change.y)}${cellToAnsi(change.cell)}`;
+    trace(type, fields) {
+        if (this.tracePath === undefined || this.tracePath.length === 0)
+            return;
+        appendFileSync(this.tracePath, `${JSON.stringify({ type, timestamp: new Date().toISOString(), ...fields })}\n`);
     }
-    return output;
-}
-function cursorPositionAnsi(x, y) {
-    return `\u001b[${Math.max(1, y + 1)};${Math.max(1, x + 1)}H`;
 }

package/node_modules/toolcraft-design/dist/explorer/runtime.test-helpers.d.ts

@@ -1,50 +1,36 @@
-import type { Cell } from "../dashboard/types.js";
-import type { KeypressEvent, TerminalDriver } from "../dashboard/terminal.js";
+import type { TerminalDriver, TerminalInputEvent } from "../terminal/driver.js";
 export declare class FakeTerminalDriver implements TerminalDriver {
     private cols;
     private rows;
-    readonly keyQueue: KeypressEvent[];
     readonly writes: string[];
-    readonly flushes: Array<Array<{
-        x: number;
-        y: number;
-        cell: Cell;
-    }>>;
-    rawMode: boolean;
-    altScreen: boolean;
-    lineWrap: boolean;
-    cursorVisible: boolean;
-    destroyed: boolean;
-    enterAltScreenCount: number;
-    exitAltScreenCount: number;
-    enterRawModeCount: number;
-    exitRawModeCount: number;
-    private readonly keypressHandlers;
+    started: boolean;
+    startCount: number;
+    stopCount: number;
+    private readonly eventHandlers;
     private readonly resizeHandlers;
     constructor(cols?: number, rows?: number);
     get output(): string;
-    enterRawMode(): void;
-    exitRawMode(): void;
-    enterAltScreen(): void;
-    exitAltScreen(): void;
-    disableLineWrap(): void;
-    enableLineWrap(): void;
-    hideCursor(): void;
-    showCursor(): void;
-    moveTo(x: number, y: number): void;
-    write(text: string): void;
-    flush(changes: Array<{
-        x: number;
-        y: number;
-        cell: Cell;
-    }>): void;
+    get destroyed(): boolean;
+    get altScreen(): boolean;
+    get enterAltScreenCount(): number;
+    start(): void;
+    stop(): void;
+    onEvent(handler: (event: TerminalInputEvent) => void): () => void;
+    onResize(handler: (size: {
+        cols: number;
+        rows: number;
+    }) => void): () => void;
     getSize(): {
         cols: number;
         rows: number;
     };
+    writeFrame(ansi: string): void;
     resize(cols: number, rows: number): void;
-    onResize(handler: () => void): () => void;
-    onKeypress(handler: (key: KeypressEvent) => void): () => void;
-    press(key: KeypressEvent): void;
-    destroy(): void;
+    press(key: {
+        name?: string;
+        ch?: string;
+        ctrl: boolean;
+        meta: boolean;
+        shift: boolean;
+    }): void;
 }

package/node_modules/toolcraft-design/dist/explorer/runtime.test-helpers.js

@@ -1,101 +1,50 @@
 export class FakeTerminalDriver {
     cols;
     rows;
-    keyQueue = [];
     writes = [];
-    flushes = [];
-    rawMode = false;
-    altScreen = false;
-    lineWrap = true;
-    cursorVisible = true;
-    destroyed = false;
-    enterAltScreenCount = 0;
-    exitAltScreenCount = 0;
-    enterRawModeCount = 0;
-    exitRawModeCount = 0;
-    keypressHandlers = new Set();
+    started = false;
+    startCount = 0;
+    stopCount = 0;
+    eventHandlers = new Set();
     resizeHandlers = new Set();
     constructor(cols = 120, rows = 24) {
         this.cols = cols;
         this.rows = rows;
     }
-    get output() {
-        return this.writes.join("");
+    get output() { return this.writes.join(""); }
+    get destroyed() { return !this.started && this.stopCount > 0; }
+    get altScreen() { return this.started; }
+    get enterAltScreenCount() { return this.startCount; }
+    start() { if (!this.started) {
+        this.started = true;
+        this.startCount += 1;
+    } }
+    stop() { if (this.started) {
+        this.started = false;
+        this.stopCount += 1;
+    } }
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => { this.eventHandlers.delete(handler); };
     }
-    enterRawMode() {
-        this.rawMode = true;
-        this.enterRawModeCount += 1;
-    }
-    exitRawMode() {
-        this.rawMode = false;
-        this.exitRawModeCount += 1;
-    }
-    enterAltScreen() {
-        this.altScreen = true;
-        this.enterAltScreenCount += 1;
-    }
-    exitAltScreen() {
-        this.altScreen = false;
-        this.exitAltScreenCount += 1;
-    }
-    disableLineWrap() {
-        this.lineWrap = false;
-    }
-    enableLineWrap() {
-        this.lineWrap = true;
-    }
-    hideCursor() {
-        this.cursorVisible = false;
-    }
-    showCursor() {
-        this.cursorVisible = true;
-    }
-    moveTo(x, y) {
-        this.write(`\u001b[${Math.max(1, y + 1)};${Math.max(1, x + 1)}H`);
-    }
-    write(text) {
-        if (!this.destroyed) {
-            this.writes.push(text);
-        }
-    }
-    flush(changes) {
-        this.flushes.push(changes);
-    }
-    getSize() {
-        return { cols: this.cols, rows: this.rows };
+    onResize(handler) {
+        this.resizeHandlers.add(handler);
+        return () => { this.resizeHandlers.delete(handler); };
     }
+    getSize() { return { cols: this.cols, rows: this.rows }; }
+    writeFrame(ansi) { if (this.started)
+        this.writes.push(ansi); }
     resize(cols, rows) {
         this.cols = cols;
         this.rows = rows;
-        for (const handler of this.resizeHandlers) {
-            handler();
-        }
-    }
-    onResize(handler) {
-        this.resizeHandlers.add(handler);
-        return () => {
-            this.resizeHandlers.delete(handler);
-        };
-    }
-    onKeypress(handler) {
-        this.keypressHandlers.add(handler);
-        return () => {
-            this.keypressHandlers.delete(handler);
-        };
+        for (const handler of this.resizeHandlers)
+            handler(this.getSize());
     }
     press(key) {
-        this.keyQueue.push(key);
-        for (const handler of this.keypressHandlers) {
-            handler(key);
-        }
-    }
-    destroy() {
-        this.destroyed = true;
-        this.rawMode = false;
-        this.lineWrap = true;
-        this.altScreen = false;
-        this.cursorVisible = true;
-        this.keypressHandlers.clear();
-        this.resizeHandlers.clear();
+        if (!this.started)
+            return;
+        const event = { type: "key", name: key.name ?? key.ch ?? "", ch: key.ch, ctrl: key.ctrl, alt: key.meta, shift: key.shift };
+        for (const handler of this.eventHandlers)
+            handler(event);
     }
 }

package/node_modules/toolcraft-design/dist/explorer/state.d.ts

@@ -37,7 +37,9 @@ export interface Action<R> {
     id: string;
     label: string | (() => string);
     key?: string | string[];
+    accelerator?: string;
     predicate?: (ctx: ActionContext<R>) => boolean;
+    visible?: (row: Row) => boolean;
     handler: (ctx: ActionContext<R>) => void | Promise<void>;
     destructive?: boolean;
     primary?: boolean;
@@ -59,6 +61,31 @@ export interface ActionContext<R> {
     toast: (msg: string, tone?: Tone) => void;
     confirm: (prompt: string) => Promise<boolean>;
     exit: (after?: () => void | Promise<void>) => void;
+    activePane?: PaneRuntimeState;
+    inactivePane?: PaneRuntimeState;
+}
+export interface ListPaneConfig {
+    id: string;
+    kind: "list";
+    title: string;
+    rows: () => Promise<Row[]>;
+    emptyHint?: string;
+    multiSelect?: boolean;
+}
+export interface DetailPaneConfig {
+    id: string;
+    kind: "detail";
+    title: string;
+    render: (row: Row | undefined, ctx: DetailCtx) => string | Promise<string>;
+}
+export type PaneConfig = ListPaneConfig | DetailPaneConfig;
+export interface PaneRuntimeState {
+    id: string;
+    title: string;
+    rows: Row[];
+    cursor: number;
+    selected: Set<string>;
+    filter: string;
 }
 export interface ReorderContext {
     refresh: () => Promise<void>;
@@ -66,9 +93,10 @@ export interface ReorderContext {
 }
 export interface ExplorerConfig<R> {
     title: string;
-    rows: () => Promise<Row[]>;
-    refresh?: () => Promise<void>;
-    detail: Detail<R>;
+    panes?: PaneConfig[];
+    rows?: () => Promise<Row[]>;
+    refresh?: () => void | Promise<void>;
+    detail?: Detail<R>;
     actions: Action<R>[];
     reorder?: {
         onReorder: (orderedIds: string[], ctx?: ReorderContext) => void | Promise<void>;
@@ -80,6 +108,11 @@ export interface ExplorerConfig<R> {
     /** Synchronous first paint rows; still refreshed via `rows()` after start. */
     initialRows?: Row[];
 }
+export type NormalizedExplorerConfig<R> = ExplorerConfig<R> & {
+    rows: () => Promise<Row[]>;
+    detail: Detail<R>;
+};
+export declare function normalizeExplorerConfig<R>(config: ExplorerConfig<R>): NormalizedExplorerConfig<R>;
 export declare const REGION_HEADER: number;
 export declare const REGION_LIST: number;
 export declare const REGION_DETAIL: number;
@@ -97,6 +130,7 @@ export interface ExplorerState {
     title: string;
     emptyHint: string;
     rows: Row[];
+    rowsLoading: boolean;
     filtered: number[];
     matchPositions: Map<number, number[]>;
     cursor: number;
@@ -106,6 +140,8 @@ export interface ExplorerState {
     detail: {
         rowId: string | null;
         items: DetailItem[] | null;
+        allItems?: DetailItem[] | null;
+        filter?: string;
         cursor: number;
         scroll: number;
         token: number;
@@ -140,13 +176,19 @@ export interface ExplorerState {
     layout: ExplorerLayoutMode;
     bindings: ResolvedBindings;
     actionState: Map<string, ActionStateEntry>;
+    suspended: boolean;
+    paneDefinitions: Array<{
+        id: string;
+        title: string;
+        kind: "list" | "detail";
+    }>;
 }
 export interface ActionStateEntry {
     available: boolean;
     label: string;
     running?: boolean;
     action?: Action<unknown>;
-    source?: "row" | "detail";
+    source?: "row" | "detail" | "both";
 }
 export declare function createInitialState<R>(config: ExplorerConfig<R>, size: ExplorerSize): ExplorerState;
-export declare function resolveExplorerLayoutMode(cols: number): ExplorerLayoutMode;
+export declare function resolveExplorerLayoutMode(cols: number, rows?: number): ExplorerLayoutMode;