@jangts/agent-core 0.1.1 → 0.2.1

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

@@ -1,17 +1,52 @@
+/**
+ * Presentation Kit: declarative output contracts for text, master, record and group outputs.
+ *
+ * Place in the package: part of the `presentation` Kit. A definition decides which fields the
+ * model generates, which are bound to App providers, which are constants and which select a
+ * semantic key; this module validates those declarations and composes the final value.
+ *
+ * Exports: `defineOutputCatalog`, and the output definition/field/provider/result types.
+ */
 import { snapshotSchemaAdapter } from '../../utils/schema-adapter.js';
 import { readonlyCatalog } from '../../utils/catalog.js';
 import { synchronous } from '../../utils/synchronous.js';
 import { defineTextTemplate } from './templates.js';
 import { freezeSchema } from '../../utils/object.js';
 import { observeSafely } from '../../utils/observer.js';
-function snapshotValue(value) { const copy = structuredClone(value); freezeSchema(copy); return copy; }
-const textValueSchema = snapshotSchemaAdapter({ jsonSchema: { type: 'string' }, parse(value) {
+function snapshotValue(value) {
+    const copy = structuredClone(value);
+    freezeSchema(copy);
+    return copy;
+}
+const textValueSchema = snapshotSchemaAdapter({
+    jsonSchema: { type: 'string' },
+    parse(value) {
         if (typeof value !== 'string')
             throw new TypeError('Invalid output field value');
         return value;
-    } });
-function parseField(field, value) { return field.valueSchema.parse(value); }
-const validId = (id) => typeof id === 'string' && /^[A-Za-z][A-Za-z0-9_.-]*$/.test(id) && !['__proto__', 'constructor', 'prototype'].includes(id);
+    },
+});
+function parseField(field, value) {
+    return field.valueSchema.parse(value);
+}
+// Object-prototype names are excluded so a field id can never shadow `__proto__` or replace a
+// prototype member when values are assembled into a dictionary.
+const validId = (id) => typeof id === 'string' &&
+    /^[A-Za-z][A-Za-z0-9_.-]*$/.test(id) &&
+    !['__proto__', 'constructor', 'prototype'].includes(id);
+/**
+ * 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 function defineOutputCatalog(definitions, options = {}) {
     const providers = options.providers ?? [], observe = options.observe?.bind(options);
     const providerMap = new Map();
@@ -27,42 +62,70 @@ export function defineOutputCatalog(definitions, options = {}) {
         const { id, kind, fields: fieldDefinitions, master, maxItems, allowedOutputIds } = definition;
         if (!validId(id) || catalog.has(id) || !['text', 'master', 'record', 'group'].includes(kind))
             throw new TypeError('Invalid output definition');
-        const fields = fieldDefinitions?.map(field => {
+        const fields = fieldDefinitions?.map((field) => {
             const { id, owner, required, valueSchema, providerId, constantValue, semanticKeys } = field;
-            return Object.freeze({ id, owner, required, valueSchema: valueSchema === undefined ? textValueSchema : snapshotSchemaAdapter(valueSchema),
-                providerId, constantValue: owner === 'constant' ? snapshotValue(constantValue) : undefined,
-                semanticKeys: semanticKeys === undefined ? undefined : Object.freeze([...semanticKeys]) });
+            return Object.freeze({
+                id,
+                owner,
+                required,
+                valueSchema: valueSchema === undefined ? textValueSchema : snapshotSchemaAdapter(valueSchema),
+                providerId,
+                constantValue: owner === 'constant' ? snapshotValue(constantValue) : undefined,
+                semanticKeys: semanticKeys === undefined ? undefined : Object.freeze([...semanticKeys]),
+            });
+        });
+        const entry = Object.freeze({
+            id,
+            kind,
+            master,
+            maxItems,
+            fields: fields ? Object.freeze(fields) : undefined,
+            allowedOutputIds: allowedOutputIds === undefined ? undefined : Object.freeze([...allowedOutputIds]),
         });
-        const entry = Object.freeze({ id, kind, master, maxItems, fields: fields ? Object.freeze(fields) : undefined,
-            allowedOutputIds: allowedOutputIds === undefined ? undefined : Object.freeze([...allowedOutputIds]) });
         if (entry.kind === 'group') {
-            if (entry.fields?.length || entry.master !== undefined || !entry.allowedOutputIds?.length || new Set(entry.allowedOutputIds).size !== entry.allowedOutputIds.length || !Number.isSafeInteger(entry.maxItems) || entry.maxItems < 1)
+            if (entry.fields?.length ||
+                entry.master !== undefined ||
+                !entry.allowedOutputIds?.length ||
+                new Set(entry.allowedOutputIds).size !== entry.allowedOutputIds.length ||
+                !Number.isSafeInteger(entry.maxItems) ||
+                entry.maxItems < 1)
                 throw new TypeError('Invalid output group');
         }
         else {
-            if (!fields?.length || new Set(fields.map(field => field.id)).size !== fields.length || (entry.kind === 'text' && (fields.length !== 1 || fields[0].required === false)))
+            if (!fields?.length ||
+                new Set(fields.map((field) => field.id)).size !== fields.length ||
+                (entry.kind === 'text' && (fields.length !== 1 || fields[0].required === false)))
                 throw new TypeError('Invalid output fields');
             for (const field of fields) {
-                if (!validId(field.id) || !['generated', 'bound', 'constant', 'semantic'].includes(field.owner))
+                if (!validId(field.id) ||
+                    !['generated', 'bound', 'constant', 'semantic'].includes(field.owner))
                     throw new TypeError('Invalid output ownership');
                 if (['bound', 'semantic'].includes(field.owner) && !providerMap.has(field.providerId))
                     throw new TypeError(`Unknown output provider: ${field.providerId}`);
-                if (field.owner === 'semantic' && (!field.semanticKeys?.length || new Set(field.semanticKeys).size !== field.semanticKeys.length || field.semanticKeys.some(key => typeof key !== 'string' || !key)))
+                if (field.owner === 'semantic' &&
+                    (!field.semanticKeys?.length ||
+                        new Set(field.semanticKeys).size !== field.semanticKeys.length ||
+                        field.semanticKeys.some((key) => typeof key !== 'string' || !key)))
                     throw new TypeError('Invalid semantic output keys');
             }
             if (entry.kind === 'master') {
                 if (typeof entry.master !== 'string')
                     throw new TypeError('Missing output master');
                 const template = defineTextTemplate(entry.master);
-                if (template.slots.length !== fields.length || template.slots.some(id => !fields.some(field => field.id === id)))
+                if (template.slots.length !== fields.length ||
+                    template.slots.some((id) => !fields.some((field) => field.id === id)))
                     throw new TypeError('Output master fields do not match slots');
                 masters.set(entry.id, template);
             }
         }
         catalog.set(entry.id, entry);
     }
-    const get = (id) => { const entry = catalog.get(id); if (!entry)
-        throw new TypeError(`Unknown output: ${id}`); return entry; };
+    const get = (id) => {
+        const entry = catalog.get(id);
+        if (!entry)
+            throw new TypeError(`Unknown output: ${id}`);
+        return entry;
+    };
     const visited = new Set(), visiting = new Set();
     function checkRefs(id) {
         if (visited.has(id))
@@ -78,13 +141,23 @@ export function defineOutputCatalog(definitions, options = {}) {
     for (const id of catalog.keys())
         checkRefs(id);
     // Both callers reject groups before asking for their validated nonempty fields.
-    const modelFields = (entry) => entry.fields.filter(field => ['generated', 'semantic'].includes(field.owner));
+    const modelFields = (entry) => entry.fields.filter((field) => ['generated', 'semantic'].includes(field.owner));
     function toModelSchema(id) {
         const entry = get(id);
         if (entry.kind === 'group')
             throw new TypeError('Output groups require program-assigned items');
         const fields = modelFields(entry);
-        return { type: 'object', properties: Object.fromEntries(fields.map(field => [field.id, field.owner === 'semantic' ? { type: 'string', enum: [...field.semanticKeys] } : field.valueSchema.jsonSchema])), required: fields.filter(field => field.required !== false).map(field => field.id), additionalProperties: false };
+        return {
+            type: 'object',
+            properties: Object.fromEntries(fields.map((field) => [
+                field.id,
+                field.owner === 'semantic'
+                    ? { type: 'string', enum: [...field.semanticKeys] }
+                    : field.valueSchema.jsonSchema,
+            ])),
+            required: fields.filter((field) => field.required !== false).map((field) => field.id),
+            additionalProperties: false,
+        };
     }
     function inspect(id, value, signal) {
         signal?.throwIfAborted();
@@ -93,16 +166,27 @@ export function defineOutputCatalog(definitions, options = {}) {
             throw new TypeError('Inspect individual group items');
         const issues = [], values = Object.create(null);
         if (!value || typeof value !== 'object' || Array.isArray(value))
-            return { values, issues: [{ path: [id], code: 'OUTPUT_SHAPE', message: 'Expected an output object' }] };
+            return {
+                values,
+                issues: [{ path: [id], code: 'OUTPUT_SHAPE', message: 'Expected an output object' }],
+            };
         const input = value, fields = modelFields(entry);
         for (const key of Object.keys(input))
-            if (!fields.some(field => field.id === key))
-                issues.push({ path: [id, key], code: 'OUTPUT_FOREIGN_FIELD', message: 'Unknown generated field' });
+            if (!fields.some((field) => field.id === key))
+                issues.push({
+                    path: [id, key],
+                    code: 'OUTPUT_FOREIGN_FIELD',
+                    message: 'Unknown generated field',
+                });
         for (const field of fields) {
             signal?.throwIfAborted();
             if (!Object.hasOwn(input, field.id)) {
                 if (field.required !== false)
-                    issues.push({ path: [id, field.id], code: 'OUTPUT_MISSING', message: 'Required generated field is missing' });
+                    issues.push({
+                        path: [id, field.id],
+                        code: 'OUTPUT_MISSING',
+                        message: 'Required generated field is missing',
+                    });
                 continue;
             }
             const value = input[field.id];
@@ -118,9 +202,16 @@ export function defineOutputCatalog(definitions, options = {}) {
             }
             catch (error) {
                 signal?.throwIfAborted();
-                if (error && typeof error === 'object' && 'name' in error && ['AbortError', 'TimeoutError'].includes(String(error.name)))
+                if (error &&
+                    typeof error === 'object' &&
+                    'name' in error &&
+                    ['AbortError', 'TimeoutError'].includes(String(error.name)))
                     throw error;
-                issues.push({ path: [id, field.id], code: 'OUTPUT_VALUE', message: 'Generated field does not match its schema' });
+                issues.push({
+                    path: [id, field.id],
+                    code: 'OUTPUT_VALUE',
+                    message: 'Generated field does not match its schema',
+                });
             }
             signal?.throwIfAborted();
         }
@@ -131,16 +222,25 @@ export function defineOutputCatalog(definitions, options = {}) {
         const entry = get(id), { generated, items } = input;
         context.signal.throwIfAborted();
         if (entry.kind === 'group') {
-            if (Object.keys(generated ?? {}).length || !Array.isArray(items) || items.length > entry.maxItems)
+            if (Object.keys(generated ?? {}).length ||
+                !Array.isArray(items) ||
+                items.length > entry.maxItems)
                 throw new TypeError('Invalid output group items');
-            const assigned = items.map((item) => ({ id: item.id, outputId: item.outputId, input: item.input }));
-            if (new Set(assigned.map(item => item.id)).size !== assigned.length)
+            const assigned = items.map((item) => ({
+                id: item.id,
+                outputId: item.outputId,
+                input: item.input,
+            }));
+            if (new Set(assigned.map((item) => item.id)).size !== assigned.length)
                 throw new TypeError('Invalid output group items');
-            const value = assigned.map(item => {
+            const value = assigned.map((item) => {
                 context.signal.throwIfAborted();
                 if (!validId(item.id) || !entry.allowedOutputIds.includes(item.outputId))
                     throw new TypeError('Invalid output group reference');
-                return Object.freeze({ id: item.id, ...composeInternal(item.outputId, item.input, context) });
+                return Object.freeze({
+                    id: item.id,
+                    ...composeInternal(item.outputId, item.input, context),
+                });
             });
             context.signal.throwIfAborted();
             return Object.freeze({ outputId: id, kind: entry.kind, value: Object.freeze(value) });
@@ -148,17 +248,26 @@ export function defineOutputCatalog(definitions, options = {}) {
         const checked = inspect(id, generated ?? {}, context.signal);
         context.signal.throwIfAborted();
         if (checked.issues.length)
-            throw Object.assign(new TypeError('Output contract rejected generated fields'), { issues: checked.issues });
+            throw Object.assign(new TypeError('Output contract rejected generated fields'), {
+                issues: checked.issues,
+            });
         const values = Object.create(null);
         for (const field of entry.fields) {
             context.signal.throwIfAborted();
-            if (['generated', 'semantic'].includes(field.owner) && !Object.hasOwn(checked.values, field.id) && field.required === false) {
+            if (['generated', 'semantic'].includes(field.owner) &&
+                !Object.hasOwn(checked.values, field.id) &&
+                field.required === false) {
                 if (entry.kind === 'master')
                     values[field.id] = '';
                 continue;
             }
-            const value = field.owner === 'constant' ? field.constantValue : ['bound', 'semantic'].includes(field.owner)
-                ? synchronous(providerMap.get(field.providerId).resolve({ key: field.owner === 'semantic' ? checked.values[field.id] : undefined }, context), 'Output providers must be synchronous') : checked.values[field.id];
+            const value = field.owner === 'constant'
+                ? field.constantValue
+                : ['bound', 'semantic'].includes(field.owner)
+                    ? synchronous(providerMap.get(field.providerId).resolve({
+                        key: field.owner === 'semantic' ? checked.values[field.id] : undefined,
+                    }, context), 'Output providers must be synchronous')
+                    : checked.values[field.id];
             context.signal.throwIfAborted();
             if (value === undefined && field.required === false) {
                 if (entry.kind === 'master')
@@ -168,7 +277,11 @@ export function defineOutputCatalog(definitions, options = {}) {
             values[field.id] = field.owner === 'generated' ? value : parseField(field, value);
             context.signal.throwIfAborted();
         }
-        const value = entry.kind === 'master' ? masters.get(id).render(values) : entry.kind === 'text' ? values[entry.fields[0].id] : Object.freeze(values);
+        const value = entry.kind === 'master'
+            ? masters.get(id).render(values)
+            : entry.kind === 'text'
+                ? values[entry.fields[0].id]
+                : Object.freeze(values);
         if ((entry.kind === 'text' || entry.kind === 'master') && typeof value !== 'string')
             throw new TypeError('Text output requires a string value');
         const result = Object.freeze({ outputId: id, kind: entry.kind, value });
@@ -176,8 +289,33 @@ export function defineOutputCatalog(definitions, options = {}) {
         observeSafely(observe, result);
         return result;
     }
-    return Object.freeze({ ...readonlyCatalog(catalog.values(), id => new TypeError(`Unknown output: ${id}`)), toModelSchema,
-        check(request) { const result = inspect(request.outputId, request.value); return { status: result.issues.length ? 'failed' : 'passed', value: result.values, issues: result.issues }; },
+    return Object.freeze({
+        ...readonlyCatalog(catalog.values(), (id) => new TypeError(`Unknown output: ${id}`)),
+        /** JSON schema of the fields a model must generate for this output. */
+        toModelSchema,
+        /**
+         * 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) {
+            const result = inspect(request.outputId, request.value);
+            return {
+                status: result.issues.length ? 'failed' : 'passed',
+                value: result.values,
+                issues: result.issues,
+            };
+        },
+        /**
+         * 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, context) {
             if (!request || typeof request !== 'object')
                 throw new TypeError('Use a named output request');

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

@@ -1,12 +1,41 @@
+/**
+ * Presentation Kit: text masters with substituted slots and semantic-slot validation.
+ *
+ * Place in the package: part of the `presentation` Kit. The program owns each master; model
+ * output only supplies slot values, so generated text can never introduce new template syntax.
+ *
+ * Exports: `defineTextTemplate`, `defineSemanticSlots`, and the template definition types.
+ */
 import type { SemanticSlotDefinition, TextTemplateOptions } from '../../structs/kits/presentation/templates.js';
-/** The program owns the master; inserted model text is a value and is substituted once only. */
+/**
+ * The program owns the master; inserted model text is a value and is substituted once only.
+ *
+ * Substitution is single-pass `String.replace`: a value that itself contains `{{slot}}` is
+ * left as literal text, so a slot value cannot inject further substitutions.
+ *
+ * @param master - Template text using `{{slot}}` placeholders; slot names may repeat.
+ * @param options - Error wording and an optional observer for rendered text.
+ * @returns A frozen template exposing the deduplicated `slots` and `render(values)`.
+ * @throws Error From `render` when a referenced slot is missing from `values`.
+ */
 export declare function defineTextTemplate(master: string, options?: TextTemplateOptions): Readonly<{
     slots: readonly string[];
     render(values: Readonly<Record<string, string>>): string;
 }>;
-/** Models select public semantic keys; hosts retain private values and selection policy. */
+/**
+ * Models select public semantic keys; hosts retain private values and selection policy.
+ *
+ * A text is valid when it uses at most `maxOccurrences` namespaced slots, every name is a
+ * declared key, and no malformed `{{namespace` remnant is left behind — the last check stops
+ * partial or misspelled placeholders from reaching the template engine.
+ *
+ * @param definition - Namespace (lower-case words joined by hyphens), allowed keys and the
+ *   occurrence limit (a non-negative safe integer, 0 forbidding the slot entirely).
+ * @returns A frozen validator with the namespace and `isValid(text)`.
+ * @throws TypeError For an invalid namespace or occurrence limit.
+ */
 export declare function defineSemanticSlots(definition: SemanticSlotDefinition): Readonly<{
     namespace: string;
     isValid(text: string): boolean;
 }>;
-export type { SemanticSlotDefinition, TextTemplateOptions } from '../../structs/kits/presentation/templates.js';
+export type { SemanticSlotDefinition, TextTemplateOptions, } from '../../structs/kits/presentation/templates.js';

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

@@ -1,8 +1,20 @@
 import { breakWhile } from '../../utils/rules.js';
 import { observeSafely } from '../../utils/observer.js';
-/** The program owns the master; inserted model text is a value and is substituted once only. */
+/**
+ * The program owns the master; inserted model text is a value and is substituted once only.
+ *
+ * Substitution is single-pass `String.replace`: a value that itself contains `{{slot}}` is
+ * left as literal text, so a slot value cannot inject further substitutions.
+ *
+ * @param master - Template text using `{{slot}}` placeholders; slot names may repeat.
+ * @param options - Error wording and an optional observer for rendered text.
+ * @returns A frozen template exposing the deduplicated `slots` and `render(values)`.
+ * @throws Error From `render` when a referenced slot is missing from `values`.
+ */
 export function defineTextTemplate(master, options = {}) {
-    const slots = Object.freeze([...new Set([...master.matchAll(/\{\{(\w+)\}\}/g)].map(match => match[1]))]);
+    const slots = Object.freeze([
+        ...new Set([...master.matchAll(/\{\{(\w+)\}\}/g)].map((match) => match[1])),
+    ]);
     const errors = options.errors, missingField = errors?.missingField?.bind(errors), observe = options.observe?.bind(options);
     return Object.freeze({
         slots,
@@ -16,12 +28,26 @@ export function defineTextTemplate(master, options = {}) {
         },
     });
 }
-/** Models select public semantic keys; hosts retain private values and selection policy. */
+/**
+ * Models select public semantic keys; hosts retain private values and selection policy.
+ *
+ * A text is valid when it uses at most `maxOccurrences` namespaced slots, every name is a
+ * declared key, and no malformed `{{namespace` remnant is left behind — the last check stops
+ * partial or misspelled placeholders from reaching the template engine.
+ *
+ * @param definition - Namespace (lower-case words joined by hyphens), allowed keys and the
+ *   occurrence limit (a non-negative safe integer, 0 forbidding the slot entirely).
+ * @returns A frozen validator with the namespace and `isValid(text)`.
+ * @throws TypeError For an invalid namespace or occurrence limit.
+ */
 export function defineSemanticSlots(definition) {
     const { namespace, maxOccurrences } = definition;
     breakWhile([
         { occur: () => !/^[a-z][a-z0-9-]*$/.test(namespace), error: 'Invalid slot namespace' },
-        { occur: () => !Number.isSafeInteger(maxOccurrences) || maxOccurrences < 0, error: 'Invalid slot limit' },
+        {
+            occur: () => !Number.isSafeInteger(maxOccurrences) || maxOccurrences < 0,
+            error: 'Invalid slot limit',
+        },
     ]);
     const keys = new Set(definition.keys);
     const pattern = new RegExp(`\\{\\{${namespace}:([^{}]*)\\}\\}`, 'g');
@@ -29,7 +55,9 @@ export function defineSemanticSlots(definition) {
         namespace,
         isValid(text) {
             const matches = [...text.matchAll(pattern)];
-            return matches.length <= maxOccurrences && matches.every(match => keys.has(match[1])) && !text.replace(pattern, '').includes(`{{${namespace}`);
+            return (matches.length <= maxOccurrences &&
+                matches.every((match) => keys.has(match[1])) &&
+                !text.replace(pattern, '').includes(`{{${namespace}`));
         },
     });
 }

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

@@ -1,7 +1,36 @@
+/**
+ * Presentation Kit: variant selection and preference resolution over App-supplied values.
+ *
+ * Place in the package: part of the `presentation` Kit. Copy, priorities and randomness are
+ * App policy; this module only applies a deterministic rule to what it is given.
+ *
+ * Exports: `selectVariant`, `resolvePreference`.
+ */
+/**
+ * Pick one variant, avoiding an immediate repeat when alternatives exist.
+ *
+ * When every candidate equals `previous`, the full list is used again, so a single-value set
+ * still yields a result instead of failing.
+ *
+ * @param values - Candidate variants; an empty list returns `undefined`.
+ * @param options - Previous value to avoid and a random index source in `[0, limit)`.
+ * @returns The selected value, or `undefined` when there are no candidates.
+ * @throws TypeError When `randomIndex` returns a non-integer or an out-of-range index.
+ */
 export declare function selectVariant<Value>(values: readonly Value[], options: {
     previous?: Value;
     randomIndex(limit: number): number;
 }): Value | undefined;
+/**
+ * Resolve the preferred candidate.
+ *
+ * Highest `priority` wins; `order` breaks ties with the later entry first, so recency can be
+ * encoded without touching priority. The input array is copied before sorting.
+ *
+ * @param candidates - Values with a priority and an order marker.
+ * @returns The winning value, or `undefined` for an empty list.
+ * @throws TypeError When any priority or order is not finite.
+ */
 export declare function resolvePreference<Value>(candidates: readonly {
     value: Value;
     priority: number;

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

@@ -1,7 +1,26 @@
+/**
+ * Presentation Kit: variant selection and preference resolution over App-supplied values.
+ *
+ * Place in the package: part of the `presentation` Kit. Copy, priorities and randomness are
+ * App policy; this module only applies a deterministic rule to what it is given.
+ *
+ * Exports: `selectVariant`, `resolvePreference`.
+ */
+/**
+ * Pick one variant, avoiding an immediate repeat when alternatives exist.
+ *
+ * When every candidate equals `previous`, the full list is used again, so a single-value set
+ * still yields a result instead of failing.
+ *
+ * @param values - Candidate variants; an empty list returns `undefined`.
+ * @param options - Previous value to avoid and a random index source in `[0, limit)`.
+ * @returns The selected value, or `undefined` when there are no candidates.
+ * @throws TypeError When `randomIndex` returns a non-integer or an out-of-range index.
+ */
 export function selectVariant(values, options) {
     if (!values.length)
         return undefined;
-    const candidates = values.length > 1 ? values.filter(value => value !== options.previous) : [...values];
+    const candidates = values.length > 1 ? values.filter((value) => value !== options.previous) : [...values];
     const pool = candidates.length ? candidates : [...values];
     if (pool.length === 1)
         return pool[0];
@@ -10,8 +29,18 @@ export function selectVariant(values, options) {
         throw new TypeError('Invalid variant index');
     return pool[index];
 }
+/**
+ * Resolve the preferred candidate.
+ *
+ * Highest `priority` wins; `order` breaks ties with the later entry first, so recency can be
+ * encoded without touching priority. The input array is copied before sorting.
+ *
+ * @param candidates - Values with a priority and an order marker.
+ * @returns The winning value, or `undefined` for an empty list.
+ * @throws TypeError When any priority or order is not finite.
+ */
 export function resolvePreference(candidates) {
-    if (candidates.some(item => !Number.isFinite(item.priority) || !Number.isFinite(item.order)))
+    if (candidates.some((item) => !Number.isFinite(item.priority) || !Number.isFinite(item.order)))
         throw new TypeError('Invalid preference priority');
     return [...candidates].sort((left, right) => right.priority - left.priority || right.order - left.order)[0]?.value;
 }

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

@@ -1,18 +1,55 @@
 import type { ContentProjectionOptions, ContentProjection, TreeProjectionOptions } from '../structs/kits/projection.js';
-/** Keep valid JSON while reducing prose before dropping records; budgets are caller policy. */
+/**
+ * Compile a JSON-preserving projector.
+ *
+ * Keep valid JSON while reducing prose before dropping records; budgets are caller policy.
+ * The candidate list is tried in order (outer `counts`, inner `lengths`), so callers control
+ * whether trimming text or dropping items is preferred, and the configured fallback is used
+ * only when no candidate fits.
+ *
+ * @param options - Candidate bounds, a synchronous renderer and a synchronous fallback factory.
+ * @returns A frozen object whose `project({ value, maxChars })` returns `{ text, truncated }`.
+ * @throws TypeError For a negative or non-integer `maxChars`, or a non-synchronous renderer;
+ *   a `CONTEXT_BUDGET` `ValidationError` from the budget check when even the fallback is long.
+ */
 export declare function defineContentProjection(options: ContentProjectionOptions): Readonly<{
-    project: ({ value, maxChars: limit }: {
+    project: ({ value, maxChars: limit, }: {
         value: unknown;
         maxChars: number;
     }) => ContentProjection;
 }>;
-/** Binary-search a continuous prefix and keep an existing surrogate pair intact. */
+/**
+ * Project a continuous excerpt of a body by binary-searching the longest prefix that fits.
+ *
+ * Binary-search a continuous prefix and keep an existing surrogate pair intact. `render`
+ * receives the prefix length, not the text, so the caller decides how the excerpt is framed.
+ *
+ * @param body - Source text whose length bounds the search.
+ * @param limit - Maximum rendered length in characters.
+ * @param render - Synchronous renderer for a given prefix length.
+ * @returns The fitting projection, or `undefined` when even the empty excerpt does not fit.
+ * @throws TypeError For an invalid limit or a non-synchronous renderer; a `CONTEXT_BUDGET`
+ *   `ValidationError` when the chosen excerpt still exceeds the budget.
+ */
 export declare function projectContinuousExcerpt(body: string, limit: number, render: (length: number) => string): ContentProjection | undefined;
-/** Traverse synchronously in property/array order; only undefined omits a result. */
+/**
+ * Compile a depth-limited tree transform.
+ *
+ * Traverse synchronously in property/array order; only undefined omits a result. Because a
+ * visitor returns a new value instead of mutating, an omitted branch disappears from arrays
+ * and objects the same way, and `maxDepth` bounds both cycles and cost.
+ *
+ * @param options - Maximum depth (0 keeps only the root), optional omit predicate and optional
+ *   record visitor.
+ * @returns A frozen object whose `visit(value, context)` returns the projected value.
+ * @throws TypeError For a negative or non-integer `maxDepth`; a predicate that is not
+ *   synchronous boolean; a visitor that returns a thenable.
+ */
 export declare function defineTreeProjection<Context>(options: TreeProjectionOptions<Context>): Readonly<{
     visit: (value: unknown, context: Context) => unknown;
 }>;
-export type { ContentProjectionOptions, ContentProjection, TreeProjectionOptions } from '../structs/kits/projection.js';
+export type { ContentProjectionOptions, ContentProjection, TreeProjectionOptions, } from '../structs/kits/projection.js';
+/** Namespace object for callers that prefer one import over named helpers. */
 export declare const Projection: Readonly<{
     defineContentProjection: typeof defineContentProjection;
     projectContinuousExcerpt: typeof projectContinuousExcerpt;