@fnndsc/brasa 0.12.0 → 0.14.0

package/dist/core/promptContext.js

@@ -13,6 +13,19 @@
 import { session } from '../session/index.js';
 import { context_getSingle } from '@fnndsc/salsa';
 import { procCache_get, } from '@fnndsc/cumin';
+/**
+ * Snapshots the live process-index counts, cheaply: no network, just the
+ * cache's own registers. The daemon's telemetry heartbeat reads this.
+ *
+ * @returns The jobs and feeds the index currently holds.
+ */
+export function procIndex_snapshot() {
+    const cache = procCache_get();
+    return {
+        jobs: cache.warmupProgress_get().loaded,
+        feeds: cache.feedScopeCounts_get('').total,
+    };
+}
 /**
  * Builds the current session's prompt context.
  *
@@ -32,6 +45,14 @@ export async function sessionPromptContext_build(options = {}) {
     const procWarmup = warmupRaw.active || lifecycle.state === 'reconciling' || lifecycle.state === 'failed'
         ? { loaded: warmupRaw.loaded, total: warmupRaw.total, restored, state: procState }
         : undefined;
+    // Steady-state counts stay visible after warm-up settles: warmup progress
+    // retains its final figures, and the feed map is the live index.
+    const procIndex = warmupRaw.loaded > 0 || procCache_get().feedScopeCounts_get(context.user ?? '').total > 0
+        ? {
+            jobs: warmupRaw.loaded,
+            feeds: procCache_get().feedScopeCounts_get(context.user ?? '').total,
+        }
+        : undefined;
     return {
         user: isOffline ? 'disconnected' : (context.user ?? 'disconnected'),
         uri: isOffline ? 'no-cube' : (context.URL ?? 'no-cube'),
@@ -41,6 +62,7 @@ export async function sessionPromptContext_build(options = {}) {
         lastExitCode: options.lastExitCode ?? 0,
         lastCommandDurationMs: options.lastCommandDurationMs ?? 0,
         procWarmup,
+        procIndex,
     };
 }
 //# sourceMappingURL=promptContext.js.map

package/dist/core/promptContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"promptContext.js","sourceRoot":"","sources":["../../src/core/promptContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAEL,aAAa,GAKd,MAAM,eAAe,CAAC;AAgCvB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,UAAuC,EAAE;IAEzC,MAAM,OAAO,GAAkB,MAAM,iBAAiB,EAAE,CAAC;IACzD,MAAM,GAAG,GAAW,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;IAC3C,MAAM,SAAS,GAAY,OAAO,CAAC,OAAO,CAAC;IAE3C,MAAM,SAAS,GAAuB,aAAa,EAAE,CAAC,kBAAkB,EAAE,CAAC;IAC3E,MAAM,SAAS,GAAuB,aAAa,EAAE,CAAC,aAAa,EAAE,CAAC;IACtE,MAAM,QAAQ,GAAY,SAAS,CAAC,YAAY,KAAK,SAAS,CAAC;IAC/D,MAAM,SAAS,GAAoB,SAAS,CAAC,KAAK,KAAK,QAAQ;QAC7D,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;IACjC,MAAM,UAAU,GACd,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,KAAK,KAAK,aAAa,IAAI,SAAS,CAAC,KAAK,KAAK,QAAQ;QACnF,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE;QAClF,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO;QACL,IAAI,EAAmB,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,cAAc,CAAC;QACpF,GAAG,EAAoB,SAAS,CAAC,CAAC,CAAC,SAAS,CAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,IAAK,SAAS,CAAC;QAC/E,GAAG,EAAoB,SAAS,CAAC,CAAC,CAAC,GAAG,CAAY,CAAC,CAAC,GAAG;QACvD,UAAU,EAAa,OAAO,CAAC,UAAU,IAAI,IAAI;QACjD,YAAY,EAAW,OAAO,CAAC,gBAAgB,EAAE;QACjD,YAAY,EAAW,OAAO,CAAC,YAAY,IAAI,CAAC;QAChD,qBAAqB,EAAE,OAAO,CAAC,qBAAqB,IAAI,CAAC;QACzD,UAAU;KACX,CAAC;AACJ,CAAC"}
+{"version":3,"file":"promptContext.js","sourceRoot":"","sources":["../../src/core/promptContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAEL,aAAa,GAKd,MAAM,eAAe,CAAC;AAkCvB;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAG,aAAa,EAAE,CAAC;IAC9B,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,kBAAkB,EAAE,CAAC,MAAM;QACvC,KAAK,EAAE,KAAK,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC,KAAK;KAC3C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,UAAuC,EAAE;IAEzC,MAAM,OAAO,GAAkB,MAAM,iBAAiB,EAAE,CAAC;IACzD,MAAM,GAAG,GAAW,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;IAC3C,MAAM,SAAS,GAAY,OAAO,CAAC,OAAO,CAAC;IAE3C,MAAM,SAAS,GAAuB,aAAa,EAAE,CAAC,kBAAkB,EAAE,CAAC;IAC3E,MAAM,SAAS,GAAuB,aAAa,EAAE,CAAC,aAAa,EAAE,CAAC;IACtE,MAAM,QAAQ,GAAY,SAAS,CAAC,YAAY,KAAK,SAAS,CAAC;IAC/D,MAAM,SAAS,GAAoB,SAAS,CAAC,KAAK,KAAK,QAAQ;QAC7D,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;IACjC,MAAM,UAAU,GACd,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,KAAK,KAAK,aAAa,IAAI,SAAS,CAAC,KAAK,KAAK,QAAQ;QACnF,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE;QAClF,CAAC,CAAC,SAAS,CAAC;IAChB,0EAA0E;IAC1E,iEAAiE;IACjE,MAAM,SAAS,GACb,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,aAAa,EAAE,CAAC,mBAAmB,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC;QACvF,CAAC,CAAC;YACE,IAAI,EAAE,SAAS,CAAC,MAAM;YACtB,KAAK,EAAE,aAAa,EAAE,CAAC,mBAAmB,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK;SACrE;QACH,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO;QACL,IAAI,EAAmB,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,cAAc,CAAC;QACpF,GAAG,EAAoB,SAAS,CAAC,CAAC,CAAC,SAAS,CAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,IAAK,SAAS,CAAC;QAC/E,GAAG,EAAoB,SAAS,CAAC,CAAC,CAAC,GAAG,CAAY,CAAC,CAAC,GAAG;QACvD,UAAU,EAAa,OAAO,CAAC,UAAU,IAAI,IAAI;QACjD,YAAY,EAAW,OAAO,CAAC,gBAAgB,EAAE;QACjD,YAAY,EAAW,OAAO,CAAC,YAAY,IAAI,CAAC;QAChD,qBAAqB,EAAE,OAAO,CAAC,qBAAqB,IAAI,CAAC;QACzD,UAAU;QACV,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/core/surface.d.ts

@@ -40,6 +40,20 @@
  * @property shellCommands - The surface can run a `!`-prefixed host-shell
  *   command on its own machine. A daemon delegates this capability to the
  *   command's originating surface and never launches the process itself.
+ * @property fileDelivery - The surface can put a file where its operator can
+ *   reach it. What that means is the surface's business — a path on the local
+ *   CLI's disk, a path on a remote CLI's client machine, a saved file in a
+ *   browser — but never the daemon host's disk.
+ * @property engineFilesystem - The surface's operator sits at the same
+ *   filesystem the engine runs on, so a path the engine resolves is a path
+ *   they can open. True only for an in-process local shell. When false, a
+ *   builtin that would write to disk must deliver through the surface instead,
+ *   because the engine's disk is somebody else's machine.
+ * @property localFilesystem - The surface can put many files into a directory
+ *   structure of its own. True for any shell, remote included; false for a
+ *   browser, which has no directory to fill and can only accept files one at a
+ *   time. It answers a different question from `engineFilesystem`: not *whose*
+ *   disk, but whether there is one at all.
  */
 export interface SurfaceCapabilities {
     hiddenInput: boolean;
@@ -47,6 +61,9 @@ export interface SurfaceCapabilities {
     tty: boolean;
     pipeSegments: boolean;
     shellCommands: boolean;
+    fileDelivery: boolean;
+    engineFilesystem: boolean;
+    localFilesystem: boolean;
 }
 /**
  * A request to prompt the user for a line of input.
@@ -70,6 +87,8 @@ export interface LocalEditRequest {
     content: string;
     extension?: string;
 }
+export type { FileDeliverRequest, FileDeliverResult } from '@fnndsc/menu';
+import type { FileDeliverRequest, FileDeliverResult } from '@fnndsc/menu';
 /**
  * The outcome of a local edit.
  *
@@ -129,6 +148,19 @@ export interface Surface {
      *   capability.
      */
     localEdit(request: LocalEditRequest): Promise<LocalEditResult>;
+    /**
+     * Places one file where this surface's operator can reach it.
+     *
+     * The mechanics are the surface's: a write to the resolved path for the
+     * local CLI, a write on the client machine for a remote CLI, a saved file
+     * for a browser. A daemon never writes to its own disk on a surface's
+     * behalf, for the same reason it never spawns a shell there.
+     *
+     * @param request - What to deliver and where the operator asked for it.
+     * @returns Where it landed and how large it was.
+     * @throws {CapabilityError} When the surface lacks `fileDelivery`.
+     */
+    fileDeliver(request: FileDeliverRequest): Promise<FileDeliverResult>;
 }
 /**
  * Raised when a builtin requests an interaction the attached surface cannot
@@ -161,6 +193,8 @@ export declare class HeadlessSurface implements Surface {
     shellCommand(_command: string): Promise<number>;
     /** @inheritdoc */
     localEdit(_request: LocalEditRequest): Promise<LocalEditResult>;
+    /** @inheritdoc */
+    fileDeliver(_request: FileDeliverRequest): Promise<FileDeliverResult>;
 }
 /**
  * Returns the currently installed surface.

package/dist/core/surface.js

@@ -55,6 +55,9 @@ export class HeadlessSurface {
         tty: false,
         pipeSegments: false,
         shellCommands: false,
+        fileDelivery: false,
+        engineFilesystem: false,
+        localFilesystem: false,
     };
     /** @inheritdoc */
     prompt(_request) {
@@ -72,6 +75,10 @@ export class HeadlessSurface {
     localEdit(_request) {
         throw new CapabilityError('localEdit', 'This surface cannot open a local editor.');
     }
+    /** @inheritdoc */
+    fileDeliver(_request) {
+        throw new CapabilityError('fileDelivery', 'This surface cannot receive a file.');
+    }
 }
 /** The active surface. Defaults to headless until a host installs one. */
 let activeSurface = new HeadlessSurface();

package/dist/core/surface.js.map

@@ -1 +1 @@
-{"version":3,"file":"surface.js","sourceRoot":"","sources":["../../src/core/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAsHH;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,mDAAmD;IACnC,UAAU,CAA4B;IAEtD;;;OAGG;IACH,YAAY,UAAqC,EAAE,OAAe;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAC1B,kBAAkB;IACF,YAAY,GAAwB;QAClD,WAAW,EAAE,KAAK;QAClB,SAAS,EAAE,KAAK;QAChB,GAAG,EAAE,KAAK;QACV,YAAY,EAAE,KAAK;QACnB,aAAa,EAAE,KAAK;KACrB,CAAC;IAEF,kBAAkB;IACX,MAAM,CAAC,QAAuB;QACnC,MAAM,IAAI,eAAe,CAAC,KAAK,EAAE,uCAAuC,CAAC,CAAC;IAC5E,CAAC;IAED,kBAAkB;IACX,WAAW,CAAC,QAAgB,EAAE,MAAc;QACjD,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,4CAA4C,CAAC,CAAC;IAC1F,CAAC;IAED,kBAAkB;IACX,YAAY,CAAC,QAAgB;QAClC,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,yCAAyC,CAAC,CAAC;IACxF,CAAC;IAED,kBAAkB;IACX,SAAS,CAAC,QAA0B;QACzC,MAAM,IAAI,eAAe,CAAC,WAAW,EAAE,0CAA0C,CAAC,CAAC;IACrF,CAAC;CACF;AAED,0EAA0E;AAC1E,IAAI,aAAa,GAAY,IAAI,eAAe,EAAE,CAAC;AAEnD;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,MAAM,QAAQ,GAAY,aAAa,CAAC;IACxC,aAAa,GAAG,OAAO,CAAC;IACxB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAqC,EACrC,OAAe;IAEf,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../../src/core/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA+JH;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,mDAAmD;IACnC,UAAU,CAA4B;IAEtD;;;OAGG;IACH,YAAY,UAAqC,EAAE,OAAe;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAC1B,kBAAkB;IACF,YAAY,GAAwB;QAClD,WAAW,EAAE,KAAK;QAClB,SAAS,EAAE,KAAK;QAChB,GAAG,EAAE,KAAK;QACV,YAAY,EAAE,KAAK;QACnB,aAAa,EAAE,KAAK;QACpB,YAAY,EAAE,KAAK;QACnB,gBAAgB,EAAE,KAAK;QACvB,eAAe,EAAE,KAAK;KACvB,CAAC;IAEF,kBAAkB;IACX,MAAM,CAAC,QAAuB;QACnC,MAAM,IAAI,eAAe,CAAC,KAAK,EAAE,uCAAuC,CAAC,CAAC;IAC5E,CAAC;IAED,kBAAkB;IACX,WAAW,CAAC,QAAgB,EAAE,MAAc;QACjD,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,4CAA4C,CAAC,CAAC;IAC1F,CAAC;IAED,kBAAkB;IACX,YAAY,CAAC,QAAgB;QAClC,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,yCAAyC,CAAC,CAAC;IACxF,CAAC;IAED,kBAAkB;IACX,SAAS,CAAC,QAA0B;QACzC,MAAM,IAAI,eAAe,CAAC,WAAW,EAAE,0CAA0C,CAAC,CAAC;IACrF,CAAC;IAED,kBAAkB;IACX,WAAW,CAAC,QAA4B;QAC7C,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,qCAAqC,CAAC,CAAC;IACnF,CAAC;CACF;AAED,0EAA0E;AAC1E,IAAI,aAAa,GAAY,IAAI,eAAe,EAAE,CAAC;AAEnD;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,MAAM,QAAQ,GAAY,aAAa,CAAC;IACxC,aAAa,GAAG,OAAO,CAAC;IACxB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAqC,EACrC,OAAe;IAEf,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export * from './builtins/index.js';
 export * from './config/storeConfig.js';
 export * from './lib/vfs/vfs.js';
 export * from './lib/spinner.js';
+export * from './logo/brain.js';
 export * from './lib/prefetch.js';
 export * from './lib/parser.js';
 export * from './lib/pipe.js';

package/dist/index.js

@@ -27,6 +27,7 @@ export * from './builtins/index.js';
 export * from './config/storeConfig.js';
 export * from './lib/vfs/vfs.js';
 export * from './lib/spinner.js';
+export * from './logo/brain.js';
 export * from './lib/prefetch.js';
 export * from './lib/parser.js';
 export * from './lib/pipe.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,kBAAkB,CAAC;AACjC,iEAAiE;AACjE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,kBAAkB,CAAC;AACjC,iEAAiE;AACjE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC"}

package/dist/lib/spinner.d.ts

@@ -1,23 +1,62 @@
 /**
- * @file Terminal spinner utility for long-running operations.
+ * @file Indeterminate-progress announcer for long-running work.
+ *
+ * A command that cannot say how much work remains still owes the operator the
+ * fact that work is under way. This announces that fact as a structured
+ * progress event; it does not draw it. Frame choreography — the braille cycle,
+ * the erase-line, the elapsed counter — belongs to whichever renderer is
+ * attached, because a browser, a terminal and a log each express waiting
+ * differently and none of them should have to recover meaning from cursor
+ * movement.
+ *
+ * The class keeps its former name and call signature so its many callers need
+ * no change, but it is no longer a terminal utility: it emits `operation:
+ * 'task'` with `kind: 'inspection'`, and the surface decides the rest.
  *
  * @module
  */
 /**
- * Terminal spinner indicating progress of async work.
+ * Announces indeterminate progress for async work.
+ *
+ * `start` opens an announcement, `updateMessage` revises its label, and `stop`
+ * closes it. Only state changes cross the wire: a spin that lasts a minute
+ * costs two events, not one per animation frame.
  */
 export declare class Spinner {
-    private interval;
     private message;
-    private frames;
-    private frameIndex;
     private spinnerActive;
-    private startTime;
-    private showTiming;
+    /**
+     * @param initialMessage - Label used when `start` is called without one.
+     */
     constructor(initialMessage?: string);
-    start(message?: string, showTiming?: boolean): void;
-    stop(clearLine?: boolean): void;
+    /**
+     * Opens an indeterminate-progress announcement.
+     *
+     * @param message - Label describing the work; defaults to the last label set.
+     * @param _showTiming - Retained for call-site compatibility. Elapsed time is
+     *   now the renderer's to measure and display, since only the renderer knows
+     *   whether it can show a live counter at all.
+     */
+    start(message?: string, _showTiming?: boolean): void;
+    /**
+     * Closes the announcement.
+     *
+     * @param _clearLine - Retained for call-site compatibility. Whether closing
+     *   erases anything is a rendering decision.
+     */
+    stop(_clearLine?: boolean): void;
+    /**
+     * Revises the label of an open announcement.
+     *
+     * @param newMessage - The label to show from now on.
+     */
     updateMessage(newMessage: string): void;
+    /**
+     * Emits one progress event for the current label.
+     *
+     * @param phase - The lifecycle phase this event reports.
+     */
+    private progress_emit;
 }
 declare const globalSpinner: Spinner;
 export { globalSpinner as spinner };

package/dist/lib/spinner.js

@@ -1,69 +1,89 @@
 /**
- * @file Terminal spinner utility for long-running operations.
+ * @file Indeterminate-progress announcer for long-running work.
+ *
+ * A command that cannot say how much work remains still owes the operator the
+ * fact that work is under way. This announces that fact as a structured
+ * progress event; it does not draw it. Frame choreography — the braille cycle,
+ * the erase-line, the elapsed counter — belongs to whichever renderer is
+ * attached, because a browser, a terminal and a log each express waiting
+ * differently and none of them should have to recover meaning from cursor
+ * movement.
+ *
+ * The class keeps its former name and call signature so its many callers need
+ * no change, but it is no longer a terminal utility: it emits `operation:
+ * 'task'` with `kind: 'inspection'`, and the surface decides the rest.
  *
  * @module
  */
-import chalk from 'chalk';
 import { sink_get } from '../core/sink.js';
 /**
- * Terminal spinner indicating progress of async work.
+ * Announces indeterminate progress for async work.
+ *
+ * `start` opens an announcement, `updateMessage` revises its label, and `stop`
+ * closes it. Only state changes cross the wire: a spin that lasts a minute
+ * costs two events, not one per animation frame.
  */
 export class Spinner {
-    interval = null;
     message = '';
-    frames = ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"];
-    frameIndex = 0;
     spinnerActive = false;
-    startTime = 0;
-    showTiming = false;
+    /**
+     * @param initialMessage - Label used when `start` is called without one.
+     */
     constructor(initialMessage = 'Loading...') {
         this.message = initialMessage;
     }
-    start(message, showTiming = false) {
-        // Do not start spinner if not in a TTY (e.g. piped output)
-        if (!process.stdout.isTTY) {
-            return;
-        }
+    /**
+     * Opens an indeterminate-progress announcement.
+     *
+     * @param message - Label describing the work; defaults to the last label set.
+     * @param _showTiming - Retained for call-site compatibility. Elapsed time is
+     *   now the renderer's to measure and display, since only the renderer knows
+     *   whether it can show a live counter at all.
+     */
+    start(message, _showTiming = false) {
         if (this.spinnerActive) {
-            this.stop(); // Stop any existing spinner
+            this.stop();
         }
-        this.message = message || this.message;
+        this.message = message ?? this.message;
         this.spinnerActive = true;
-        this.frameIndex = 0;
-        this.showTiming = showTiming;
-        this.startTime = Date.now();
-        // Hide cursor
-        sink_get().status_write('\x1B[?25l');
-        this.interval = setInterval(() => {
-            const frame = this.frames[this.frameIndex = (this.frameIndex + 1) % this.frames.length];
-            let displayMessage = this.message;
-            // Add timing if enabled
-            if (this.showTiming) {
-                const elapsedSeconds = ((Date.now() - this.startTime) / 1000).toFixed(1);
-                displayMessage = `${this.message} (${elapsedSeconds}s)`;
-            }
-            // Note: We use chalk.gray for the message to match the existing "Fetching..." style.
-            // \x1b[K erases to end-of-line so a shorter message never leaves the
-            // tail of a longer previous one behind.
-            sink_get().status_write(`\r\x1b[K${chalk.bgBlack.cyanBright.bold(frame)} ${chalk.gray(displayMessage)}`);
-        }, 80);
+        this.progress_emit('working');
     }
-    stop(clearLine = true) {
-        if (this.interval) {
-            clearInterval(this.interval);
-            this.interval = null;
-        }
-        if (this.spinnerActive) {
-            if (clearLine) {
-                sink_get().status_write('\r\x1b[K'); // Clear line
-            }
-            // Show cursor
-            sink_get().status_write('\x1B[?25h');
-            this.spinnerActive = false;
+    /**
+     * Closes the announcement.
+     *
+     * @param _clearLine - Retained for call-site compatibility. Whether closing
+     *   erases anything is a rendering decision.
+     */
+    stop(_clearLine = true) {
+        if (!this.spinnerActive) {
+            return;
         }
+        this.spinnerActive = false;
+        this.progress_emit('complete');
     }
+    /**
+     * Revises the label of an open announcement.
+     *
+     * @param newMessage - The label to show from now on.
+     */
     updateMessage(newMessage) {
         this.message = newMessage;
+        if (this.spinnerActive) {
+            this.progress_emit('working');
+        }
+    }
+    /**
+     * Emits one progress event for the current label.
+     *
+     * @param phase - The lifecycle phase this event reports.
+     */
+    progress_emit(phase) {
+        sink_get().progress_write({
+            operation: 'task',
+            kind: 'inspection',
+            phase,
+            label: this.message,
+        });
     }
 }
 const globalSpinner = new Spinner();

package/dist/lib/spinner.js.map

@@ -1 +1 @@
-{"version":3,"file":"spinner.js","sourceRoot":"","sources":["../../src/lib/spinner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"spinner.js","sourceRoot":"","sources":["../../src/lib/spinner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,OAAO,OAAO;IACV,OAAO,GAAW,EAAE,CAAC;IACrB,aAAa,GAAY,KAAK,CAAC;IAEvC;;OAEG;IACH,YAAY,iBAAyB,YAAY;QAC/C,IAAI,CAAC,OAAO,GAAG,cAAc,CAAC;IAChC,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,OAAgB,EAAE,cAAuB,KAAK;QACzD,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC;QACvC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACI,IAAI,CAAC,aAAsB,IAAI;QACpC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC3B,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACI,aAAa,CAAC,UAAkB;QACrC,IAAI,CAAC,OAAO,GAAG,UAAU,CAAC;QAC1B,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,aAAa,CAAC,KAA6B;QACjD,QAAQ,EAAE,CAAC,cAAc,CAAC;YACxB,SAAS,EAAE,MAAM;YACjB,IAAI,EAAE,YAAY;YAClB,KAAK;YACL,KAAK,EAAE,IAAI,CAAC,OAAO;SACpB,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,aAAa,GAAY,IAAI,OAAO,EAAE,CAAC;AAC7C,OAAO,EAAE,aAAa,IAAI,OAAO,EAAE,CAAC"}

package/dist/logo/brain.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Renders the ASCII logo as an array of lines.
+ *
+ * @param colorize - Whether to apply color.
+ * @param reverse - Whether to reverse the gradient.
+ * @returns The rendered logo lines.
+ */
+export declare function logo_linesRender(colorize: boolean, reverse?: boolean): string[];
+/**
+ * Renders a single frame of the brain activity animation, where the core brain
+ * structure retains its original hue'd color gradient, and only the inner spaces
+ * (stylized nodes) pulse, grow, and fade physically as spatial blooms.
+ *
+ * @param frameIndex - The index of the animation frame.
+ * @param isStaticEndState - If true, renders the final steady state where holes are blank.
+ * @returns Array of rendered lines with color codes.
+ */
+export declare function logo_frameRender(frameIndex: number, isStaticEndState?: boolean): string[];
+/**
+ * The number of terminal rows one rendered frame occupies.
+ *
+ * @returns The frame height in rows.
+ */
+export declare function logoRows_count(): number;
+/**
+ * The number of terminal columns the widest rendered line occupies,
+ * including the two-column indent every frame line carries.
+ *
+ * @returns The frame width in columns.
+ */
+export declare function logoColumns_count(): number;