@jangts/agent-core 0.1.1 → 0.2.0

package/dist/esm/kits/knowledge/sections.js

@@ -1,4 +1,11 @@
-/** Paired, nestable anchors are one text adapter. Other sources supply the same document contract directly. */
+/**
+ * Paired, nestable anchors are one text adapter. Other sources supply the same document
+ * contract directly.
+ *
+ * @param input - Document identity, revision, optional locale and the anchored text.
+ * @returns A document whose parts alternate text strings and section objects.
+ * @throws TypeError For an unmatched closing anchor or an anchor left open at the end.
+ */
 export function parseKnowledgeDocument(input) {
     const parts = [];
     const stack = [];
@@ -24,6 +31,14 @@ export function parseKnowledgeDocument(input) {
     parts.push(input.text.slice(offset));
     return { id: input.id, revision: input.revision, locale: input.locale, parts };
 }
+/**
+ * Deep-copy and freeze a document while indexing its sections by id.
+ *
+ * @param document - Declared document, possibly sharing arrays or containing cycles.
+ * @returns The frozen document plus a map from section id to its frozen section.
+ * @throws TypeError For a missing identity or parts array, a sparse or cyclic tree, a blank
+ *   section id, or a duplicate section id.
+ */
 export function compileKnowledgeDocument(document) {
     if (!document.id?.trim() || !document.revision?.trim() || !Array.isArray(document.parts))
         throw new TypeError('Invalid knowledge document');
@@ -35,7 +50,7 @@ export function compileKnowledgeDocument(document) {
         ancestors.add(parts);
         // Visit empty array slots too: a sparse tree is not valid knowledge, and
         // must not share a serialized cache identity with an explicit null part.
-        const result = Array.from(parts, part => {
+        const result = Array.from(parts, (part) => {
             if (typeof part === 'string')
                 return part;
             if (!part || typeof part.id !== 'string' || !part.id.trim() || sections.has(part.id))
@@ -49,9 +64,23 @@ export function compileKnowledgeDocument(document) {
         ancestors.delete(parts);
         return Object.freeze(result);
     }
-    const value = Object.freeze({ id: document.id, revision: document.revision, locale: document.locale, parts: copy(document.parts) });
+    const value = Object.freeze({
+        id: document.id,
+        revision: document.revision,
+        locale: document.locale,
+        parts: copy(document.parts),
+    });
     return { document: value, sections };
 }
+/**
+ * Flatten parts into text.
+ *
+ * @param parts - Document parts; nested sections are traversed in order.
+ * @param subtree - When false, nested section text is skipped and only top-level text remains.
+ * @returns Concatenated text with separators left to the caller.
+ */
 export function knowledgeText(parts, subtree = true) {
-    return parts.map(part => typeof part === 'string' ? part : subtree ? knowledgeText(part.parts) : '').join('');
+    return parts
+        .map((part) => (typeof part === 'string' ? part : subtree ? knowledgeText(part.parts) : ''))
+        .join('');
 }

package/dist/esm/kits/normalization.d.ts

@@ -1,5 +1,17 @@
 import type { NormalizationStep, NormalizationOptions } from '../structs/kits/normalization.js';
-/** Ordered value transformations; replacement, completion and input ownership are explicit. */
+/**
+ * Compile an ordered normalization pipeline.
+ *
+ * Steps run in declaration order. Each step may be skipped by its `when` predicate, receives
+ * the value produced by the previous step, and `isComplete` can stop the walk early, so the
+ * usual contract is "first completion wins" rather than "always run everything".
+ *
+ * @param definitions - Steps with unique non-blank ids and a synchronous `normalize` handler.
+ * @param options - Optional completion predicate; bound to the options object.
+ * @returns A frozen pipeline exposing `steps` (ids plus handlers) and `normalize`.
+ * @throws TypeError At construction for blank/duplicate ids or a missing handler; from
+ *   `normalize` when a predicate or handler returns a thenable or a non-boolean.
+ */
 export declare function defineNormalization<Value, Context = void>(definitions: readonly NormalizationStep<Value, Context>[], options?: NormalizationOptions<Value, Context>): Readonly<{
     steps: readonly Readonly<{
         id: string;
@@ -8,9 +20,20 @@ export declare function defineNormalization<Value, Context = void>(definitions:
     }>[];
     normalize(value: Value, context: Context): Value;
 }>;
-/** Stable deduplication preserves the original values; the host chooses equivalence. */
+/**
+ * Stable deduplication preserves the original values; the host chooses equivalence.
+ *
+ * The first occurrence of each key wins and the input order is kept, so callers can rely on
+ * deduplication never reordering their list.
+ *
+ * @param values - Values in the order to retain.
+ * @param key - Equivalence selector.
+ * @param initial - Keys already treated as seen, for example those owned by another batch.
+ * @returns The retained values as a new array.
+ */
 export declare function uniqueBy<Value, Key>(values: readonly Value[], key: (value: Value) => Key, initial?: Iterable<Key>): Value[];
 export type { NormalizationStep, NormalizationOptions } from '../structs/kits/normalization.js';
+/** Namespace object for callers that prefer one import over named helpers. */
 export declare const Normalization: Readonly<{
     defineNormalization: typeof defineNormalization;
     uniqueBy: typeof uniqueBy;

package/dist/esm/kits/normalization.js

@@ -1,17 +1,50 @@
+/**
+ * Normalization Kit: ordered synchronous value transformations and stable deduplication.
+ *
+ * Place in the package: an optional App-side helper for cleaning model or transport input
+ * before it reaches business logic. Replacement, completion detection and input ownership stay
+ * explicit; this module never mutates the caller's arrays.
+ *
+ * Exports: `defineNormalization`, `uniqueBy`, `Normalization`, and the step/option types.
+ */
 import { synchronous, booleanResult } from '../utils/synchronous.js';
 import { breakWhile } from '../utils/rules.js';
-/** Ordered value transformations; replacement, completion and input ownership are explicit. */
+/**
+ * Compile an ordered normalization pipeline.
+ *
+ * Steps run in declaration order. Each step may be skipped by its `when` predicate, receives
+ * the value produced by the previous step, and `isComplete` can stop the walk early, so the
+ * usual contract is "first completion wins" rather than "always run everything".
+ *
+ * @param definitions - Steps with unique non-blank ids and a synchronous `normalize` handler.
+ * @param options - Optional completion predicate; bound to the options object.
+ * @returns A frozen pipeline exposing `steps` (ids plus handlers) and `normalize`.
+ * @throws TypeError At construction for blank/duplicate ids or a missing handler; from
+ *   `normalize` when a predicate or handler returns a thenable or a non-boolean.
+ */
 export function defineNormalization(definitions, options = {}) {
     const isComplete = options.isComplete?.bind(options);
     const predicate = (value) => booleanResult(value, 'Normalization predicates must be synchronous', 'Normalization predicates must return boolean');
     const ids = new Set();
-    const steps = Object.freeze(definitions.map(step => {
+    const steps = Object.freeze(definitions.map((step) => {
         breakWhile([
-            { occur: () => !step.id.trim() || ids.has(step.id), error: 'Invalid or duplicate normalization step', tags: ['id'] },
-            { occur: () => typeof step.normalize !== 'function', error: 'Missing normalization handler', tags: ['handler'] },
+            {
+                occur: () => !step.id.trim() || ids.has(step.id),
+                error: 'Invalid or duplicate normalization step',
+                tags: ['id'],
+            },
+            {
+                occur: () => typeof step.normalize !== 'function',
+                error: 'Missing normalization handler',
+                tags: ['handler'],
+            },
         ]);
         ids.add(step.id);
-        return Object.freeze({ id: step.id, when: step.when?.bind(step), normalize: step.normalize.bind(step) });
+        return Object.freeze({
+            id: step.id,
+            when: step.when?.bind(step),
+            normalize: step.normalize.bind(step),
+        });
     }));
     return Object.freeze({
         steps,
@@ -27,10 +60,20 @@ export function defineNormalization(definitions, options = {}) {
         },
     });
 }
-/** Stable deduplication preserves the original values; the host chooses equivalence. */
+/**
+ * Stable deduplication preserves the original values; the host chooses equivalence.
+ *
+ * The first occurrence of each key wins and the input order is kept, so callers can rely on
+ * deduplication never reordering their list.
+ *
+ * @param values - Values in the order to retain.
+ * @param key - Equivalence selector.
+ * @param initial - Keys already treated as seen, for example those owned by another batch.
+ * @returns The retained values as a new array.
+ */
 export function uniqueBy(values, key, initial = []) {
     const seen = new Set(initial);
-    return values.filter(value => {
+    return values.filter((value) => {
         const id = key(value);
         if (seen.has(id))
             return false;
@@ -38,4 +81,5 @@ export function uniqueBy(values, key, initial = []) {
         return true;
     });
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 export const Normalization = Object.freeze({ defineNormalization, uniqueBy });

package/dist/esm/kits/policies.d.ts

@@ -1,5 +1,16 @@
 import type { PolicyDefinition, RecoveryDefinition, RecoveryResult } from '../structs/kits/policies.js';
-/** Collect every matching reason; a configured mode cannot silently override a mandatory policy. */
+/**
+ * Compile a policy set that reports every matching reason.
+ *
+ * Collect every matching reason; a configured mode cannot silently override a mandatory
+ * policy. `assess` returns the matched ids and deduplicated kinds rather than a single verdict,
+ * so callers keep the ordering information they need for messages and diagnostics.
+ *
+ * @param definitions - Policies with unique ids, descriptions and a synchronous `when`.
+ * @returns A frozen catalog extended with `assess(input)`.
+ * @throws TypeError For blank/duplicate ids, a blank description, a missing `when`, or a
+ *   predicate that is not synchronous boolean.
+ */
 export declare function definePolicySet<Input, Kind extends string>(definitions: readonly PolicyDefinition<Input, Kind>[]): Readonly<{
     assess(input: Input): {
         required: boolean;
@@ -14,7 +25,18 @@ export declare function definePolicySet<Input, Kind extends string>(definitions:
     get(id: string): Readonly<PolicyDefinition<Input, Kind>> | undefined;
     require(id: string): Readonly<PolicyDefinition<Input, Kind>>;
 }>;
-/** A handler reports whether it handled the input; handled undefined values remain explicit. */
+/**
+ * Compile an ordered recovery chain.
+ *
+ * A handler reports whether it handled the input; handled undefined values remain explicit.
+ * The first handler that reports `handled` ends the walk, so declaration order is the
+ * precedence, and `{ handled: false }` is the only way to fall through.
+ *
+ * @param definitions - Recovery handlers with unique ids, descriptions and `tryRecover`.
+ * @returns A frozen catalog extended with `tryRecover(input)`.
+ * @throws TypeError For blank/duplicate ids, a missing handler, or an outcome that lacks a
+ *   boolean `handled` or omits `value` while claiming to have handled the input.
+ */
 export declare function defineRecoveryChain<Input, Result>(definitions: readonly RecoveryDefinition<Input, Result>[]): Readonly<{
     tryRecover: (input: Input) => RecoveryResult<Result>;
     definitions: readonly Readonly<{
@@ -45,7 +67,8 @@ export declare function defineRecoveryChain<Input, Result>(definitions: readonly
         tryRecover(input: Input): RecoveryResult<Result>;
     }>;
 }>;
-export type { PolicyDefinition, PolicyAssessment, RecoveryDefinition, RecoveryResult } from '../structs/kits/policies.js';
+export type { PolicyDefinition, PolicyAssessment, RecoveryDefinition, RecoveryResult, } from '../structs/kits/policies.js';
+/** Namespace object for callers that prefer one import over named helpers. */
 export declare const Policies: Readonly<{
     definePolicySet: typeof definePolicySet;
     defineRecoveryChain: typeof defineRecoveryChain;

package/dist/esm/kits/policies.js

@@ -1,27 +1,69 @@
+/**
+ * Policies Kit: assess which declared policies apply, and run ordered recovery handlers.
+ *
+ * Place in the package: an optional App-side library for policy and recovery tables. Policy
+ * predicates, recovery handlers, kinds and descriptions are App configuration; this module
+ * owns registration checks, evaluation order and outcome validation.
+ *
+ * Exports: `definePolicySet`, `defineRecoveryChain`, `Policies`, and the policy types.
+ */
 import { readonlyCatalog } from '../utils/catalog.js';
 import { synchronous, booleanResult } from '../utils/synchronous.js';
 import { breakWhile } from '../utils/rules.js';
-/** Collect every matching reason; a configured mode cannot silently override a mandatory policy. */
+/**
+ * Compile a policy set that reports every matching reason.
+ *
+ * Collect every matching reason; a configured mode cannot silently override a mandatory
+ * policy. `assess` returns the matched ids and deduplicated kinds rather than a single verdict,
+ * so callers keep the ordering information they need for messages and diagnostics.
+ *
+ * @param definitions - Policies with unique ids, descriptions and a synchronous `when`.
+ * @returns A frozen catalog extended with `assess(input)`.
+ * @throws TypeError For blank/duplicate ids, a blank description, a missing `when`, or a
+ *   predicate that is not synchronous boolean.
+ */
 export function definePolicySet(definitions) {
     const catalog = registerPolicies(definitions, 'when');
     return Object.freeze({
-        ...readonlyCatalog(catalog, id => new TypeError(`Unknown policy: ${id}`)),
+        ...readonlyCatalog(catalog, (id) => new TypeError(`Unknown policy: ${id}`)),
         assess(input) {
-            const matched = catalog.filter(policy => booleanMatch(policy.when(input)));
-            return { required: matched.length > 0, reasons: matched.map(policy => policy.id), kinds: [...new Set(matched.map(policy => policy.kind))] };
+            const matched = catalog.filter((policy) => booleanMatch(policy.when(input)));
+            return {
+                required: matched.length > 0,
+                reasons: matched.map((policy) => policy.id),
+                kinds: [...new Set(matched.map((policy) => policy.kind))],
+            };
         },
     });
 }
-/** A handler reports whether it handled the input; handled undefined values remain explicit. */
+/**
+ * Compile an ordered recovery chain.
+ *
+ * A handler reports whether it handled the input; handled undefined values remain explicit.
+ * The first handler that reports `handled` ends the walk, so declaration order is the
+ * precedence, and `{ handled: false }` is the only way to fall through.
+ *
+ * @param definitions - Recovery handlers with unique ids, descriptions and `tryRecover`.
+ * @returns A frozen catalog extended with `tryRecover(input)`.
+ * @throws TypeError For blank/duplicate ids, a missing handler, or an outcome that lacks a
+ *   boolean `handled` or omits `value` while claiming to have handled the input.
+ */
 export function defineRecoveryChain(definitions) {
-    const catalog = registerPolicies(definitions, 'tryRecover').map(definition => {
-        return Object.freeze({ id: definition.id, description: definition.description, tryRecover(input) {
+    const catalog = registerPolicies(definitions, 'tryRecover').map((definition) => {
+        return Object.freeze({
+            id: definition.id,
+            description: definition.description,
+            tryRecover(input) {
                 const value = synchronous(definition.tryRecover(input), 'Recovery handlers must be synchronous');
                 const result = value;
-                if (!result || typeof result !== 'object' || typeof result.handled !== 'boolean' || (result.handled && !('value' in result)))
+                if (!result ||
+                    typeof result !== 'object' ||
+                    typeof result.handled !== 'boolean' ||
+                    (result.handled && !('value' in result)))
                     throw new TypeError('Invalid recovery outcome');
                 return result;
-            } });
+            },
+        });
     });
     const tryRecover = (input) => {
         for (const policy of catalog) {
@@ -31,20 +73,42 @@ export function defineRecoveryChain(definitions) {
         }
         return { handled: false };
     };
-    return Object.freeze({ ...readonlyCatalog(catalog, id => new TypeError(`Unknown recovery policy: ${id}`)), tryRecover });
+    return Object.freeze({
+        ...readonlyCatalog(catalog, (id) => new TypeError(`Unknown recovery policy: ${id}`)),
+        tryRecover,
+    });
 }
 function registerPolicies(definitions, handler) {
     const ids = new Set();
-    return Object.freeze(definitions.map(definition => {
+    return Object.freeze(definitions.map((definition) => {
         breakWhile([
-            { occur: () => !definition.id.trim() || !definition.description.trim(), error: 'Invalid policy declaration', tags: ['metadata'] },
-            { occur: () => ids.has(definition.id), error: () => `Duplicate policy: ${definition.id}`, tags: ['id'] },
-            { occur: () => typeof definition[handler] !== 'function', error: () => `Missing policy handler: ${definition.id}`, tags: ['handler'] },
+            {
+                occur: () => !definition.id.trim() || !definition.description.trim(),
+                error: 'Invalid policy declaration',
+                tags: ['metadata'],
+            },
+            {
+                occur: () => ids.has(definition.id),
+                error: () => `Duplicate policy: ${definition.id}`,
+                tags: ['id'],
+            },
+            {
+                occur: () => typeof definition[handler] !== 'function',
+                error: () => `Missing policy handler: ${definition.id}`,
+                tags: ['handler'],
+            },
         ], ['agent-core', 'policy-registration']);
         ids.add(definition.id);
-        return Object.freeze({ ...definition, id: definition.id, description: definition.description, ...('kind' in definition ? { kind: definition.kind } : {}), [handler]: definition[handler].bind(definition) });
+        return Object.freeze({
+            ...definition,
+            id: definition.id,
+            description: definition.description,
+            ...('kind' in definition ? { kind: definition.kind } : {}),
+            [handler]: definition[handler].bind(definition),
+        });
     }));
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 export const Policies = Object.freeze({ definePolicySet, defineRecoveryChain });
 function booleanMatch(value) {
     return booleanResult(value, 'Policy predicates must be synchronous', 'Policy predicates must return boolean');

package/dist/esm/kits/presentation/events.d.ts

@@ -1,14 +1,61 @@
+/**
+ * Presentation Kit: the reply bubble/chunk event protocol.
+ *
+ * Place in the package: part of the `presentation` Kit. It turns a validated reply string into
+ * a paced stream of `text`/`bubble` events and can serialize that stream back into plain text.
+ * Transport, styling and the actual rendering stay with the App.
+ *
+ * Exports: `REPLY_BUBBLE_BOUNDARY`, `replyBubbleTexts`, `publishReplyEvents`,
+ * `serializeOutputEvents`, `textOutputEvents`, and the output event types.
+ */
 import type { AgentOutputEvent, ReplyBubbleInput, ReplyDeliveryOptions } from '../../structs/kits/presentation/events.js';
 import type { ExecutionContext } from '../../structs/common.js';
-/** Internal boundary between validated assistant bubbles. Never sent as visible text. */
+/**
+ * Internal boundary between validated assistant bubbles. Never sent as visible text.
+ *
+ * U+001E (record separator) is a non-printing control character that ordinary replies do not
+ * contain, so splitting on it cannot truncate visible prose.
+ */
 export declare const REPLY_BUBBLE_BOUNDARY = "\u001E";
+/**
+ * Collect the non-empty-text parts of a reply.
+ *
+ * @param reply - Primary text plus optional extra bubbles.
+ * @returns The text and every string bubble; non-string entries are dropped.
+ */
 export declare function replyBubbleTexts(reply: ReplyBubbleInput): string[];
-/** Publish a validated reply without exposing its internal boundary to consumers. */
+/**
+ * Stream one reply as paced text chunks and bubble separators.
+ *
+ * Publish a validated reply without exposing its internal boundary to consumers. The pacing
+ * options are upper bounds, not exact timings: the pause and interval are clamped against
+ * `maxDurationMs`, so added delay never exceeds the budget while every chunk is still emitted.
+ *
+ * @param request - Reply text (bubbles separated by `REPLY_BUBBLE_BOUNDARY`) and pacing options.
+ * @param context - Execution context supplying the abort signal.
+ * @returns An async stream of `text` and `bubble` events, in order.
+ * @throws TypeError For a malformed request, missing signal, or invalid chunk/pacing values;
+ *   aborts with the caller's signal.
+ */
 export declare function publishReplyEvents(request: {
     text: string;
     delivery?: ReplyDeliveryOptions;
 }, context: ExecutionContext): AsyncIterable<AgentOutputEvent>;
-/** Serialize the event protocol for callers using a text stream. */
+/**
+ * Serialize the event protocol for callers using a text stream.
+ *
+ * `preview` events are dropped because they are not final text; bubbles become the boundary
+ * character again, so a consumer can re-split the stream.
+ *
+ * @param events - Event stream carrying `text`, `bubble` or `preview` entries.
+ * @returns The equivalent string chunks.
+ */
 export declare function serializeOutputEvents(events: AsyncIterable<AgentOutputEvent>): AsyncIterable<string>;
+/**
+ * Wrap already-chunked text as `text` events.
+ *
+ * @param chunks - Text chunks in delivery order.
+ * @returns The same chunks as events.
+ */
 export declare function textOutputEvents(chunks: AsyncIterable<string>): AsyncIterable<AgentOutputEvent>;
-export type { AgentOutputEvent, ReplyBubbleInput, ReplyDeliveryOptions } from '../../structs/kits/presentation/events.js';
+export type { AgentOutputEvent, ReplyBubbleInput, ReplyDeliveryOptions, } from '../../structs/kits/presentation/events.js';

package/dist/esm/kits/presentation/events.js

@@ -1,26 +1,49 @@
 import { breakWhile } from '../../utils/rules.js';
-/** Internal boundary between validated assistant bubbles. Never sent as visible text. */
+/**
+ * Internal boundary between validated assistant bubbles. Never sent as visible text.
+ *
+ * U+001E (record separator) is a non-printing control character that ordinary replies do not
+ * contain, so splitting on it cannot truncate visible prose.
+ */
 export const REPLY_BUBBLE_BOUNDARY = '\u001e';
+/**
+ * Collect the non-empty-text parts of a reply.
+ *
+ * @param reply - Primary text plus optional extra bubbles.
+ * @returns The text and every string bubble; non-string entries are dropped.
+ */
 export function replyBubbleTexts(reply) {
     const { text, bubbles } = reply;
-    return [text, ...(Array.isArray(bubbles) ? bubbles : [])]
-        .filter((text) => typeof text === 'string');
+    return [text, ...(Array.isArray(bubbles) ? bubbles : [])].filter((text) => typeof text === 'string');
 }
-/** Publish a validated reply without exposing its internal boundary to consumers. */
+/**
+ * Stream one reply as paced text chunks and bubble separators.
+ *
+ * Publish a validated reply without exposing its internal boundary to consumers. The pacing
+ * options are upper bounds, not exact timings: the pause and interval are clamped against
+ * `maxDurationMs`, so added delay never exceeds the budget while every chunk is still emitted.
+ *
+ * @param request - Reply text (bubbles separated by `REPLY_BUBBLE_BOUNDARY`) and pacing options.
+ * @param context - Execution context supplying the abort signal.
+ * @returns An async stream of `text` and `bubble` events, in order.
+ * @throws TypeError For a malformed request, missing signal, or invalid chunk/pacing values;
+ *   aborts with the caller's signal.
+ */
 export async function* publishReplyEvents(request, context) {
     breakWhile(!request || typeof request !== 'object', () => new TypeError('Use a named reply delivery request'));
     const { text, delivery } = request, { signal } = context;
     breakWhile(typeof text !== 'string' || !signal, () => new TypeError('Reply delivery requires text and ExecutionContext'));
     breakWhile(delivery !== undefined && (!delivery || typeof delivery !== 'object'), () => new TypeError('Reply delivery requires named options'));
-    const { chunkSize = 240, intervalMs = 0, bubblePauseMs = 0, maxDurationMs = 3000 } = delivery ?? {};
+    const { chunkSize = 240, intervalMs = 0, bubblePauseMs = 0, maxDurationMs = 3000, } = delivery ?? {};
     breakWhile(!Number.isSafeInteger(chunkSize) || chunkSize < 1, () => new TypeError('Invalid output chunk size'));
     for (const [name, value] of Object.entries({ intervalMs, bubblePauseMs, maxDurationMs }))
         breakWhile(!Number.isFinite(value) || value < 0, () => new TypeError(`Invalid ${name}`));
     signal.throwIfAborted();
-    const bubbles = text.split(REPLY_BUBBLE_BOUNDARY).map(bubble => Array.from(bubble));
+    const bubbles = text.split(REPLY_BUBBLE_BOUNDARY).map((bubble) => Array.from(bubble));
     const chunkCount = bubbles.reduce((sum, bubble) => sum + Math.ceil(bubble.length / chunkSize), 0);
     const pause = Math.min(bubblePauseMs, maxDurationMs / Math.max(1, bubbles.length - 1));
-    const interval = Math.min(intervalMs, Math.max(0, maxDurationMs - pause * (bubbles.length - 1)) / Math.max(1, chunkCount - bubbles.filter(bubble => bubble.length).length));
+    const interval = Math.min(intervalMs, Math.max(0, maxDurationMs - pause * (bubbles.length - 1)) /
+        Math.max(1, chunkCount - bubbles.filter((bubble) => bubble.length).length));
     const deadline = performance.now() + maxDurationMs;
     for (let bubble = 0; bubble < bubbles.length; bubble++) {
         if (bubble) {
@@ -43,14 +66,29 @@ async function wait(milliseconds, signal) {
     if (!milliseconds)
         return;
     await new Promise((resolve, reject) => {
-        const stop = () => { clearTimeout(timer); signal.removeEventListener('abort', stop); reject(signal.reason); };
-        const timer = setTimeout(() => { signal.removeEventListener('abort', stop); resolve(); }, milliseconds);
+        const stop = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', stop);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', stop);
+            resolve();
+        }, milliseconds);
         signal.addEventListener('abort', stop, { once: true });
         if (signal.aborted)
             stop();
     });
 }
-/** Serialize the event protocol for callers using a text stream. */
+/**
+ * Serialize the event protocol for callers using a text stream.
+ *
+ * `preview` events are dropped because they are not final text; bubbles become the boundary
+ * character again, so a consumer can re-split the stream.
+ *
+ * @param events - Event stream carrying `text`, `bubble` or `preview` entries.
+ * @returns The equivalent string chunks.
+ */
 export async function* serializeOutputEvents(events) {
     for await (const event of events) {
         if (event.type === 'preview')
@@ -58,6 +96,12 @@ export async function* serializeOutputEvents(events) {
         yield event.type === 'bubble' ? REPLY_BUBBLE_BOUNDARY : event.text;
     }
 }
+/**
+ * Wrap already-chunked text as `text` events.
+ *
+ * @param chunks - Text chunks in delivery order.
+ * @returns The same chunks as events.
+ */
 export async function* textOutputEvents(chunks) {
     for await (const text of chunks)
         yield { type: 'text', text };

package/dist/esm/kits/presentation/index.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Presentation Kit entry: output contracts, text templates, semantic slots, variants and the
+ * reply/chunk event stream.
+ *
+ * Place in the package: an optional App-side library for shaping what the user finally sees.
+ * The App owns copy, styling and transport; this directory owns contract validation, template
+ * substitution, variant selection and the bubble/chunk protocol.
+ *
+ * Exports: everything from `./outputs.js`, `./variants.js`, `./templates.js` and `./events.js`,
+ * plus the `Presentation` namespace object.
+ */
 export * from './outputs.js';
 export * from './variants.js';
 export type * from '../../structs/kits/presentation/outputs.js';
@@ -7,6 +18,7 @@ import { defineOutputCatalog } from './outputs.js';
 import { defineTextTemplate, defineSemanticSlots } from './templates.js';
 import { selectVariant, resolvePreference } from './variants.js';
 import { replyBubbleTexts, publishReplyEvents, serializeOutputEvents, textOutputEvents } from './events.js';
+/** Namespace object for callers that prefer one import over named helpers. */
 export declare const Presentation: Readonly<{
     defineOutputCatalog: typeof defineOutputCatalog;
     defineTextTemplate: typeof defineTextTemplate;

package/dist/esm/kits/presentation/index.js

@@ -1,3 +1,14 @@
+/**
+ * Presentation Kit entry: output contracts, text templates, semantic slots, variants and the
+ * reply/chunk event stream.
+ *
+ * Place in the package: an optional App-side library for shaping what the user finally sees.
+ * The App owns copy, styling and transport; this directory owns contract validation, template
+ * substitution, variant selection and the bubble/chunk protocol.
+ *
+ * Exports: everything from `./outputs.js`, `./variants.js`, `./templates.js` and `./events.js`,
+ * plus the `Presentation` namespace object.
+ */
 export * from './outputs.js';
 export * from './variants.js';
 export * from './templates.js';
@@ -5,5 +16,17 @@ export * from './events.js';
 import { defineOutputCatalog } from './outputs.js';
 import { defineTextTemplate, defineSemanticSlots } from './templates.js';
 import { selectVariant, resolvePreference } from './variants.js';
-import { REPLY_BUBBLE_BOUNDARY, replyBubbleTexts, publishReplyEvents, serializeOutputEvents, textOutputEvents } from './events.js';
-export const Presentation = Object.freeze({ defineOutputCatalog, defineTextTemplate, defineSemanticSlots, selectVariant, resolvePreference, REPLY_BUBBLE_BOUNDARY, replyBubbleTexts, publishReplyEvents, serializeOutputEvents, textOutputEvents });
+import { REPLY_BUBBLE_BOUNDARY, replyBubbleTexts, publishReplyEvents, serializeOutputEvents, textOutputEvents, } from './events.js';
+/** Namespace object for callers that prefer one import over named helpers. */
+export const Presentation = Object.freeze({
+    defineOutputCatalog,
+    defineTextTemplate,
+    defineSemanticSlots,
+    selectVariant,
+    resolvePreference,
+    REPLY_BUBBLE_BOUNDARY,
+    replyBubbleTexts,
+    publishReplyEvents,
+    serializeOutputEvents,
+    textOutputEvents,
+});

package/dist/esm/kits/presentation/outputs.d.ts

@@ -1,6 +1,20 @@
 import type { OperationContext } from '../../structs/common.js';
 import type { OutputDefinition, OutputField, OutputComposeInput, OutputIssue, OutputResult, OutputCatalogOptions } from '../../structs/kits/presentation/outputs.js';
+/**
+ * Compile output definitions into one catalog.
+ *
+ * Compilation is where most mistakes surface: group membership is checked for cycles, master
+ * templates must have exactly one slot per field, and every `bound`/`semantic` field must name
+ * a registered provider. Composition then trusts the compiled catalog.
+ *
+ * @param definitions - Output definitions with unique ids and a supported `kind`.
+ * @param options - Provider list and an optional observer for composed results.
+ * @returns A frozen catalog extended with `toModelSchema`, `check` and `compose`.
+ * @throws TypeError For an invalid id or kind, a malformed group, mismatched master slots,
+ *   an invalid field owner or semantic keys, or an unknown provider id.
+ */
 export declare function defineOutputCatalog<App = unknown>(definitions: readonly OutputDefinition[], options?: OutputCatalogOptions<App>): Readonly<{
+    /** JSON schema of the fields a model must generate for this output. */
     toModelSchema: (id: string) => {
         type: string;
         properties: {
@@ -9,6 +23,12 @@ export declare function defineOutputCatalog<App = unknown>(definitions: readonly
         required: string[];
         additionalProperties: boolean;
     };
+    /**
+     * Validate a generated value without composing it.
+     *
+     * @param request - Output id and the candidate value.
+     * @returns `passed` or `failed` with the collected issues and accepted values.
+     */
     check(request: {
         outputId: string;
         value: unknown;
@@ -17,6 +37,15 @@ export declare function defineOutputCatalog<App = unknown>(definitions: readonly
         value: Record<string, unknown>;
         issues: OutputIssue[];
     };
+    /**
+     * Compose the final output value from generated fields, providers and constants.
+     *
+     * @param request - Output id and the generated/group input.
+     * @param context - Operation context; cancellation is checked between every step.
+     * @returns The frozen composed result, also forwarded to the observer.
+     * @throws TypeError For a malformed request, missing context, rejected generated fields
+     *   (carrying `issues`), a non-synchronous provider, or a text output that is not a string.
+     */
     compose(request: {
         outputId: string;
         input: OutputComposeInput;
@@ -64,4 +93,4 @@ export declare function defineOutputCatalog<App = unknown>(definitions: readonly
         maxItems?: number | undefined;
     }>;
 }>;
-export type { OutputDefinition, OutputField, OutputProvider, OutputComposeInput, OutputIssue, OutputResult, OutputCatalogOptions } from '../../structs/kits/presentation/outputs.js';
+export type { OutputDefinition, OutputField, OutputProvider, OutputComposeInput, OutputIssue, OutputResult, OutputCatalogOptions, } from '../../structs/kits/presentation/outputs.js';