@orkestrel/template 0.0.1

package/dist/src/core/index.d.cts

@@ -0,0 +1,665 @@
+import { ContractShape } from '@orkestrel/contract';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { FieldPath } from '@orkestrel/contract';
+
+/**
+ * Create a template.
+ *
+ * @param options - The template's `name` / `content`, an optional `id`
+ *   (defaults to a generated UUID), `placeholders`, catalog metadata, and
+ *   `missing` / `locale` fill defaults
+ * @returns A working {@link TemplateInterface}
+ *
+ * @example
+ * ```ts
+ * import { createTemplate } from '@src/core'
+ *
+ * const greeting = createTemplate({ name: 'greeting', content: 'Hi {{name}}' })
+ * greeting.fill({ name: 'Ada' }) // 'Hi Ada'
+ * ```
+ */
+export declare function createTemplate(options: TemplateOptions): TemplateInterface;
+
+/**
+ * Create a template registry.
+ *
+ * @param options - Optional initial `templates` seed collection and
+ *   manager-wide `missing` / `locale` fill defaults, emitter `on` hooks, and
+ *   an `error` handler
+ * @returns A working {@link TemplateManagerInterface}
+ *
+ * @example
+ * ```ts
+ * import { createTemplateManager } from '@src/core'
+ *
+ * const templates = createTemplateManager({
+ * 	templates: [{ id: 'greeting', name: 'greeting', content: 'Hi {{name}}' }],
+ * })
+ * templates.fill('greeting', { name: 'Ada' }) // 'Hi Ada'
+ * ```
+ */
+export declare function createTemplateManager(options?: TemplateManagerOptions): TemplateManagerInterface;
+
+/** Default `locale` for `Template#fill` / `TemplateManager#fill` when unspecified. */
+export declare const DEFAULT_LOCALE = "en-US";
+
+/** Default `missing` policy for `Template#fill` / `TemplateManager#fill` when unspecified. */
+export declare const DEFAULT_MISSING_POLICY: MissingPolicy;
+
+/**
+ * The single-pass `{{name}}` substitution pattern shared by `Template#fill`
+ * and `Template#validate`.
+ *
+ * @remarks
+ * Global-flagged, two-alternative pattern: a match of the FIRST alternative
+ * (`\{{` — a literal backslash followed by `{{`) means "emit a literal
+ * `{{`" — the escape hatch for content that must show `{{` without
+ * triggering substitution. A match that instead populates capture group 1
+ * (`\{{([^{}]+?)\}\}`) means "substitute the named token" — group 1 is the
+ * RAW (untrimmed) token text between the braces; every call site trims it
+ * (`token.trim()`) before using it as a lookup name, so `'{{ name }}'` still
+ * resolves `'name'`. The pattern intentionally does NOT wrap the token in
+ * `\s*` — an unclosed `'{{' + ' '.repeat(n)` with no closing `}}` would
+ * otherwise force the regex engine into catastrophic backtracking over the
+ * whitespace run (O(n^2)); trimming after the match keeps the same
+ * whitespace tolerance without the backtracking hazard. Every call site
+ * builds a fresh `RegExp` from `.source` / `.flags` rather than sharing this
+ * instance's mutable `lastIndex` across scans.
+ */
+export declare const FILL_PATTERN: RegExp;
+
+/**
+ * Substitute every `{{name}}` token in `content` in a single pass.
+ *
+ * @remarks
+ * Uses a fresh `RegExp` clone of `FILL_PATTERN` per call (never sharing its
+ * `lastIndex`) and a single `String#replace` scan — substituted output is
+ * never re-scanned. For each token: the matching declared
+ * {@link TemplatePlaceholder} (exact `name`) supplies its `path` (falling
+ * back to the token split on `.`); ANY path segment in `UNSAFE_FIELD_SEGMENTS`
+ * makes the token unresolved without ever calling `resolveField` (a
+ * prototype-pollution guard). A resolved value formats via `formatValue`; an
+ * unresolved value falls back to the placeholder's `fallback` when declared;
+ * otherwise `options.missing` governs — `'literal'` re-emits the original
+ * `{{name}}` text, `'empty'` emits `''`, and `'error'` emits `''` for every
+ * token but collects EVERY unresolved required token (an undeclared token, or
+ * a declared token with `required !== false`) and throws one
+ * {@link TemplateError} coded `MISSING` listing them all, in first-appearance
+ * order, once the scan completes. An escaped `\{{` emits a literal `{{`.
+ *
+ * PARITY: called with no declared `placeholders` and `{ missing: 'empty' }`,
+ * this reproduces `interpolateMessage` (`@src/core` sibling
+ * `interpret`) vector-for-vector. KNOWN DIVERGENCE: `FILL_PATTERN`'s token
+ * class (`[^{}]`) excludes `{`, where `interpolateMessage`'s (`[^}]`) allows
+ * it — a token containing `{` therefore behaves differently here.
+ *
+ * @param content - The template content carrying `{{name}}` tokens
+ * @param values - The values tokens resolve against
+ * @param options - `missing` (default `'error'`), `locale` (default `'en-US'`), and the declared `placeholders` (default none) tokens resolve against
+ * @returns The substituted content
+ *
+ * @example
+ * ```ts
+ * import { fillTemplate } from '@src/core'
+ *
+ * fillTemplate('Hi {{name}}', { name: 'Ada' }) // 'Hi Ada'
+ * fillTemplate('Limit {{limit}}', { limit: 5010 }, { missing: 'empty' }) // 'Limit 5,010'
+ * ```
+ */
+export declare function fillTemplate(content: string, values?: TemplateFillValues, options?: TemplateFillOptions & {
+    readonly placeholders?: readonly TemplatePlaceholder[];
+}): string;
+
+/**
+ * Format a resolved fill value for substitution into a template's `content`.
+ *
+ * @remarks
+ * A finite number renders with the given locale's thousand grouping (via
+ * `toLocaleString`); every other value — including `null` — String-coerces.
+ * `null` therefore renders as the literal string `'null'`, intentionally
+ * mirroring `interpolateMessage`'s coercion parity (see `fillTemplate`). An
+ * invalid BCP-47 `locale` tag throws a `RangeError` from the underlying
+ * `toLocaleString` call when `value` is a finite number — this is a caller
+ * error (an invalid locale argument), by design, and is not caught here.
+ *
+ * @param value - The resolved value to format
+ * @param locale - The locale used for finite-number formatting
+ * @returns The formatted string
+ *
+ * @example
+ * ```ts
+ * import { formatValue } from '@src/core'
+ *
+ * formatValue(5010, 'en-US') // '5,010'
+ * formatValue(null, 'en-US') // 'null'
+ * ```
+ */
+export declare function formatValue(value: unknown, locale: string): string;
+
+/**
+ * Narrow an unknown caught value to a {@link TemplateError}.
+ *
+ * @param value - The value to test (typically a `catch` binding)
+ * @returns `true` when `value` is a {@link TemplateError}
+ *
+ * @example
+ * ```ts
+ * import { isTemplateError } from '@src/core'
+ *
+ * try {
+ * 	manager.template('missing')
+ * } catch (error) {
+ * 	if (isTemplateError(error) && error.code === 'NOTFOUND') return
+ * }
+ * ```
+ */
+export declare function isTemplateError(value: unknown): value is TemplateError;
+
+/**
+ * How {@link TemplateInterface#fill} handles an unresolved required
+ * placeholder.
+ *
+ * @remarks
+ * `error` — throws a {@link TemplateError} coded `MISSING`. `empty` —
+ * substitutes an empty string. `literal` — substitutes the placeholder's own
+ * `{{name}}` token back into the output, unchanged.
+ */
+export declare type MissingPolicy = 'error' | 'empty' | 'literal';
+
+/**
+ * Build the `@orkestrel/contract` object shape describing a template's
+ * declared placeholders.
+ *
+ * @remarks
+ * Each placeholder becomes a `stringShape` carrying its `description`;
+ * `required === false` wraps it in `optionalShape`. Used by `Template` to
+ * compile its `parameters()` contract once per instance.
+ *
+ * @param placeholders - The declared placeholders to shape
+ * @returns The contract shape for `createContract`
+ *
+ * @example
+ * ```ts
+ * import { placeholderShape } from '@src/core'
+ * import { createContract } from '@orkestrel/contract'
+ *
+ * const contract = createContract(placeholderShape([{ name: 'city' }]))
+ * ```
+ */
+export declare function placeholderShape(placeholders: readonly TemplatePlaceholder[]): ContractShape;
+
+/**
+ * Resolve a field path against a fill-values record, refusing any path that
+ * touches a prototype-pollution-unsafe segment.
+ *
+ * @remarks
+ * A prototype-pollution guard shared by `fillTemplate` and `Template#validate`
+ * so the two stay in lockstep: `path` normalizes to a segment array (a bare
+ * string `path` becomes a single-segment array); if ANY segment appears in
+ * `UNSAFE_FIELD_SEGMENTS` (`'__proto__'`, `'constructor'`, `'prototype'`), the
+ * lookup is refused and `undefined` is returned WITHOUT ever calling
+ * `resolveField` — a path like `['__proto__', 'polluted']` can never reach
+ * the record's actual prototype chain through this function. Every other
+ * path resolves through `@orkestrel/contract`'s `resolveField`.
+ *
+ * @param record - The fill-values record to resolve against
+ * @param path - The field path — a single segment or a segment array
+ * @returns The resolved value, or `undefined` when unresolved or the path is unsafe
+ *
+ * @example
+ * ```ts
+ * import { resolveSafeField } from '@src/core'
+ *
+ * resolveSafeField({ a: { b: 1 } }, ['a', 'b']) // 1
+ * resolveSafeField({}, ['__proto__', 'polluted']) // undefined
+ * ```
+ */
+export declare function resolveSafeField(record: TemplateFillValues, path: FieldPath): unknown;
+
+/**
+ * A named, versionable template — `{{name}}` tokens in `content`, filled
+ * against a values record.
+ *
+ * @remarks
+ * `missing` / `locale` seed this instance's default {@link TemplateFillOptions},
+ * overridable per `fill` call. Its `parameters()` contract (built from
+ * `placeholders` via `placeholderShape`) compiles once, in the constructor.
+ *
+ * @example
+ * ```ts
+ * const greeting = new Template({ name: 'greeting', content: 'Hi {{name}}' })
+ * greeting.fill({ name: 'Ada' }) // 'Hi Ada'
+ * ```
+ */
+export declare class Template implements TemplateInterface {
+    #private;
+    readonly id: string;
+    readonly name: string;
+    readonly content: string;
+    readonly placeholders: readonly TemplatePlaceholder[];
+    readonly summary?: string;
+    readonly description?: string;
+    readonly category?: string;
+    readonly tags?: readonly string[];
+    constructor(options: TemplateOptions);
+    /**
+     * The plain, JSON-serializable data this template carries.
+     *
+     * @returns The {@link TemplateDefinition} record
+     *
+     * @example
+     * ```ts
+     * const instance = new Template({ name: 'greeting', content: 'Hi {{name}}' })
+     * instance.definition().name // 'greeting'
+     * ```
+     */
+    definition(): TemplateDefinition;
+    /**
+     * Substitute every `{{name}}` token in `content` against `values`.
+     *
+     * @param values - The values tokens resolve against
+     * @param options - Per-call overrides for this instance's `missing` / `locale` defaults
+     * @returns The substituted content
+     *
+     * @example
+     * ```ts
+     * const instance = new Template({ name: 'greeting', content: 'Hi {{name}}' })
+     * instance.fill({ name: 'Ada' }) // 'Hi Ada'
+     * ```
+     */
+    fill(values?: TemplateFillValues, options?: TemplateFillOptions): string;
+    /**
+     * Report which required placeholders would stay unresolved, and which
+     * `values` keys go unused, without producing output.
+     *
+     * @remarks
+     * Content-token driven: scans `this.content` for every `{{name}}` token
+     * (skipping escaped `\{{` matches) the same way `fill` does, so `validate`
+     * predicts `fill`'s `'error'`-{@link MissingPolicy} outcome exactly — a
+     * token reported here as missing is precisely a token that would throw
+     * under `fill(values, { missing: 'error' })`. For each distinct token
+     * (first-appearance order, trimmed): a declared {@link TemplatePlaceholder}
+     * sharing its `name` supplies `path` (falling back to the token split on
+     * `.`); the value resolves via `resolveSafeField`. The token is `missing`
+     * only when the value is unresolved AND no `fallback` is declared AND the
+     * placeholder is required (`required !== false`, including undeclared
+     * tokens). `extra` lists every `values` key with no declared placeholder.
+     *
+     * @param values - The values to check
+     * @returns The {@link TemplateValidationResult}
+     *
+     * @example
+     * ```ts
+     * const instance = new Template({
+     * 	name: 'greeting',
+     * 	content: 'Hi {{name}}',
+     * 	placeholders: [{ name: 'name' }],
+     * })
+     * instance.validate({}).missing // ['name']
+     * ```
+     */
+    validate(values?: TemplateFillValues): TemplateValidationResult;
+    /**
+     * Project this template's placeholders to the open tool-parameters record
+     * shape.
+     *
+     * @returns The compiled parameters record, or `undefined` when `schemaToParameters` yields none
+     *
+     * @example
+     * ```ts
+     * const instance = new Template({
+     * 	name: 'greeting',
+     * 	content: 'Hi {{name}}',
+     * 	placeholders: [{ name: 'name' }],
+     * })
+     * instance.parameters()
+     * ```
+     */
+    parameters(): Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * A named, versionable template record — pure data, no behavior.
+ *
+ * @remarks
+ * `content` is the raw string carrying `{{name}}` tokens (see
+ * `FILL_PATTERN` in `constants.ts`); `placeholders` declares every token's
+ * lookup rule. `summary` / `description` / `category` / `tags` are optional
+ * catalog metadata for `TemplateManagerInterface#find`.
+ */
+export declare interface TemplateDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly content: string;
+    readonly placeholders: readonly TemplatePlaceholder[];
+    readonly summary?: string;
+    readonly description?: string;
+    readonly category?: string;
+    readonly tags?: readonly string[];
+}
+
+/**
+ * An error thrown by the template layer.
+ *
+ * @remarks
+ * Thrown for: a required placeholder staying unresolved under the `error`
+ * {@link MissingPolicy} (`MISSING`), an unknown template id
+ * (`NOTFOUND`), `createTemplate` handed invalid data (`INVALID`), and
+ * `TemplateManagerInterface#register` handed an id already present without
+ * `options.replace` (`CONFLICT`). `context`, when present, carries the
+ * offending id / name.
+ */
+export declare class TemplateError extends Error {
+    readonly code: TemplateErrorCode;
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(code: TemplateErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * Coded misuse / failure conditions thrown as a {@link TemplateError}.
+ *
+ * @remarks
+ * `MISSING` — a required placeholder stayed unresolved under the `error`
+ * {@link MissingPolicy}. `NOTFOUND` — `TemplateManagerInterface#template`
+ * (or `fill` / `validate` / `parameters` by id) was handed an unknown id.
+ * `INVALID` — `createTemplate` was handed data that fails validation.
+ * `CONFLICT` — `register` was handed an id already present without
+ * `options.replace`.
+ */
+export declare type TemplateErrorCode = 'MISSING' | 'NOTFOUND' | 'INVALID' | 'CONFLICT';
+
+/** Per-call options for `TemplateInterface#fill` / `TemplateManagerInterface#fill`. */
+export declare interface TemplateFillOptions {
+    readonly missing?: MissingPolicy;
+    readonly locale?: string;
+}
+
+/** The values a {@link TemplateInterface#fill} / `#validate` call resolves placeholders against. */
+export declare type TemplateFillValues = Readonly<Record<string, unknown>>;
+
+/**
+ * The template contract (AGENTS §22 — exact bijection with `Template`).
+ *
+ * @remarks
+ * `definition` returns the plain {@link TemplateDefinition} data. `fill`
+ * substitutes every `{{name}}` token in `content` against `values`,
+ * honoring `options.missing` for unresolved required placeholders. `validate`
+ * reports which required placeholders are unresolved (`missing`) and which
+ * supplied `values` keys are unused (`extra`) without producing output.
+ * `parameters` projects this template's placeholders to the open
+ * tool-parameters record shape (`schemaToParameters`'s return type from
+ * `@orkestrel/contract`).
+ */
+export declare interface TemplateInterface {
+    readonly id: string;
+    readonly name: string;
+    readonly content: string;
+    readonly placeholders: readonly TemplatePlaceholder[];
+    readonly summary?: string;
+    readonly description?: string;
+    readonly category?: string;
+    readonly tags?: readonly string[];
+    definition(): TemplateDefinition;
+    fill(values?: TemplateFillValues, options?: TemplateFillOptions): string;
+    validate(values?: TemplateFillValues): TemplateValidationResult;
+    parameters(): Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * The template registry — a self-owning, id-keyed record-holder for the
+ * {@link TemplateInterface} instances a consumer registers, looks up, fills,
+ * and validates by id (AGENTS §9.1 singular/plural accessors, §9.2 batch
+ * `remove` overloads, §13 emitter ownership).
+ *
+ * @remarks
+ * `register` accepts either a constructed {@link TemplateInterface} (kept
+ * as-is, including its own `missing` / `locale` defaults) or a plain
+ * {@link TemplateOptions} bag — constructed into a `Template` with this
+ * manager's `missing` / `locale` defaults applied wherever the bag omits
+ * them. A duplicate `id` throws a {@link TemplateError} coded `CONFLICT`
+ * unless `options.replace` is `true`, in which case the existing entry is
+ * overwritten. `options.templates` SEEDS the registry at construction
+ * WITHOUT emitting `register` — only calls to `register` after construction
+ * emit. The batch `remove(ids)` form is ALL-OR-NOTHING: any id absent from
+ * the registry leaves the collection untouched and returns `false`.
+ *
+ * @example
+ * ```ts
+ * import { TemplateManager } from '@src/core'
+ *
+ * const manager = new TemplateManager()
+ * const instance = manager.register({ name: 'greeting', content: 'Hi {{name}}' })
+ * manager.fill(instance.id, { name: 'Ada' }) // 'Hi Ada'
+ * ```
+ */
+export declare class TemplateManager implements TemplateManagerInterface {
+    #private;
+    constructor(options?: TemplateManagerOptions);
+    get emitter(): EmitterInterface<TemplateManagerEventMap>;
+    get size(): number;
+    /**
+     * Register a template — a constructed {@link TemplateInterface} (kept
+     * as-is) or a plain {@link TemplateOptions} bag (constructed into a
+     * `Template` with this manager's `missing` / `locale` defaults applied
+     * wherever the bag omits them).
+     *
+     * @param template - The template instance or options to register
+     * @param options - `replace` — overwrite an existing entry sharing the same id instead of throwing
+     * @returns The registered {@link TemplateInterface}
+     *
+     * @example
+     * ```ts
+     * const instance = manager.register({ id: 'greeting', name: 'greeting', content: 'Hi {{name}}' })
+     * ```
+     */
+    register(template: TemplateInterface | TemplateOptions, options?: {
+        readonly replace?: boolean;
+    }): TemplateInterface;
+    /**
+     * Look up a registered template by id.
+     *
+     * @param id - The template id
+     * @returns The registered {@link TemplateInterface}
+     * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+         */
+     template(id: string): TemplateInterface;
+     /**
+      * List every registered template.
+      *
+      * @returns A snapshot array of every registered {@link TemplateInterface}
+      */
+     templates(): readonly TemplateInterface[];
+     /**
+      * Filter registered templates by name / category / tag — every supplied
+      * field must match (logical AND).
+      *
+      * @param query - The {@link TemplateQuery} to filter by; omit for every registered template
+      * @returns The matching templates
+      */
+     find(query?: TemplateQuery): readonly TemplateInterface[];
+     /**
+      * Test whether a template id is registered.
+      *
+      * @param id - The template id
+      * @returns `true` when `id` is registered
+      */
+     has(id: string): boolean;
+     /**
+      * Remove one, several, or every registered template (AGENTS §9.2 batch
+      * overloads) — array overload declared first so a list resolves to the
+      * batch form.
+      *
+      * @remarks
+      * `remove()` removes every registered template, emitting `remove` once per
+      * instance. `remove(id)` removes one template by id, emitting `remove` and
+      * returning `true` when it existed, `false` otherwise. `remove(ids)` is
+      * ALL-OR-NOTHING: if any id in the list is unregistered, the collection is
+      * left untouched and `false` is returned; otherwise every listed template
+      * is removed (each emitting `remove`) and `true` is returned.
+      *
+      * @param target - Omit to remove all, a single id, or a list of ids
+      * @returns `boolean` for the single-id / list-of-ids forms; `void` for the remove-all form
+      */
+     remove(ids: readonly string[]): boolean;
+     remove(id: string): boolean;
+     remove(): void;
+     /** Remove every registered template, emitting `clear`. */
+     clear(): void;
+     /**
+      * Fill a registered template by id.
+      *
+      * @param id - The template id
+      * @param values - The values tokens resolve against
+      * @param options - Per-call overrides for the template's `missing` / `locale` defaults
+      * @returns The substituted content
+      * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+          */
+      fill(id: string, values?: TemplateFillValues, options?: TemplateFillOptions): string;
+      /**
+       * Validate values against a registered template by id.
+       *
+       * @param id - The template id
+       * @param values - The values to check
+       * @returns The {@link TemplateValidationResult}
+       * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+           */
+       validate(id: string, values?: TemplateFillValues): TemplateValidationResult;
+       /**
+        * Project a registered template's parameters by id.
+        *
+        * @param id - The template id
+        * @returns The compiled parameters record, or `undefined` when the template has none
+        * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+            */
+        parameters(id: string): Readonly<Record<string, unknown>> | undefined;
+       }
+
+       /**
+        * The push observation surface of a {@link TemplateManagerInterface} (AGENTS
+        * §13) — an id-keyed registry, so `register` / `remove` are the events
+        * (never ordered-list `append`/`prepend`).
+        */
+       export declare type TemplateManagerEventMap = {
+           /** A template was registered — carries the registered template. */
+           readonly register: readonly [template: TemplateInterface];
+           /** A template was removed — carries the removed template. */
+           readonly remove: readonly [template: TemplateInterface];
+           /** The registry was cleared. */
+           readonly clear: readonly [];
+       };
+
+       /**
+        * The template registry — a self-owning, id-keyed record-holder (AGENTS §9.1
+        * singular/plural accessors, §9.2 batch overloads).
+        *
+        * @remarks
+        * `register` accepts either a constructed {@link TemplateInterface} or a
+        * plain {@link TemplateOptions} bag (constructed internally), and throws a
+        * {@link TemplateError} coded `CONFLICT` when the id already exists unless
+        * `options.replace` is `true`. `template` throws `NOTFOUND` for an unknown
+        * id. `remove`'s batch form is all-or-nothing: any missing id in the list
+        * leaves the collection untouched and returns `false`.
+        */
+       export declare interface TemplateManagerInterface {
+           readonly emitter: EmitterInterface<TemplateManagerEventMap>;
+           readonly size: number;
+           register(template: TemplateInterface | TemplateOptions, options?: {
+               readonly replace?: boolean;
+           }): TemplateInterface;
+           template(id: string): TemplateInterface;
+           templates(): readonly TemplateInterface[];
+           find(query?: TemplateQuery): readonly TemplateInterface[];
+           has(id: string): boolean;
+           remove(ids: readonly string[]): boolean;
+           remove(id: string): boolean;
+           remove(): void;
+           clear(): void;
+           fill(id: string, values?: TemplateFillValues, options?: TemplateFillOptions): string;
+           validate(id: string, values?: TemplateFillValues): TemplateValidationResult;
+           parameters(id: string): Readonly<Record<string, unknown>> | undefined;
+       }
+
+       /**
+        * Options for `createTemplateManager` / the `TemplateManager` constructor.
+        *
+        * @remarks
+        * `templates` seeds the registry — either constructed {@link TemplateInterface}
+        * instances or plain {@link TemplateOptions} bags. `missing` / `locale` are
+        * the manager-wide default {@link TemplateFillOptions}, overridable per-call.
+        * `on` — initial event listeners (AGENTS §8/§13). `error` — the emitter's
+        * listener-error handler.
+        */
+       export declare interface TemplateManagerOptions {
+           readonly templates?: readonly (TemplateInterface | TemplateOptions)[];
+           readonly missing?: MissingPolicy;
+           readonly locale?: string;
+           readonly on?: EmitterHooks<TemplateManagerEventMap>;
+           readonly error?: EmitterErrorHandler;
+       }
+
+       /**
+        * Options for `createTemplate` / the `Template` constructor.
+        *
+        * @remarks
+        * `id` defaults to a generated id when omitted. `placeholders` defaults to
+        * an empty list. `missing` / `locale` seed the instance's default
+        * {@link TemplateFillOptions}, overridable per-call.
+        */
+       export declare interface TemplateOptions {
+           readonly id?: string;
+           readonly name: string;
+           readonly content: string;
+           readonly placeholders?: readonly TemplatePlaceholder[];
+           readonly summary?: string;
+           readonly description?: string;
+           readonly category?: string;
+           readonly tags?: readonly string[];
+           readonly missing?: MissingPolicy;
+           readonly locale?: string;
+       }
+
+       /**
+        * One placeholder a {@link TemplateDefinition}'s `content` declares — its
+        * lookup name, an optional field path into the values record, whether it is
+        * required, and a literal fallback.
+        *
+        * @remarks
+        * `name` is the `{{name}}` token as written in `content`. `path`, when
+        * present, resolves the fill value through a (possibly nested)
+        * {@link FieldPath} rather than a flat `name` lookup on the values record.
+        * `required` defaults to `true` when omitted — an unresolved required
+        * placeholder is governed by the active {@link MissingPolicy}. `fallback` is
+        * a literal substituted when the value is unresolved, regardless of
+        * `required`.
+        */
+       export declare interface TemplatePlaceholder {
+           readonly name: string;
+           readonly path?: FieldPath;
+           readonly required?: boolean;
+           readonly fallback?: unknown;
+           readonly description?: string;
+       }
+
+       /** A query for `TemplateManagerInterface#find` — every supplied field must match. */
+       export declare interface TemplateQuery {
+           readonly name?: string;
+           readonly category?: string;
+           readonly tag?: string;
+       }
+
+       /** The outcome of `TemplateInterface#validate` — which required placeholders are unresolved, and which supplied values are unused. */
+       export declare interface TemplateValidationResult {
+           readonly valid: boolean;
+           readonly missing: readonly string[];
+           readonly extra: readonly string[];
+       }
+
+       /**
+        * Prototype-pollution-unsafe field-path segments — a fill lookup refuses to
+        * resolve ANY path containing one, treating the placeholder as unresolved.
+        */
+       export declare const UNSAFE_FIELD_SEGMENTS: readonly string[];
+
+       export { }