@flyingrobots/bijou-tui 0.10.0 → 1.0.0

package/dist/eventbus.d.ts

@@ -26,21 +26,42 @@
  */
 import type { IOPort } from '@flyingrobots/bijou';
 import type { Cmd, KeyMsg, MouseMsg, ResizeMsg } from './types.js';
-/** Any message the bus can carry — built-in or app-defined. */
+/**
+ * Union of all message types the bus can carry — built-in key, resize,
+ * mouse messages plus any app-defined custom message type.
+ *
+ * @template M - Application-defined custom message type.
+ */
 export type BusMsg<M> = KeyMsg | ResizeMsg | MouseMsg | M;
+/**
+ * Centralized event bus that unifies all input sources into a single
+ * typed event stream for TEA applications.
+ *
+ * @template M - Application-defined custom message type.
+ */
 export interface EventBus<M> {
     /**
      * Subscribe to all events. Returns a dispose function.
      * Multiple subscribers are supported — all receive every event.
+     *
+     * @param handler - Callback invoked for every emitted message.
+     * @returns A disposable that removes this subscription.
      */
     on(handler: (msg: BusMsg<M>) => void): Disposable;
-    /** Emit a message to all subscribers. */
+    /**
+     * Emit a message to all subscribers.
+     *
+     * @param msg - The message to broadcast.
+     */
     emit(msg: BusMsg<M>): void;
     /**
      * Connect keyboard and resize sources from an IOPort.
      * Raw stdin bytes are parsed into KeyMsg automatically.
      * When `options.mouse` is true, SGR mouse sequences are parsed into MouseMsg.
-     * Returns a dispose function that disconnects both.
+     *
+     * @param io - IO port providing raw input and resize events.
+     * @param options - Optional flags (e.g. `{ mouse: true }` to enable mouse input).
+     * @returns A disposable that disconnects both input and resize listeners.
      */
     connectIO(io: IOPort, options?: {
         mouse?: boolean;
@@ -48,25 +69,41 @@ export interface EventBus<M> {
     /**
      * Run a command. The command receives the bus's `emit` function to
      * dispatch intermediate messages during execution. When it resolves:
-     * - QUIT signal → fires onQuit handlers
-     * - Message → emitted to all subscribers
-     * - void/undefined → ignored
+     * - QUIT signal — fires onQuit handlers
+     * - Message — emitted to all subscribers
+     * - void/undefined — ignored
      *
      * Rejected commands are logged to stderr via `console.error`.
+     *
+     * @param cmd - The command to execute.
      */
     runCmd(cmd: Cmd<M>): void;
     /**
      * Register a quit handler. Called when a command resolves to QUIT.
      * Separate from `on()` so the runtime can handle shutdown without
      * the app needing to filter for it.
+     *
+     * @param handler - Callback invoked on quit signal.
+     * @returns A disposable that removes this quit handler.
      */
     onQuit(handler: () => void): Disposable;
     /** Disconnect all sources and remove all subscribers. */
     dispose(): void;
 }
+/** Handle for unsubscribing or disconnecting a resource. */
 interface Disposable {
+    /** Remove the subscription or disconnect the resource. */
     dispose(): void;
 }
+/**
+ * Create a new event bus.
+ *
+ * Returns an {@link EventBus} that manages subscribers, I/O connections,
+ * command execution, and quit signaling for a TEA runtime.
+ *
+ * @template M - Application-defined custom message type.
+ * @returns A new event bus instance.
+ */
 export declare function createEventBus<M>(): EventBus<M>;
 export {};
 //# sourceMappingURL=eventbus.d.ts.map

package/dist/eventbus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eventbus.d.ts","sourceRoot":"","sources":["../src/eventbus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQnE,+DAA+D;AAC/D,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,CAAC,CAAC;AAE1D,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB;;;OAGG;IACH,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,UAAU,CAAC;IAElD,yCAAyC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE3B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,UAAU,CAAC;IAEjE;;;;;;;;OAQG;IACH,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE1B;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,UAAU,CAAC;IAExC,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,UAAU,UAAU;IAClB,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD,wBAAgB,cAAc,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAsG/C"}
+{"version":3,"file":"eventbus.d.ts","sourceRoot":"","sources":["../src/eventbus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQnE;;;;;GAKG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB;;;;;;OAMG;IACH,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,UAAU,CAAC;IAElD;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE3B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,UAAU,CAAC;IAEjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE1B;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,UAAU,CAAC;IAExC,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,4DAA4D;AAC5D,UAAU,UAAU;IAClB,0DAA0D;IAC1D,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAsG/C"}

package/dist/eventbus.js

@@ -29,6 +29,15 @@ import { parseKey, parseMouse } from './keys.js';
 // ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
+/**
+ * Create a new event bus.
+ *
+ * Returns an {@link EventBus} that manages subscribers, I/O connections,
+ * command execution, and quit signaling for a TEA runtime.
+ *
+ * @template M - Application-defined custom message type.
+ * @returns A new event bus instance.
+ */
 export function createEventBus() {
     const subscribers = new Set();
     const quitHandlers = new Set();

package/dist/eventbus.js.map

@@ -1 +1 @@
-{"version":3,"file":"eventbus.js","sourceRoot":"","sources":["../src/eventbus.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"eventbus.js","sourceRoot":"","sources":["../src/eventbus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAiFjD,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,WAAW,GAAG,IAAI,GAAG,EAA4B,CAAC;IACxD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAc,CAAC;IAC3C,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,SAAS,IAAI,CAAC,GAAc;QAC1B,IAAI,QAAQ;YAAE,OAAO;QACrB,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;YAClC,OAAO,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,CAAC,OAAO;YACR,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzB,OAAO;gBACL,OAAO;oBACL,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC9B,CAAC;aACF,CAAC;QACJ,CAAC;QAED,IAAI;QAEJ,SAAS,CAAC,EAAU,EAAE,OAA6B;YACjD,MAAM,YAAY,GAAG,OAAO,EAAE,KAAK,IAAI,KAAK,CAAC;YAE7C,wCAAwC;YACxC,MAAM,WAAW,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,GAAW,EAAE,EAAE;gBAC9C,IAAI,QAAQ;oBAAE,OAAO;gBAErB,oDAAoD;gBACpD,IAAI,YAAY,EAAE,CAAC;oBACjB,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;oBACjC,IAAI,QAAQ,EAAE,CAAC;wBACb,IAAI,CAAC,QAAQ,CAAC,CAAC;wBACf,OAAO;oBACT,CAAC;gBACH,CAAC;gBAED,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;gBAC7B,yDAAyD;gBACzD,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS;oBAAE,OAAO;gBACrC,IAAI,CAAC,MAAM,CAAC,CAAC;YACf,CAAC,CAAC,CAAC;YAEH,gBAAgB;YAChB,MAAM,YAAY,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE;gBACjD,IAAI,QAAQ;oBAAE,OAAO;gBACrB,MAAM,GAAG,GAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;gBACzD,IAAI,CAAC,GAAG,CAAC,CAAC;YACZ,CAAC,CAAC,CAAC;YAEH,MAAM,MAAM,GAAe;gBACzB,OAAO;oBACL,WAAW,CAAC,OAAO,EAAE,CAAC;oBACtB,YAAY,CAAC,OAAO,EAAE,CAAC;gBACzB,CAAC;aACF,CAAC;YACF,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACzB,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,CAAC,GAAW;YAChB,IAAI,QAAQ;gBAAE,OAAO;YACrB,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;gBAC7B,IAAI,QAAQ;oBAAE,OAAO;gBACrB,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;oBACpB,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;wBACnC,OAAO,EAAE,CAAC;oBACZ,CAAC;oBACD,OAAO;gBACT,CAAC;gBACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,IAAI,CAAC,MAAW,CAAC,CAAC;gBACpB,CAAC;YACH,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBACxB,8EAA8E;gBAC9E,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;YACrD,CAAC,CAAC,CAAC;QACL,CAAC;QAED,MAAM,CAAC,OAAO;YACZ,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC1B,OAAO;gBACL,OAAO;oBACL,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC/B,CAAC;aACF,CAAC;QACJ,CAAC;QAED,OAAO;YACL,QAAQ,GAAG,IAAI,CAAC;YAChB,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;gBAC5B,CAAC,CAAC,OAAO,EAAE,CAAC;YACd,CAAC;YACD,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC;YACvB,WAAW,CAAC,KAAK,EAAE,CAAC;YACpB,YAAY,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/file-picker.d.ts

@@ -21,27 +21,46 @@
  */
 import type { IOPort } from '@flyingrobots/bijou';
 import { type KeyMap } from './keybindings.js';
+/** A single entry (file or directory) in the file picker listing. */
 export interface FileEntry {
+    /** Name of the file or directory (without trailing `/`). */
     name: string;
+    /** Whether this entry is a directory. */
     isDirectory: boolean;
 }
+/** Immutable state for the file picker widget. */
 export interface FilePickerState {
+    /** Current working directory being browsed. */
     readonly cwd: string;
+    /** Sorted entries in the current directory. */
     readonly entries: readonly FileEntry[];
+    /** Index of the currently focused entry. */
     readonly focusIndex: number;
+    /** Vertical scroll offset (first visible entry index). */
     readonly scrollY: number;
+    /** Maximum number of visible entries. */
     readonly height: number;
+    /** Optional file extension filter (e.g. `".ts"`). */
     readonly filter?: string;
 }
+/** Options for creating a new file picker state. */
 export interface FilePickerOptions {
+    /** Starting directory path. */
     readonly cwd: string;
+    /** IO port used for directory listing and path joining. */
     readonly io: IOPort;
+    /** Maximum number of visible entries (default: 10). */
     readonly height?: number;
+    /** Optional file extension filter (e.g. `".ts"`). */
     readonly filter?: string;
 }
+/** Options for rendering the file picker view. */
 export interface FilePickerRenderOptions {
+    /** Character(s) shown next to the focused entry (default: `"\u25b8"`). */
     readonly focusIndicator?: string;
+    /** Character(s) shown before directory names (default: `"d"`). */
     readonly dirIndicator?: string;
+    /** Character(s) shown before file names (default: `"-"`). */
     readonly fileIndicator?: string;
 }
 /**
@@ -50,21 +69,50 @@ export interface FilePickerRenderOptions {
  * Reads directory contents via `io.readDir()` and parses entries into
  * directories (trailing `/`) and files. Directories are sorted first,
  * then files, both alphabetically.
+ *
+ * @param options - Starting directory, IO port, height, and optional filter.
+ * @returns Fresh file picker state with focus on the first entry.
  */
 export declare function createFilePickerState(options: FilePickerOptions): FilePickerState;
-/** Move focus to the next entry (wraps around). */
+/**
+ * Move focus to the next entry (wraps around).
+ *
+ * @param state - Current file picker state.
+ * @returns Updated state with focus on the next entry.
+ */
 export declare function fpFocusNext(state: FilePickerState): FilePickerState;
-/** Move focus to the previous entry (wraps around). */
+/**
+ * Move focus to the previous entry (wraps around).
+ *
+ * @param state - Current file picker state.
+ * @returns Updated state with focus on the previous entry.
+ */
 export declare function fpFocusPrev(state: FilePickerState): FilePickerState;
-/** Enter the focused directory, refreshing the entry list. No-op on files. */
+/**
+ * Enter the focused directory, refreshing the entry list. No-op on files.
+ *
+ * @param state - Current file picker state.
+ * @param io - IO port for filesystem access.
+ * @returns Updated state browsing the focused directory, or unchanged if focused on a file.
+ */
 export declare function fpEnter(state: FilePickerState, io: IOPort): FilePickerState;
-/** Navigate to the parent directory. No-op at filesystem root. */
+/**
+ * Navigate to the parent directory. No-op at filesystem root.
+ *
+ * @param state - Current file picker state.
+ * @param io - IO port for filesystem access.
+ * @returns Updated state browsing the parent directory, or unchanged at root.
+ */
 export declare function fpBack(state: FilePickerState, io: IOPort): FilePickerState;
 /**
  * Render the file picker — cwd header followed by the visible entry list.
  *
  * Each entry is prefixed with a focus indicator and a type indicator
  * (directory or file). Directories are suffixed with `/`.
+ *
+ * @param state - Current file picker state.
+ * @param options - Rendering options (focus, dir, and file indicators).
+ * @returns Rendered file picker string with cwd header and entry list.
  */
 export declare function filePicker(state: FilePickerState, options?: FilePickerRenderOptions): string;
 /**
@@ -80,6 +128,10 @@ export declare function filePicker(state: FilePickerState, options?: FilePickerR
  *   quit: { type: 'quit' },
  * });
  * ```
+ *
+ * @template Msg - Application message type dispatched by key bindings.
+ * @param actions - Map of navigation and action messages.
+ * @returns Preconfigured key map with vim-style file picker bindings.
  */
 export declare function filePickerKeyMap<Msg>(actions: {
     focusNext: Msg;

package/dist/file-picker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-picker.d.ts","sourceRoot":"","sources":["../src/file-picker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAM7D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAkDD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CAYjF;AAMD,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CAInE;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CAInE;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,CAe3E;AAED,kEAAkE;AAClE,wBAAgB,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,CAa1E;AAqBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,MAAM,CA0B5F;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE;IAC7C,SAAS,EAAE,GAAG,CAAC;IACf,SAAS,EAAE,GAAG,CAAC;IACf,KAAK,EAAE,GAAG,CAAC;IACX,IAAI,EAAE,GAAG,CAAC;IACV,IAAI,EAAE,GAAG,CAAC;CACX,GAAG,MAAM,CAAC,GAAG,CAAC,CAed"}
+{"version":3,"file":"file-picker.d.ts","sourceRoot":"","sources":["../src/file-picker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAM7D,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAwDD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CAYjF;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CAInE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,CAe3E;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,CAa1E;AA8BD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,MAAM,CA0B5F;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE;IAC7C,SAAS,EAAE,GAAG,CAAC;IACf,SAAS,EAAE,GAAG,CAAC;IACf,KAAK,EAAE,GAAG,CAAC;IACX,IAAI,EAAE,GAAG,CAAC;IACV,IAAI,EAAE,GAAG,CAAC;CACX,GAAG,MAAM,CAAC,GAAG,CAAC,CAed"}

package/dist/file-picker.js

@@ -26,6 +26,11 @@ import { createKeyMap } from './keybindings.js';
 /**
  * Safely read and parse directory entries. Returns `[]` if the directory
  * is unreadable (permissions, missing, etc.) instead of throwing.
+ *
+ * @param io - IO port for filesystem access.
+ * @param cwd - Directory path to read.
+ * @param filter - Optional file extension filter.
+ * @returns Sorted array of file entries, or empty array on error.
  */
 function safeReadEntries(io, cwd, filter) {
     try {
@@ -42,6 +47,7 @@ function safeReadEntries(io, cwd, filter) {
  * @param filter - Optional extension suffix (e.g. `".ts"`) — only files whose
  *                 name ends with this suffix are included. Directories are
  *                 always included regardless of the filter.
+ * @returns Sorted array of file entries (directories first, then files).
  */
 function parseEntries(names, filter) {
     const dirs = [];
@@ -70,6 +76,9 @@ function parseEntries(names, filter) {
  * Reads directory contents via `io.readDir()` and parses entries into
  * directories (trailing `/`) and files. Directories are sorted first,
  * then files, both alphabetically.
+ *
+ * @param options - Starting directory, IO port, height, and optional filter.
+ * @returns Fresh file picker state with focus on the first entry.
  */
 export function createFilePickerState(options) {
     const height = Math.max(1, options.height ?? 10);
@@ -86,21 +95,37 @@ export function createFilePickerState(options) {
 // ---------------------------------------------------------------------------
 // State transformers
 // ---------------------------------------------------------------------------
-/** Move focus to the next entry (wraps around). */
+/**
+ * Move focus to the next entry (wraps around).
+ *
+ * @param state - Current file picker state.
+ * @returns Updated state with focus on the next entry.
+ */
 export function fpFocusNext(state) {
     if (state.entries.length === 0)
         return state;
     const focusIndex = (state.focusIndex + 1) % state.entries.length;
     return { ...state, focusIndex, scrollY: adjustScroll(focusIndex, state.scrollY, state.height, state.entries.length) };
 }
-/** Move focus to the previous entry (wraps around). */
+/**
+ * Move focus to the previous entry (wraps around).
+ *
+ * @param state - Current file picker state.
+ * @returns Updated state with focus on the previous entry.
+ */
 export function fpFocusPrev(state) {
     if (state.entries.length === 0)
         return state;
     const focusIndex = (state.focusIndex - 1 + state.entries.length) % state.entries.length;
     return { ...state, focusIndex, scrollY: adjustScroll(focusIndex, state.scrollY, state.height, state.entries.length) };
 }
-/** Enter the focused directory, refreshing the entry list. No-op on files. */
+/**
+ * Enter the focused directory, refreshing the entry list. No-op on files.
+ *
+ * @param state - Current file picker state.
+ * @param io - IO port for filesystem access.
+ * @returns Updated state browsing the focused directory, or unchanged if focused on a file.
+ */
 export function fpEnter(state, io) {
     if (state.entries.length === 0)
         return state;
@@ -117,7 +142,13 @@ export function fpEnter(state, io) {
         scrollY: 0,
     };
 }
-/** Navigate to the parent directory. No-op at filesystem root. */
+/**
+ * Navigate to the parent directory. No-op at filesystem root.
+ *
+ * @param state - Current file picker state.
+ * @param io - IO port for filesystem access.
+ * @returns Updated state browsing the parent directory, or unchanged at root.
+ */
 export function fpBack(state, io) {
     const newCwd = io.joinPath(state.cwd, '..');
     if (newCwd === state.cwd)
@@ -134,6 +165,15 @@ export function fpBack(state, io) {
 // ---------------------------------------------------------------------------
 // Scroll helper
 // ---------------------------------------------------------------------------
+/**
+ * Clamp scroll position so the focused entry stays within the visible window.
+ *
+ * @param focusIndex - Index of the focused entry.
+ * @param scrollY - Current scroll offset.
+ * @param height - Viewport height in entries.
+ * @param totalItems - Total number of entries.
+ * @returns Adjusted scroll offset.
+ */
 function adjustScroll(focusIndex, scrollY, height, totalItems) {
     let newScrollY = scrollY;
     if (focusIndex < newScrollY) {
@@ -153,6 +193,10 @@ function adjustScroll(focusIndex, scrollY, height, totalItems) {
  *
  * Each entry is prefixed with a focus indicator and a type indicator
  * (directory or file). Directories are suffixed with `/`.
+ *
+ * @param state - Current file picker state.
+ * @param options - Rendering options (focus, dir, and file indicators).
+ * @returns Rendered file picker string with cwd header and entry list.
  */
 export function filePicker(state, options) {
     const indicator = options?.focusIndicator ?? '\u25b8';
@@ -192,6 +236,10 @@ export function filePicker(state, options) {
  *   quit: { type: 'quit' },
  * });
  * ```
+ *
+ * @template Msg - Application message type dispatched by key bindings.
+ * @param actions - Map of navigation and action messages.
+ * @returns Preconfigured key map with vim-style file picker bindings.
  */
 export function filePickerKeyMap(actions) {
     return createKeyMap()

package/dist/file-picker.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-picker.js","sourceRoot":"","sources":["../src/file-picker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-picker.js","sourceRoot":"","sources":["../src/file-picker.ts"],"names":[],"mappings":"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"}

package/dist/flex.d.ts

@@ -12,6 +12,10 @@
  * )
  * ```
  */
+import type { BijouContext, TokenValue } from '@flyingrobots/bijou';
+/**
+ * Configuration for the flex layout container.
+ */
 export interface FlexOptions {
     /** Layout direction. Default: 'row'. */
     readonly direction?: 'row' | 'column';
@@ -21,7 +25,14 @@ export interface FlexOptions {
     readonly height: number;
     /** Gap between children (in the main axis). Default: 0. */
     readonly gap?: number;
+    /** Background token applied to the entire flex container (gap + padding areas). Requires `bg` field on the token. */
+    readonly bgToken?: TokenValue;
+    /** Bijou context for styled output (required for bgToken to take effect). */
+    readonly ctx?: BijouContext;
 }
+/**
+ * Descriptor for a single child within a flex layout.
+ */
 export interface FlexChild {
     /**
      * Content to render. Either a static string, or a function that
@@ -38,6 +49,8 @@ export interface FlexChild {
     readonly maxSize?: number;
     /** Cross-axis alignment. Default: 'start'. */
     readonly align?: 'start' | 'center' | 'end';
+    /** Background token for this child's allocated region. Requires `bg` field on the token and `ctx` on `FlexOptions`. */
+    readonly bgToken?: TokenValue;
 }
 /**
  * Lay out children using flexbox-style rules.
@@ -59,6 +72,10 @@ export interface FlexChild {
  *   { basis: 1, content: statusLine },
  * )
  * ```
+ *
+ * @param options - Layout container configuration (direction, dimensions, gap).
+ * @param children - Child descriptors with content, flex factors, and constraints.
+ * @returns Composed layout string with lines joined by newlines. Empty string if no children.
  */
 export declare function flex(options: FlexOptions, ...children: FlexChild[]): string;
 //# sourceMappingURL=flex.d.ts.map

package/dist/flex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flex.d.ts","sourceRoot":"","sources":["../src/flex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IACvE,kFAAkF;IAClF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;CAC7C;AAoLD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,CAkB3E"}
+{"version":3,"file":"flex.d.ts","sourceRoot":"","sources":["../src/flex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGpE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,qHAAqH;IACrH,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IACvE,kFAAkF;IAClF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC5C,uHAAuH;IACvH,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC/B;AAoPD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,CAmB3E"}