omkit 0.0.1

package/dist/core/action.d.ts

@@ -0,0 +1,105 @@
+import type { Logger } from "./log-collector/LogsCollector.ts";
+import { type Emitter, type EventHandler } from "./events.ts";
+import { type Proc } from "./process.ts";
+/** An action that declares no events. */
+export type NoEvents = Record<never, never>;
+/** A value an action's `exec` may return: a result, or a promise of one. */
+export type Awaitable<T> = T | Promise<T>;
+/**
+ * Lifecycle events the framework emits for every action — on top of whatever it
+ * declares via `.emits<…>()`. They make key moments first-class signals (no
+ * log-scraping) and give a uniform sequencing hook.
+ */
+export interface SystemEvents<Result> {
+    /** The action published its imperative handle via `ctx.attach` (fires once). */
+    attached: void;
+    /** The run resolved; payload is its result. */
+    done: Result;
+    /** The run rejected; payload is the thrown error. */
+    error: unknown;
+}
+/** The full event map a constructed instance exposes: the declared events plus the system ones. */
+export type InstanceEvents<Events extends object, Result> = Events & SystemEvents<Result>;
+/** System services the pipeline injects into every action when it runs. */
+export interface SystemGlobal {
+    /** A logger bound to this action — feeds it directly or via `proc`. */
+    readonly logs: Logger;
+    /** The run's abort signal — aborted on teardown/cancel; honor it to stop early. */
+    readonly signal: AbortSignal;
+}
+/** What an action's implementation receives: the system bag, plus `emit`, `attach`, and `proc`. */
+export interface ActionContext<Events extends object, Handle = void> extends SystemGlobal {
+    /** Emit one of this action's declared events (also pushed to the global log). */
+    readonly emit: Emitter<Events>["emit"];
+    /** Publish this action's imperative handle, resolving its instance's `.ref`. */
+    readonly attach: (handle: Handle) => void;
+    /**
+     * Spawn child processes bound to this action: their output streams into this
+     * action's log and they're killed on teardown. The built-in source; a custom
+     * one (e.g. CDP) follows the same pattern over `logs`/`signal`.
+     */
+    readonly proc: Proc;
+}
+/** A constructed-but-not-yet-run action: what calling an `Action` produces. */
+export interface ActionInstance<Result = unknown, Events extends object = NoEvents, Handle = void> {
+    readonly name: string;
+    readonly args: readonly unknown[];
+    /** Runs the action with the captured args and the injected system services. */
+    readonly start: (system: SystemGlobal) => Promise<Result>;
+    /**
+     * Resolves with the handle the action attached via `ctx.attach` (set once). If
+     * the action settles *without* attaching, this never hangs: it resolves
+     * (`undefined` for the default `void` handle) on success, or rejects with the
+     * action's error on failure.
+     */
+    readonly ref: Promise<Handle>;
+    /** Subscribe to a declared or system event (`done`/`error`) with a handler. */
+    on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
+    /**
+     * A promise for the next occurrence of an event: resolves with its payload —
+     * or rejects if the action settles first (`error`, or `done` without the
+     * event), so an awaiter never hangs. Use {@link on} for ongoing/handler
+     * subscriptions; `once` is the awaitable, one-value form.
+     */
+    once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K]>;
+}
+/**
+ * Any constructed instance, whatever its result, events, or handle. The launch
+ * surface ({@link ActionInstance}-takers like `run` and `Run.run`) accepts this
+ * so handle-bearing actions — those declaring `.ref<H>()` — can be launched: the
+ * bare `ActionInstance` pins the handle to `void`, so an instance whose `ref` is
+ * a `Promise<Page>` (not `Promise<void>`) would otherwise be rejected. `unknown`
+ * for result/handle and `object` for events admit every concrete instance while
+ * still excluding non-instances.
+ */
+export type AnyActionInstance = ActionInstance<unknown, object, unknown>;
+/** A callable produced by `action`: invoking it builds an {@link ActionInstance}. */
+export interface Action<Args extends unknown[], Result, Events extends object = NoEvents, Handle = void> {
+    (...args: Args): ActionInstance<Result, Events, Handle>;
+    readonly actionName: string;
+}
+/** Intermediate step from `action(name)`: declare events/handle, then provide the impl. */
+export interface ActionBuilder<Events extends object, Handle = void> {
+    /** Declare the typed event map this action emits. */
+    emits<E extends object>(): ActionBuilder<E, Handle>;
+    /** Declare the imperative handle this action exposes (resolved via `instance.ref`). */
+    ref<H>(): ActionBuilder<Events, H>;
+    /** Provide the implementation. `ctx` carries `logs`, `signal`, `emit`, and `attach`. */
+    run<Args extends unknown[], Result>(exec: (ctx: ActionContext<Events, Handle>, ...args: Args) => Awaitable<Result>): Action<Args, Result, Events, Handle>;
+}
+/**
+ * Defines an action. Always returns a builder; provide the implementation via
+ * `.run(…)`, optionally after declaring events and/or a handle:
+ *
+ *   action("Build").run(async (ctx, opts) => { … })       // no declared events / handle
+ *   action("Watch")                                       // typed events + handle
+ *     .emits<{ create: string }>()
+ *     .ref<{ rescan(): void }>()
+ *     .run((ctx, opts) => { ctx.emit(…); ctx.attach(…); … })
+ *
+ * `.run(…)` yields a callable that, when invoked, constructs an
+ * {@link ActionInstance} (deferred — the run executes it). Instances expose
+ * chainable `.on` / `.once` (declared events plus `done`/`error`); the attached
+ * handle is awaited via `instance.ref`.
+ */
+export declare function action(name: string): ActionBuilder<NoEvents, void>;

package/dist/core/action.js

@@ -0,0 +1,133 @@
+import { events } from "./events.js";
+import { createProc } from "./process.js";
+/** A promise paired with its settlers, for the set-once handle. */
+const deferred = () => {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+};
+/**
+ * A promise for the next emit of `key`. It races the event against the
+ * instance's terminal events: if the action errors first it rejects with that
+ * error, and if it completes (`done`) without ever emitting `key` it rejects too
+ * — so an awaiter can never hang. A retained snapshot resolves it immediately.
+ */
+const awaitEvent = (emitter, name, key) => new Promise((resolve, reject) => {
+    const offs = [];
+    let settled = false;
+    // First of [the event | error | done] to fire wins; the rest are unsubscribed.
+    const settle = (act) => {
+        if (settled)
+            return;
+        settled = true;
+        for (const off of offs)
+            off();
+        act();
+    };
+    // listenOnce is keyed by E; the system keys (error/done) are always present
+    // on an instance's event map, so reach them through a loosened view.
+    const listen = emitter.listenOnce;
+    offs.push(listen(key, (payload) => settle(() => resolve(payload))));
+    if (key !== "error") {
+        offs.push(listen("error", (err) => settle(() => reject(err))));
+    }
+    if (key !== "done") {
+        offs.push(listen("done", () => settle(() => reject(new Error(`${name}: settled before "${String(key)}"`)))));
+    }
+    // A retained snapshot fires a listen synchronously during registration; if
+    // that already settled us, drop any listeners registered afterwards.
+    if (settled)
+        for (const off of offs)
+            off();
+});
+/** Assembles an {@link Action} from a name and its implementation. */
+const build = (name, exec) => {
+    const create = (...args) => {
+        // The emitter covers declared + system events; `ctx.emit` is narrowed to the
+        // declared ones, while the framework emits done/error through the same bus.
+        const emitter = events(name);
+        const emit = emitter.emit;
+        // Loosely typed for the framework's own emits (sidesteps EmitArgs for void results).
+        const systemEmit = emitter.emit;
+        // The handle lives on the instance as a set-once promise: `attach` resolves
+        // it, `instance.ref` awaits it. A second attach is a no-op (promise settled).
+        // If the action settles without ever attaching, `start` below settles it too
+        // (resolve on success, reject on error) so `ref` can't hang.
+        const handle = deferred();
+        // Attaching is a one-time lifecycle moment: resolve `ref` and emit `attached`
+        // (the *fact* the action became controllable — not the handle, which is just
+        // functions). Guarded so a second attach neither re-emits nor re-resolves.
+        let attached = false;
+        const attach = (value) => {
+            if (attached)
+                return;
+            attached = true;
+            handle.resolve(value);
+            systemEmit("attached");
+        };
+        // Most actions have a `void` handle and no one awaits `ref`; mark the promise
+        // handled so a settle-time rejection on such an instance doesn't surface as an
+        // unhandled rejection. Real awaiters of `ref` still receive the rejection.
+        void handle.promise.catch(() => { });
+        const instance = {
+            name,
+            args,
+            ref: handle.promise,
+            start: (system) => 
+            // `Promise.resolve().then` normalizes a sync result and routes a sync
+            // throw to the `error` path, so exec may be sync or async.
+            Promise.resolve()
+                .then(() => exec({ ...system, emit, attach, proc: createProc(system.logs, system.signal) }, ...args))
+                .then((result) => {
+                systemEmit("done", result);
+                // Settle `ref` if the action finished without attaching, so awaiters
+                // resolve (with `undefined` for the default void handle) rather than
+                // hang. Idempotent — a no-op when a handle was already attached.
+                handle.resolve(undefined);
+                return result;
+            }, (error) => {
+                systemEmit("error", error);
+                // The action failed, so its handle will never arrive — reject `ref`
+                // with the same error instead of leaving awaiters hung. No-op if a
+                // handle was already attached before the failure.
+                handle.reject(error);
+                throw error;
+            }),
+            on(key, handler) {
+                emitter.listen(key, handler);
+            },
+            once(key) {
+                return awaitEvent(emitter, name, key);
+            },
+        };
+        return instance;
+    };
+    return Object.assign(create, { actionName: name });
+};
+const builder = (name) => ({
+    emits: () => builder(name),
+    ref: () => builder(name),
+    run: (exec) => build(name, exec),
+});
+/**
+ * Defines an action. Always returns a builder; provide the implementation via
+ * `.run(…)`, optionally after declaring events and/or a handle:
+ *
+ *   action("Build").run(async (ctx, opts) => { … })       // no declared events / handle
+ *   action("Watch")                                       // typed events + handle
+ *     .emits<{ create: string }>()
+ *     .ref<{ rescan(): void }>()
+ *     .run((ctx, opts) => { ctx.emit(…); ctx.attach(…); … })
+ *
+ * `.run(…)` yields a callable that, when invoked, constructs an
+ * {@link ActionInstance} (deferred — the run executes it). Instances expose
+ * chainable `.on` / `.once` (declared events plus `done`/`error`); the attached
+ * handle is awaited via `instance.ref`.
+ */
+export function action(name) {
+    return builder(name);
+}

package/dist/core/events.d.ts

@@ -0,0 +1,23 @@
+/** Passed to every handler so it can tell a replayed snapshot from a live emit. */
+export interface EventMeta {
+    /** True when called with the retained last value on subscribe; false for a live emit. */
+    readonly isSnapshot: boolean;
+}
+export type EventHandler<P> = (payload: P, meta: EventMeta) => void;
+/** No payload arg for `void` events, a required one otherwise. */
+type EmitArgs<P> = [P] extends [void] ? [] : [payload: P];
+/**
+ * A typed pub/sub keyed by an event map (`{ key: payload }`). It snapshots the
+ * last payload per key, so a late `listen`/`listenOnce` is replayed that value
+ * immediately (with `isSnapshot: true`) before receiving live emits.
+ */
+export interface Emitter<Events extends object> {
+    /** Emit `key`'s payload to current listeners and retain it as the snapshot. */
+    emit<K extends keyof Events>(key: K, ...args: EmitArgs<Events[K]>): void;
+    /** Subscribe to `key`. Fires immediately with the snapshot if one exists. Returns an unsubscribe. */
+    listen<K extends keyof Events>(key: K, handler: EventHandler<Events[K]>): () => void;
+    /** Like {@link Emitter.listen} but auto-unsubscribes after the first delivery (snapshot counts). */
+    listenOnce<K extends keyof Events>(key: K, handler: EventHandler<Events[K]>): () => void;
+}
+export declare const events: <Events extends object>(namespace?: string) => Emitter<Events>;
+export {};

package/dist/core/events.js

@@ -0,0 +1,61 @@
+import { log } from "./log-collector/global.js";
+import { captureSnapshot } from "./output.js";
+export const events = (namespace) => {
+    const handlers = new Map();
+    const snapshots = new Map();
+    const emit = (key, ...args) => {
+        const payload = args[0];
+        snapshots.set(key, payload);
+        // Every emit also lands in the global log, so events share the timeline with
+        // process output and end up in the drained log file. Fields are `·`-delimited
+        // — namespace (the emitting action) · key · payload. String payloads show
+        // inline; richer payloads are no longer dropped — they're written to a
+        // snapshot file and linked (`→ <path>`), so the durable record keeps them.
+        const fields = [namespace, String(key)];
+        if (typeof payload === "string") {
+            fields.push(payload);
+        }
+        else if (payload !== undefined) {
+            const name = `event-${[namespace, String(key)].filter(Boolean).join("-")}`;
+            fields.push(`→ ${captureSnapshot(name, payload).rel}`);
+        }
+        log.append({
+            source: "event",
+            level: "event",
+            message: fields.filter(Boolean).join(" · "),
+        });
+        const set = handlers.get(key);
+        if (!set)
+            return;
+        // Copy so a handler unsubscribing (or listenOnce) mid-emit doesn't disturb iteration.
+        for (const handler of [...set])
+            handler(payload, { isSnapshot: false });
+    };
+    const listen = (key, handler) => {
+        let set = handlers.get(key);
+        if (!set) {
+            set = new Set();
+            handlers.set(key, set);
+        }
+        set.add(handler);
+        // Snapshot on subscribe, if one has ever been emitted for this key.
+        if (snapshots.has(key))
+            handler(snapshots.get(key), { isSnapshot: true });
+        return () => {
+            set.delete(handler);
+        };
+    };
+    const listenOnce = (key, handler) => {
+        // A retained snapshot satisfies "once" immediately — deliver and we're done.
+        if (snapshots.has(key)) {
+            handler(snapshots.get(key), { isSnapshot: true });
+            return () => { };
+        }
+        const off = listen(key, (payload, meta) => {
+            off();
+            handler(payload, meta);
+        });
+        return off;
+    };
+    return { emit, listen, listenOnce };
+};

package/dist/core/helpers/AsyncQueue.d.ts

@@ -0,0 +1,13 @@
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    private readonly items;
+    private readonly resolvers;
+    private closed;
+    push(item: T): void;
+    /**
+     * Ends the queue: any parked reader resolves `{ done: true }` immediately, and
+     * once already-buffered items are drained, future reads do too. Idempotent.
+     */
+    close(): void;
+    private next;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/core/helpers/AsyncQueue.js

@@ -0,0 +1,50 @@
+export class AsyncQueue {
+    items = [];
+    resolvers = [];
+    closed = false;
+    push(item) {
+        if (this.closed)
+            return;
+        const resolver = this.resolvers.shift();
+        if (resolver) {
+            resolver({
+                done: false,
+                value: item,
+            });
+            return;
+        }
+        this.items.push(item);
+    }
+    /**
+     * Ends the queue: any parked reader resolves `{ done: true }` immediately, and
+     * once already-buffered items are drained, future reads do too. Idempotent.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Unblock everyone parked — nothing more is coming.
+        for (const resolve of this.resolvers.splice(0))
+            resolve({ done: true, value: undefined });
+    }
+    next() {
+        const item = this.items.shift();
+        if (item !== undefined) {
+            return Promise.resolve({
+                done: false,
+                value: item,
+            });
+        }
+        // Drained and closed → the iteration is over.
+        if (this.closed)
+            return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve) => {
+            this.resolvers.push(resolve);
+        });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.next(),
+        };
+    }
+}

package/dist/core/log-collector/LogsCollector.d.ts

@@ -0,0 +1,63 @@
+export interface LogEntry {
+    sequence: number;
+    timestamp: number;
+    /**
+     * Who emitted this line — an action/proc name, or `"event"`/`"run"`/`"snapshot"`.
+     * Retained so the structured log can be filtered and correlated by origin.
+     */
+    source: string;
+    level: string;
+    message: string;
+}
+/** Input to a logger. `source` drives the header line and is retained on the entry. */
+export interface LogInput {
+    source: string;
+    level: string;
+    message: string;
+}
+export interface SubscribeOptions {
+    /**
+     * Replay the buffered history before live entries, so a late subscriber sees
+     * everything logged so far. Default: false (live entries only).
+     */
+    replay?: boolean;
+}
+/**
+ * What actions and the `proc` primitive log into: a raw append-only store. It
+ * keeps no presentation — grouping headers and indentation are applied at read
+ * time by the renderer (see `render.ts`), so every entry stays raw and queryable.
+ */
+export interface Logger {
+    /** Streams a raw text/byte source into the log, split into lines. */
+    attach(stream: AsyncIterable<unknown>, source: string, level: string): void;
+    /** Appends a single entry. */
+    append(entry: LogInput): void;
+    /** Subscribes to entries, optionally replaying history first. */
+    subscribe(options?: SubscribeOptions): AsyncIterable<LogEntry>;
+}
+export declare class LogsCollector implements Logger {
+    private sequence;
+    private readonly history;
+    private readonly subscribers;
+    private ended;
+    /**
+     * Streams a raw text/byte source (e.g. a child process's stdout) into the
+     * collector: splits it into lines and appends each under the given
+     * `source`/`level`. Partial lines are buffered across chunks and a non-empty
+     * trailing fragment is flushed when the stream ends.
+     */
+    attach(stream: AsyncIterable<unknown>, source: string, level: string): void;
+    /** Raw store: records the line verbatim, source included; presentation is the renderer's job. */
+    append(entry: LogInput): void;
+    /**
+     * Bind the run's abort signal: when it aborts (teardown), every subscription
+     * ends — each parked or future `for await` returns — so subscribers don't each
+     * have to watch the signal. The collector *is* the world's log and the signal
+     * is the world ending; the log closes with it.
+     */
+    endOn(signal: AbortSignal): void;
+    /** EOF for readers: end every live subscription and refuse to register new ones. */
+    private closeAll;
+    subscribe({ replay }?: SubscribeOptions): AsyncIterable<LogEntry>;
+    snapshot(): readonly LogEntry[];
+}

package/dist/core/log-collector/LogsCollector.js

@@ -0,0 +1,110 @@
+import { AsyncQueue } from "../helpers/AsyncQueue.js";
+export class LogsCollector {
+    sequence = 0;
+    history = [];
+    subscribers = new Set();
+    // Set once the bound signal aborts: the log has reached EOF for readers.
+    ended = false;
+    /**
+     * Streams a raw text/byte source (e.g. a child process's stdout) into the
+     * collector: splits it into lines and appends each under the given
+     * `source`/`level`. Partial lines are buffered across chunks and a non-empty
+     * trailing fragment is flushed when the stream ends.
+     */
+    attach(stream, source, level) {
+        void splitLines(stream, (message) => this.append({ source, level, message }));
+    }
+    /** Raw store: records the line verbatim, source included; presentation is the renderer's job. */
+    append(entry) {
+        const log = {
+            source: entry.source,
+            level: entry.level,
+            message: entry.message,
+            sequence: ++this.sequence,
+            timestamp: Date.now(),
+        };
+        this.history.push(log);
+        for (const subscriber of this.subscribers) {
+            // push the log into the queue for every subscriber to receive
+            subscriber.push(log);
+        }
+    }
+    /**
+     * Bind the run's abort signal: when it aborts (teardown), every subscription
+     * ends — each parked or future `for await` returns — so subscribers don't each
+     * have to watch the signal. The collector *is* the world's log and the signal
+     * is the world ending; the log closes with it.
+     */
+    endOn(signal) {
+        if (signal.aborted)
+            this.closeAll();
+        else
+            signal.addEventListener("abort", () => this.closeAll(), { once: true });
+    }
+    /** EOF for readers: end every live subscription and refuse to register new ones. */
+    closeAll() {
+        this.ended = true;
+        for (const queue of this.subscribers)
+            queue.close();
+        this.subscribers.clear();
+    }
+    subscribe({ replay = false } = {}) {
+        // create a log queue for the new subscriber
+        const queue = new AsyncQueue();
+        // Optionally replay buffered history before live entries. Synchronous, so no
+        // append can interleave between the replay and registration — a late
+        // subscriber sees every entry, with no gap and no duplicate.
+        if (replay)
+            for (const entry of this.history)
+                queue.push(entry);
+        // If the run has already ended, this subscription is EOF after the replay —
+        // don't register it for entries that will never come. Otherwise, fan it in.
+        if (this.ended)
+            queue.close();
+        else
+            this.subscribers.add(queue);
+        const { subscribers } = this;
+        // logs queue for the current subscriber
+        const inner = queue[Symbol.asyncIterator]();
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    // iterates the subscriber's log queue
+                    next: () => inner.next(),
+                    // Unsubscribe on early exit (break/return), so a consumer that stops
+                    // reading (e.g. waitForLog on a match) doesn't leave a dead queue that
+                    // append keeps pushing into forever.
+                    return: () => {
+                        subscribers.delete(queue);
+                        queue.close();
+                        return Promise.resolve({ done: true, value: undefined });
+                    },
+                };
+            },
+        };
+    }
+    snapshot() {
+        return this.history;
+    }
+}
+/**
+ * Splits a byte/string stream into lines, calling `onLine` for each. Partial
+ * lines are buffered across chunks and a non-empty trailing fragment is flushed
+ * when the stream ends.
+ */
+async function splitLines(stream, onLine) {
+    let buffer = "";
+    for await (const chunk of stream) {
+        buffer += String(chunk);
+        let newline;
+        while ((newline = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, newline).replace(/\r$/, "");
+            buffer = buffer.slice(newline + 1);
+            if (line)
+                onLine(line);
+        }
+    }
+    const tail = buffer.replace(/\r$/, "");
+    if (tail)
+        onLine(tail);
+}

package/dist/core/log-collector/global.d.ts

@@ -0,0 +1,7 @@
+import { LogsCollector } from "./LogsCollector.ts";
+/**
+ * The process-wide log. One per process: pipelines log into it and drain it, and
+ * the event bus pushes an entry here on every `emit`. Created separately from any
+ * pipeline so code that runs before/around a pipeline (like a bus) can reach it.
+ */
+export declare const log: LogsCollector;

package/dist/core/log-collector/global.js

@@ -0,0 +1,7 @@
+import { LogsCollector } from "./LogsCollector.js";
+/**
+ * The process-wide log. One per process: pipelines log into it and drain it, and
+ * the event bus pushes an entry here on every `emit`. Created separately from any
+ * pipeline so code that runs before/around a pipeline (like a bus) can reach it.
+ */
+export const log = new LogsCollector();

package/dist/core/log-collector/render.d.ts

@@ -0,0 +1,57 @@
+import type { LogEntry } from "./LogsCollector.ts";
+/**
+ * Builds a stateful renderer that turns raw {@link LogEntry} records into the
+ * pretty, grouped text form. Presentation lives here and nowhere else: the
+ * collector stores raw entries; `writeLog` and `drain` each create a renderer and
+ * feed it the entry stream in order.
+ *
+ * Grouping is decided against the *single merged stream* (the renderer's own
+ * `lastSource`), not per-producer — so interleaved concurrent sources re-header
+ * correctly, which the old per-child grouping got wrong. A milestone line breaks
+ * the current group, so the next action line re-headers.
+ */
+export declare const createRenderer: () => ((entry: LogEntry) => string);
+/** Lines of a collapsed run shown inline before the pointer. */
+export declare const COLLAPSE_HEAD = 5;
+/** Only runs *longer than* this collapse, so a trigger always hides a meaningful amount. */
+export declare const COLLAPSE_THRESHOLD = 15;
+/** A run set aside for collapsing: its source and every output line, in order. */
+export interface CollapsedRun {
+    readonly source: string;
+    readonly lines: readonly string[];
+}
+/**
+ * One unit of batch-rendered output: either a ready-to-write text `line`
+ * (identical to {@link createRenderer}'s output for that entry) or a
+ * `collapsed` run the caller must off-load and render via {@link renderCollapsed}.
+ */
+export type DisplayItem = {
+    kind: "line";
+    text: string;
+} | {
+    kind: "collapsed";
+    run: CollapsedRun;
+};
+/** Tunes {@link segmentForFile}. Defaults to {@link COLLAPSE_HEAD}/{@link COLLAPSE_THRESHOLD}. */
+export interface SegmentOptions {
+    head?: number;
+    threshold?: number;
+}
+/**
+ * Segments a full, ordered entry list into {@link DisplayItem}s. Milestones and
+ * runs no longer than `threshold` become `line` items byte-identical to
+ * {@link createRenderer}; a run longer than `threshold` becomes a single
+ * `collapsed` item carrying every line of the run. Pure — no filesystem, no
+ * snapshot writing.
+ */
+export declare const segmentForFile: (entries: readonly LogEntry[], { threshold }?: SegmentOptions) => DisplayItem[];
+/**
+ * Renders a {@link CollapsedRun} as its `head` lines under the `▸ <source>`
+ * header, then a single indented `📎` pointer line to the off-loaded snapshot at
+ * `rel` reporting how many lines were hidden. Pure — `rel` is supplied by the
+ * caller after it writes the file.
+ */
+export declare const renderCollapsed: (run: CollapsedRun, { head, rel }: {
+    head: number;
+    rel: string;
+}) => string;