@lovelaces-io/storyteller 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,14 +1,158 @@
-type StoryLevel = "tell" | "warn" | "oops";
-type StoryContextValue = Record<string, unknown> | string;
+/**
+ * Which default audience a storyteller registers.
+ *
+ * - `text` — colorized console output for a person watching
+ * - `ndjson` — one JSON object per line for a program reading
+ */
+type OutputFormat = "text" | "ndjson";
+/**
+ * A level written any of the ways people and agents actually write it.
+ * `report("...", { level: "warn" })` should not be a type error.
+ */
+type LevelInput = StoryLevel | "info" | "information" | "warn" | "warning" | "oops" | "error";
+/**
+ * Resolve any accepted level spelling to a stored level label.
+ *
+ * @param input - A level in any accepted spelling
+ * @returns The canonical StoryLevel, defaulting to Information
+ */
+declare function toStoryLevel(input?: LevelInput): StoryLevel;
+/**
+ * Read an environment variable, tolerating runtimes that have no environment at all.
+ *
+ * @param name - Variable name
+ * @returns The trimmed value, or undefined when unset or unavailable
+ */
+declare function readEnvironmentValue(name: string): string | undefined;
+/**
+ * Resolve the minimum level to deliver, from an explicit option then `STORYTELLER_LEVEL`.
+ *
+ * @param requested - Explicit level, if the caller set one
+ * @returns The threshold level, defaulting to Information (deliver everything)
+ */
+declare function resolveMinimumLevel(requested?: StoryLevel | string): StoryLevel;
+/**
+ * Check whether a level clears the configured minimum.
+ *
+ * @param level - The emission's level
+ * @param minimum - The configured threshold
+ */
+declare function meetsLevel(level: StoryLevel, minimum: StoryLevel): boolean;
+/**
+ * Resolve which default audience to register, from an explicit option then
+ * `STORYTELLER_FORMAT`.
+ *
+ * Deliberately not inferred from whether stdout is a TTY: output that silently
+ * changes shape when a process is piped is a debugging afternoon nobody asked for.
+ *
+ * @param requested - Explicit format, if the caller set one
+ * @returns The format, defaulting to text
+ */
+declare function resolveOutputFormat(requested?: OutputFormat): OutputFormat;
+/**
+ * Resolve whether to colorize, from an explicit option then `STORYTELLER_COLOR`.
+ *
+ * @param requested - Explicit choice, if the caller set one
+ * @returns Whether colors should be used, defaulting to true
+ */
+declare function resolveColors(requested?: boolean): boolean;
+
+/** A value that survives JSON.stringify with no loss and no throwing */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type NormalizeOptions = {
+    /** How many levels deep to descend before replacing the value with a truncation marker */
+    maxDepth?: number;
+    /** How many array entries to keep before truncating */
+    maxArrayLength?: number;
+    /** How many object properties to keep before truncating */
+    maxProperties?: number;
+    /** How many characters of a string to keep before truncating */
+    maxStringLength?: number;
+    /** Property names whose values are replaced with the redaction marker */
+    redactKeys?: string[];
+    /** Set false to keep secret-shaped values as-is */
+    redact?: boolean;
+};
+/** Marker written in place of a value that matched a redacted key name */
+declare const REDACTED = "[redacted]";
+/**
+ * Property names whose values are replaced with {@link REDACTED}.
+ * Matching ignores case and separators, so `apiKey`, `api_key` and `API-KEY` all match.
+ */
+declare const DEFAULT_REDACT_KEYS: string[];
+/**
+ * Convert any value into a JSON-safe structure suitable for a story record.
+ *
+ * Handles the shapes real code actually holds — errors, dates, maps, sets, class
+ * instances, binary buffers, circular references, throwing getters — and never throws,
+ * so a hostile object logged by a caller cannot break the delivery pipeline.
+ *
+ * Data dropped for size is replaced with an explicit `@truncated` marker rather than
+ * disappearing silently, so a consumer can tell the difference between "this was empty"
+ * and "this was too big".
+ *
+ * @param input - Any value
+ * @param options - Depth, size and redaction limits
+ * @returns A value that JSON.stringify can always serialize
+ *
+ * @example
+ * ```ts
+ * normalizeValue({ user: new Map([["id", 1]]), apiKey: "sk-live-abc" });
+ * // { user: { "@type": "Map", entries: { id: 1 } }, apiKey: "[redacted]" }
+ * ```
+ */
+declare function normalizeValue(input: unknown, options?: NormalizeOptions): JsonValue;
+/**
+ * Convert an unknown thrown value into a serializable StoryError,
+ * following the `cause` chain and collecting AggregateError members.
+ *
+ * @param rawError - Any thrown or rejected value
+ * @param options - Depth, size and redaction limits applied to attached data
+ * @returns A StoryError safe to store and serialize
+ */
+declare function normalizeError(rawError: unknown, options?: NormalizeOptions): StoryError;
+
+/** Human-readable level labels stored in story records */
+type StoryLevel = "Information" | "Warning" | "Error";
+/**
+ * A stored context value. Always JSON-safe — whatever the caller passed in has
+ * already been through the normalizer by the time it reaches a record.
+ */
+type StoryContextValue = JsonValue;
+/** Context accepted from callers. Anything goes; the normalizer makes it storable. */
+type StoryContextInput = unknown;
 type StoryError = {
     name?: string;
     message?: string;
     stack?: string;
-    cause?: unknown;
+    cause?: JsonValue;
+    /** Members of an AggregateError */
+    errors?: StoryError[];
+};
+/** Origin as stored on a record */
+type StoryOrigin = {
+    who?: StoryContextValue;
+    what?: StoryContextValue;
+    where?: StoryContextValue;
+};
+/** Origin as accepted from callers */
+type StoryOriginInput = {
+    who?: StoryContextInput;
+    what?: StoryContextInput;
+    where?: StoryContextInput;
 };
 type StoryNote = {
     timestamp: string;
+    /**
+     * Position within the story, assigned when the note is taken. Gap-free from 0.
+     * Optional so records written before sequencing existed still typecheck.
+     */
+    sequence?: number;
     note: string;
+    /** Omitted when the note carries the story's default Information level */
+    level?: StoryLevel;
     who?: StoryContextValue;
     what?: StoryContextValue;
     where?: StoryContextValue;
@@ -18,28 +162,45 @@ type StoryEventBase = {
     timestamp: string;
     level: StoryLevel;
     title: string;
-    origin?: {
-        who?: StoryContextValue;
-        what?: StoryContextValue;
-        where?: StoryContextValue;
-    };
+    /**
+     * Correlates every note emission with the story it belongs to. Always set on
+     * events this library builds; optional so older stored records still typecheck.
+     */
+    storyId?: string;
+    /**
+     * The story this one is a chapter of. Absent on a top-level story.
+     * Following this field reconstructs the tree of a nested run.
+     */
+    parentStoryId?: string;
+    origin?: StoryOrigin;
     notes: StoryNote[];
+    durationMs?: number;
+    /**
+     * How many emissions were dropped for back-pressure while this story was being
+     * collected. Present only when something was actually lost, so the loss shows up
+     * in the record instead of vanishing.
+     */
+    droppedEmissions?: number;
     error?: StoryError;
 };
-type StorySummaryOptions = {
+type ReportOptions = {
     timezone?: string;
     locale?: string;
-    verbosity?: "brief" | "normal" | "full";
-    maxNotes?: number;
+    detail?: "brief" | "normal" | "full";
+    noteLimit?: number;
     showData?: boolean;
-    colorize?: boolean;
+    colors?: boolean;
 };
-type StoryPreviewOptions = StorySummaryOptions & {
+/** @deprecated Use ReportOptions instead */
+type StorySummaryOptions = ReportOptions;
+type PreviewOptions = ReportOptions & {
     title?: string;
     level?: StoryLevel;
     error?: unknown;
 };
-type StorySummaryNote = {
+/** @deprecated Use PreviewOptions instead */
+type StoryPreviewOptions = PreviewOptions;
+type ReportNote = {
     timestamp: string;
     when: string;
     note: string;
@@ -49,34 +210,146 @@ type StorySummaryNote = {
     where?: StoryContextValue;
     error?: StoryError;
 };
-type StorySummaryData = {
+/** @deprecated Use ReportNote instead */
+type StorySummaryNote = ReportNote;
+type StoryReport = {
     title: string;
     level: StoryLevel;
     when: string;
     durationMs?: number;
     duration?: string;
     origin?: StoryEventBase["origin"];
-    notes: StorySummaryNote[];
+    notes: ReportNote[];
     error?: StoryError;
 };
-type StorySummary = {
+/** @deprecated Use StoryReport instead */
+type StorySummaryData = StoryReport;
+type FormattedReport = {
     text: string;
-    data: StorySummaryData;
+    data: StoryReport;
 };
+/** @deprecated Use FormattedReport instead */
+type StorySummary = FormattedReport;
 type StoryEvent = StoryEventBase & {
-    summarize: (options?: StorySummaryOptions) => StorySummary;
+    kind: "story";
+    summarize: (options?: ReportOptions) => FormattedReport;
+};
+/** @deprecated Use StoryEvent — the story-shaped emission */
+type StoryEmission = StoryEvent;
+/** The two things an audience can hear */
+type EmissionKind = "note" | "story";
+/**
+ * A single beat, delivered the moment it happens when narration is live.
+ *
+ * `storyId` and `sequence` are what make streaming lossless: a consumer holding
+ * the beats of a story can order and group them back into the record that
+ * collected narration would have produced.
+ */
+type NoteEmission = StoryNote & {
+    kind: "note";
+    storyId: string;
+    parentStoryId?: string;
+    sequence: number;
+    level: StoryLevel;
+    origin?: StoryOrigin;
 };
+type Emission = NoteEmission | StoryEvent;
 type AudienceMember = {
     name: string;
-    accepts?: (event: StoryEvent) => boolean;
-    hear: (event: StoryEvent) => void | Promise<void>;
+    /**
+     * Which emission kinds this audience wants. Defaults to `["story"]`, so an
+     * audience written before live narration existed keeps hearing only stories.
+     */
+    hears?: EmissionKind[];
+    /**
+     * Declared with method syntax deliberately. TypeScript checks method parameters
+     * bivariantly, so an audience written as `hear: (event: StoryEvent) => void`
+     * still compiles. That would be unsound if such an audience could receive a note
+     * emission — it cannot, because `hears` defaults to stories only.
+     */
+    accepts?(emission: Emission): boolean;
+    hear(emission: Emission): void | Promise<void>;
 };
+/**
+ * How a storyteller narrates.
+ *
+ * - `collected` — beats are buffered and leave as one story record (the default)
+ * - `live` — each beat is emitted as it happens, and the story still lands at the end
+ *
+ * Live narration adds emissions, it never removes them: a consumer that only wants
+ * beats says so with `hears: ["note"]` rather than by silencing the record.
+ */
+type Narration = "collected" | "live";
+/** @deprecated `both` is now the behavior of `live` — beats stream and the story still lands */
+type NarrationInput = Narration | "both";
 type NoteData = {
-    who?: StoryContextValue;
-    what?: StoryContextValue;
-    where?: StoryContextValue;
+    who?: StoryContextInput;
+    what?: StoryContextInput;
+    where?: StoryContextInput;
     error?: unknown;
+    /** Level for this beat alone. Defaults to Information. */
+    level?: LevelInput;
+    /** Emit this beat immediately even when narration is collected */
+    live?: boolean;
+    /** Deliver this beat only to the named audiences */
+    to?: string[];
 };
+type FinishOptions = {
+    /** Defaults to Information */
+    level?: LevelInput;
+    /** The error that ended the story, normalized onto the record */
+    error?: unknown;
+};
+type ChapterOptions = {
+    /** Merged over the parent's origin */
+    origin?: StoryOriginInput;
+    /** Defaults to the parent's setting */
+    narration?: NarrationInput;
+    /** Defaults to the parent's setting */
+    level?: LevelInput;
+    /** Defaults to the parent's handler */
+    onAudienceError?: AudienceErrorHandler;
+    /** Defaults to the parent's bound */
+    maxInFlight?: number;
+};
+type StorytellerOptions = {
+    origin?: StoryOriginInput;
+    audiences?: AudienceMember[];
+    /** Defaults to `STORYTELLER_NARRATION`, then `collected` */
+    narration?: NarrationInput;
+    /**
+     * Which default audience to register: colorized text for a person, NDJSON for a
+     * program. Defaults to `STORYTELLER_FORMAT`, then `text`.
+     */
+    format?: OutputFormat;
+    /**
+     * Share another storyteller's audience registry instead of creating one.
+     * Audiences added to it later reach this storyteller too. When given, no
+     * default audience is registered — the registry already has whatever it has.
+     */
+    audience?: AudienceRegistry;
+    /** The story this one is a chapter of. Set by `chapter()`. */
+    parentStoryId?: string;
+    /**
+     * Drop emissions below this level before they reach any audience.
+     * Defaults to `STORYTELLER_LEVEL`, then Information (deliver everything).
+     */
+    level?: LevelInput;
+    /**
+     * Called when an audience throws or rejects. Without one, a single throttled
+     * warning per audience goes to the console — a logging library that loses
+     * records in silence is worse than one that complains.
+     */
+    onAudienceError?: AudienceErrorHandler;
+    /**
+     * Cap on deliveries in flight to a single audience at once. Live narration is
+     * fire-and-forget, so a slow audience would otherwise grow an unbounded queue.
+     * Past the cap, emissions are dropped and counted on the closing story.
+     */
+    maxInFlight?: number;
+};
+/** Called when an audience member throws or rejects while hearing an emission */
+type AudienceErrorHandler = (error: unknown, member: AudienceMember, emission: Emission) => void;
 /** Manages the set of audience members that receive story events */
 declare class AudienceRegistry {
     private members;
@@ -88,64 +361,277 @@ declare class AudienceRegistry {
     getAll(): AudienceMember[];
     /** Return only the audience members matching the given names */
     getOnly(names: string[]): AudienceMember[];
+    /** Check if an audience member is registered by name */
+    has(name: string): boolean;
+    /** List the names of all registered audience members */
+    names(): string[];
 }
-/** Core logging class that collects timestamped notes and emits them as structured story events */
+/**
+ * Collects timestamped notes and emits them as one structured story — and, when
+ * narration is live, emits each note the moment it is taken.
+ *
+ * @example
+ * ```ts
+ * const story = new Storyteller({ origin: { who: "api-server" }, narration: "live" });
+ * story.report("Request received", { what: { path: "/checkout" } });
+ * story.report("Validated cart");
+ * story.finish("Checkout started");
+ * ```
+ */
 declare class Storyteller {
     readonly audience: AudienceRegistry;
     private readonly origin?;
+    private readonly parentStoryId?;
     private notes;
-    constructor(options?: {
-        origin?: StoryEventBase["origin"];
-        audiences?: AudienceMember[];
-    });
-    /** Add a timestamped note with optional context (who, what, where, error) */
-    note(text: string, data?: NoteData): this;
-    /** Clear all accumulated notes without emitting a story */
+    private narration;
+    private readonly minimumLevel;
+    private readonly onAudienceError;
+    private readonly maxInFlight;
+    /** Deliveries currently awaiting each audience, keyed by audience name */
+    private readonly inFlight;
+    /** Emissions dropped for back-pressure since the current story began */
+    private droppedEmissions;
+    /** Identifies the story currently being collected; regenerated after each telling */
+    private storyId;
+    /** Position of the next note within the current story */
+    private nextSequence;
+    constructor(options?: StorytellerOptions);
+    /**
+     * Switch between collected and live narration at runtime.
+     * Takes effect on the next note; already-buffered notes are not replayed.
+     *
+     * @param narration - `collected` to buffer, `live` to emit each note as it happens
+     * @returns `this` for chaining
+     */
+    narrate(narration: NarrationInput): this;
+    /** The id of the story currently being collected */
+    get currentStoryId(): string;
+    /**
+     * Start a chapter: a child storyteller whose stories are linked back to this
+     * one by `parentStoryId`.
+     *
+     * Real work nests — an agent spawns subtasks, a batch runs per-item operations.
+     * A chapter keeps each of those a complete story in its own right while leaving
+     * the run reconstructable as a tree.
+     *
+     * The child shares this storyteller's audience registry, so audiences added
+     * later reach it too, and inherits narration, level and delivery settings.
+     * Its stories are separate records — a chapter is not folded into the parent's
+     * notes.
+     *
+     * @param options - Origin to merge over the parent's, and any setting to override
+     * @returns A child Storyteller
+     *
+     * @example
+     * ```ts
+     * for (const account of accounts) {
+     *   const chapter = story.chapter({ origin: { what: account.id } });
+     *   chapter.report("Fetching invoices");
+     *   chapter.finish(`Synced ${account.id}`);
+     * }
+     * ```
+     */
+    chapter(options?: ChapterOptions): Storyteller;
+    /**
+     * Report a beat of the current story.
+     *
+     * In collected narration the beat is buffered and leaves with the story. In live
+     * narration it is emitted the moment you call this, so whoever is tuned in sees
+     * the work as it happens.
+     *
+     * Accepts anything, not just a string — pass an error, an API response, a Map, a
+     * class instance — and the value is normalized into a storable shape with the note
+     * text derived from it.
+     *
+     * @param input - What happened: a message, or any value to describe
+     * @param data - Optional context: who did it, what was involved, where it happened, any error
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```ts
+     * story.report("Card charged", { what: { amount: "$42" }, where: "stripe" });
+     * story.report(await response.json());
+     * ```
+     */
+    report(input: unknown, data?: NoteData): this;
+    /** Clear all accumulated notes without emitting a story, and start a new story id */
     reset(): this;
-    /** Generate a formatted summary of current notes without emitting or clearing them */
-    summarize(options?: StoryPreviewOptions): StorySummary;
-    /** Emit a story at the "tell" level (success / informational) */
+    /** Preview the current notes as a formatted report without emitting or clearing them */
+    summarize(options?: PreviewOptions): FormattedReport;
+    /**
+     * Finish the story: emit everything collected so far as one record, and start fresh.
+     *
+     * @param title - What the story was about
+     * @param options - Level, and the error that ended it
+     * @returns A one-shot handle whose `.to()` overrides the audience list — call it
+     *   synchronously, delivery happens on the next microtask
+     *
+     * @example
+     * ```ts
+     * story.finish("Sync complete");
+     * story.finish("Sync failed", { level: "oops", error }).to("db");
+     * ```
+     */
+    finish(title: string, options?: FinishOptions): {
+        to: (...names: string[]) => void;
+    };
+    /** @deprecated Use `finish(title)`. Removed at 1.0. */
     tell(title: string): {
         to: (...names: string[]) => void;
     };
-    /** Emit a story at the "warn" level (something was off) */
+    /** @deprecated Use `finish(title, { level: "warn" })`. Removed at 1.0. */
     warn(title: string): {
         to: (...names: string[]) => void;
     };
-    /** Emit a story at the "oops" level (something broke) with an optional error */
+    /** @deprecated Use `finish(title, { level: "oops", error })`. Removed at 1.0. */
     oops(title: string, error?: unknown): {
         to: (...names: string[]) => void;
     };
+    /** @deprecated Use `report()`. Removed at 1.0. */
+    note(input: unknown, data?: NoteData): this;
+    /** Emit a single note to the audiences listening for notes */
+    private emitNote;
     /** Build a story event and schedule delivery, returning a handle to override the audience list */
     private createDelivery;
-    /** Assemble the story event from current notes and clear notes for the next story */
+    /** Assemble the story event from current notes and start a fresh story */
     private buildEvent;
-    /** Deliver a story event to matching audience members */
+    /** Begin a new story: fresh id, sequence back to zero */
+    private startNewStory;
+    /** Deliver an emission to the audience members listening for its kind */
     private deliver;
+    /** Run an audience's accepts() without letting a throw from it lose the emission */
+    private acceptsSafely;
+    /**
+     * Hand an emission to one audience, keeping its failures and its slowness
+     * contained: a throw is reported rather than swallowed, and a backlog is dropped
+     * rather than grown without limit.
+     */
+    private hearSafely;
+    /** Report an audience failure without ever letting it reach caller code */
+    private handleAudienceError;
 }
-/** Generate a formatted, human-readable summary from a story event */
-declare function summarizeStory(story: StoryEventBase, options?: StorySummaryOptions): StorySummary;
+
+/**
+ * Format a story event into a human-readable report with optional colors.
+ *
+ * @param story - The story event to format
+ * @param options - Formatting options (timezone, locale, detail level, colors)
+ * @returns A FormattedReport with both text (for display) and data (structured)
+ *
+ * @example
+ * ```ts
+ * const report = formatStory(event, { colors: false, detail: "brief" });
+ * console.log(report.text);
+ * ```
+ */
+declare function formatStory(story: StoryEventBase, options?: ReportOptions): FormattedReport;
+/** Convert milliseconds into a human-readable duration string */
+declare function formatDuration(milliseconds: number): string;
+/** @deprecated Use formatStory instead */
+declare const summarizeStory: typeof formatStory;
 
 type StorytellerSharedOptions = {
-    origin?: StoryEventBase["origin"];
+    origin?: StoryOriginInput;
+    narration?: NarrationInput;
     reset?: boolean;
 };
-/** Return a shared singleton Storyteller instance for cross-component or cross-service logging */
+/**
+ * Get or create a shared Storyteller instance for cross-component logging.
+ * First call creates the instance; subsequent calls return the same one.
+ *
+ * @param options.origin - Origin context for the shared instance
+ * @param options.reset - Create a fresh instance (useful in tests)
+ *
+ * @example
+ * ```ts
+ * // Same instance everywhere in your app
+ * const story = useStoryteller({ origin: { who: "worker" } });
+ * ```
+ */
 declare function useStoryteller(options?: StorytellerSharedOptions): Storyteller;
 
-/** Create an audience that logs stories to the browser console with color-coded grouped output */
-declare function consoleAudience(): AudienceMember;
+type ConsoleAudienceOptions = {
+    /** Set false to strip ANSI colors from live note lines. Defaults to `STORYTELLER_COLOR`. */
+    colors?: boolean;
+};
+/**
+ * Create an audience that prints to the console: one compact line per note when
+ * narration is live, and a color-coded grouped record when a story is told.
+ *
+ * Registered by default on every Storyteller instance. It listens for notes as well
+ * as stories, so switching a storyteller to live narration shows something immediately
+ * without registering anything extra.
+ *
+ * @param options - Rendering options for live note lines
+ *
+ * @example
+ * ```ts
+ * // Already included — but you can re-add after removing:
+ * story.audience.add(consoleAudience());
+ * ```
+ */
+declare function consoleAudience(options?: ConsoleAudienceOptions): AudienceMember;
 
-/** Create an audience that persists warn and oops stories to a database via the provided insert function */
+/**
+ * Create an audience that stores warn and oops stories via your insert function.
+ * Tell-level events are filtered out to reduce noise — only warnings and errors are persisted.
+ *
+ * Hears stories only. Live notes are not persisted: the story record already contains
+ * every note, so storing both would double-write the same content.
+ *
+ * Note: if the insert function throws, the error is silently caught by the delivery
+ * pipeline (Promise.allSettled). Wrap your insert with try/catch to handle failures.
+ *
+ * @param insert - Function that receives the story event and stores it
+ *
+ * @example
+ * ```ts
+ * story.audience.add(
+ *   dbAudience(async (event) => {
+ *     await db.insert("story_logs", event);
+ *   })
+ * );
+ * ```
+ */
 declare function dbAudience(insert: (event: StoryEvent) => Promise<void> | void): AudienceMember;
 
+/** Anything that can take a line of text — a Node stream, or your own sink */
+type LineWriter = {
+    write: (chunk: string) => unknown;
+};
+type NdjsonAudienceOptions = {
+    /** Where lines go. Defaults to stdout in Node, console.log elsewhere. */
+    stream?: LineWriter;
+    /** Register under a different name, e.g. to run two streams at once */
+    name?: string;
+    /** Minimum level to write. Defaults to `STORYTELLER_LEVEL`, then everything. */
+    level?: StoryLevel;
+};
+/**
+ * Create an audience that writes one JSON object per line — every note and every
+ * story, nothing else on the channel.
+ *
+ * This is the format to give a program: a log shipper, `jq`, or an agent reading
+ * another process's output. Each line parses on its own, and `storyId` plus
+ * `sequence` let a reader group streamed notes back into their story.
+ *
+ * @param options - Stream, name and level threshold
+ *
+ * @example
+ * ```ts
+ * story.audience.remove("console");
+ * story.audience.add(ndjsonAudience({ stream: process.stderr }));
+ * ```
+ */
+declare function ndjsonAudience(options?: NdjsonAudienceOptions): AudienceMember;
+
 type StoryReportOptions = {
     timezone?: string;
     locale?: string;
-    verbosity?: "brief" | "normal" | "full";
-    maxNotesPerStory?: number;
+    detail?: "brief" | "normal" | "full";
+    noteLimit?: number;
     showData?: boolean;
-    colorize?: boolean;
+    colors?: boolean;
 };
 /** Generate a formatted report from an array of story events, grouped by day */
 declare function writeStoryReport(stories: StoryEventBase[], options?: StoryReportOptions): string;
@@ -162,14 +648,20 @@ declare const ANSI: {
 /** Map a story level to its corresponding ANSI terminal color */
 declare function getLevelColor(level: StoryLevel): string;
 /** Format an origin context into a human-readable path like "app / page / component" */
-declare function formatOrigin(origin?: StoryEventBase["origin"]): string | undefined;
-/** Colorize JSON output, dimming the notes section for visual hierarchy */
-declare function colorizeJsonSections(json: string, colors: {
-    base: string;
-    notes: string;
-    reset: string;
-}): string[];
-/** Count the net bracket depth change in a line (opening brackets minus closing brackets) */
-declare function countBrackets(line: string): number;
+declare function formatOrigin(origin?: StoryOrigin): string | undefined;
+/**
+ * Condense a note's context into a short inline summary for one-line output.
+ * The full values are always available on the story record and the NDJSON stream,
+ * so this can afford to be lossy in favor of staying readable.
+ *
+ * @param note - The note's context fields
+ * @returns A brace-wrapped summary, or undefined when there is no context
+ */
+declare function summarizeContext(note: {
+    note?: string;
+    what?: JsonValue;
+    where?: JsonValue;
+    error?: StoryError;
+}): string | undefined;
 
-export { ANSI, type AudienceMember, type StoryContextValue, type StoryError, type StoryEvent, type StoryEventBase, type StoryLevel, type StoryNote, type StoryPreviewOptions, type StoryReportOptions, type StorySummary, type StorySummaryData, type StorySummaryNote, type StorySummaryOptions, Storyteller, colorizeJsonSections, consoleAudience, countBrackets, dbAudience, formatOrigin, getLevelColor, summarizeStory, useStoryteller, writeStoryReport };
+export { ANSI, type AudienceErrorHandler, type AudienceMember, AudienceRegistry, type ChapterOptions, type ConsoleAudienceOptions, DEFAULT_REDACT_KEYS, type Emission, type EmissionKind, type FinishOptions, type FormattedReport, type JsonValue, type LevelInput, type LineWriter, type Narration, type NarrationInput, type NdjsonAudienceOptions, type NormalizeOptions, type NoteData, type NoteEmission, type OutputFormat, type PreviewOptions, REDACTED, type ReportNote, type ReportOptions, type StoryContextInput, type StoryContextValue, type StoryEmission, type StoryError, type StoryEvent, type StoryEventBase, type StoryLevel, type StoryNote, type StoryOrigin, type StoryOriginInput, type StoryPreviewOptions, type StoryReport, type StoryReportOptions, type StorySummary, type StorySummaryData, type StorySummaryNote, type StorySummaryOptions, Storyteller, type StorytellerOptions, consoleAudience, dbAudience, formatDuration, formatOrigin, formatStory, getLevelColor, meetsLevel, ndjsonAudience, normalizeError, normalizeValue, readEnvironmentValue, resolveColors, resolveMinimumLevel, resolveOutputFormat, summarizeContext, summarizeStory, toStoryLevel, useStoryteller, writeStoryReport };