@fgv/ts-extras 5.1.0-55 → 5.1.0-56

package/lib/packlets/ai-assist/usageNormalization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageNormalization.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/usageNormalization.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Per-wire-shape `usage` block normalization, shared by the non-streaming\n * adapters (`completionClient.ts`) and the streaming adapters\n * (`streamingAdapters/*.ts`) so the same JSON layout is parsed once.\n *\n * @remarks\n * Every function here follows one rule throughout: a field that is absent\n * from the wire response stays absent on {@link AiAssist.IAiCompletionUsage} —\n * never defaulted to `0`, and never derived from a sibling field unless the\n * value that sibling would need is itself known. See `IAiCompletionUsage`\n * for why.\n * @packageDocumentation\n */\n\n/* eslint-disable @typescript-eslint/naming-convention -- wire field names are snake_case */\n\nimport { type JsonObject } from '@fgv/ts-json-base';\nimport { type Validator, Validators } from '@fgv/ts-utils';\n\nimport { type AiCacheReportingLevel, type IAiCompletionUsage } from './usageTypes';\n\n// ============================================================================\n// Anthropic Messages\n// ============================================================================\n\n/** @internal */\ninterface IAnthropicRawUsage {\n  readonly input_tokens: number;\n  readonly output_tokens?: number;\n  readonly cache_creation_input_tokens?: number;\n  readonly cache_read_input_tokens?: number;\n}\n\nconst anthropicRawUsage: Validator<IAnthropicRawUsage> = Validators.object<IAnthropicRawUsage>({\n  input_tokens: Validators.number,\n  output_tokens: Validators.number.optional(),\n  cache_creation_input_tokens: Validators.number.optional(),\n  cache_read_input_tokens: Validators.number.optional()\n});\n\n/**\n * Normalizes an Anthropic Messages API `usage` block. Anthropic always\n * reports both reads and writes, so `reports` is unconditionally\n * `'reads-and-writes'` — an absent `cache_creation_input_tokens` genuinely\n * means zero tokens were written this request.\n * @internal\n */\nexport function normalizeAnthropicUsage(raw: JsonObject | undefined): IAiCompletionUsage | undefined {\n  if (raw === undefined) {\n    return undefined;\n  }\n  const parsed = anthropicRawUsage.validate(raw);\n  if (parsed.isFailure()) {\n    return undefined;\n  }\n  const {\n    input_tokens: uncachedInputTokens,\n    output_tokens: outputTokens,\n    cache_creation_input_tokens: cacheWriteTokens,\n    cache_read_input_tokens: cachedInputTokens\n  } = parsed.value;\n  return {\n    reports: 'reads-and-writes',\n    uncachedInputTokens,\n    cachedInputTokens,\n    cacheWriteTokens,\n    outputTokens,\n    totalInputTokens: cachedInputTokens !== undefined ? uncachedInputTokens + cachedInputTokens : undefined,\n    raw\n  };\n}\n\n// ============================================================================\n// OpenAI / xAI Chat Completions\n// ============================================================================\n\n/** @internal */\ninterface IOpenAiChatPromptTokensDetails {\n  readonly cached_tokens?: number;\n}\n\nconst openAiChatPromptTokensDetails: Validator<IOpenAiChatPromptTokensDetails> =\n  Validators.object<IOpenAiChatPromptTokensDetails>({ cached_tokens: Validators.number.optional() });\n\n/** @internal */\ninterface IOpenAiChatRawUsage {\n  readonly prompt_tokens?: number;\n  readonly completion_tokens?: number;\n  readonly prompt_tokens_details?: IOpenAiChatPromptTokensDetails;\n}\n\nconst openAiChatRawUsage: Validator<IOpenAiChatRawUsage> = Validators.object<IOpenAiChatRawUsage>({\n  prompt_tokens: Validators.number.optional(),\n  completion_tokens: Validators.number.optional(),\n  prompt_tokens_details: openAiChatPromptTokensDetails.optional()\n});\n\n/**\n * Normalizes an OpenAI/xAI Chat Completions `usage` block. `reports` is\n * unconditionally `'reads'`: `cache_write_tokens` does not exist on this API\n * for any provider reached through it, so `cacheWriteTokens` is never set —\n * not even to `0`.\n * @internal\n */\nexport function normalizeOpenAiChatUsage(raw: JsonObject | undefined): IAiCompletionUsage | undefined {\n  if (raw === undefined) {\n    return undefined;\n  }\n  const parsed = openAiChatRawUsage.validate(raw);\n  if (parsed.isFailure()) {\n    return undefined;\n  }\n  const {\n    prompt_tokens: promptTokens,\n    completion_tokens: outputTokens,\n    prompt_tokens_details\n  } = parsed.value;\n  const cachedInputTokens = prompt_tokens_details?.cached_tokens;\n  const uncachedInputTokens =\n    cachedInputTokens !== undefined && promptTokens !== undefined\n      ? promptTokens - cachedInputTokens\n      : undefined;\n  return {\n    reports: 'reads',\n    uncachedInputTokens,\n    cachedInputTokens,\n    outputTokens,\n    totalInputTokens:\n      uncachedInputTokens !== undefined && cachedInputTokens !== undefined\n        ? uncachedInputTokens + cachedInputTokens\n        : undefined,\n    raw\n  };\n}\n\n// ============================================================================\n// OpenAI / xAI Responses\n// ============================================================================\n\n/** @internal */\ninterface IOpenAiResponsesInputTokensDetails {\n  readonly cached_tokens?: number;\n  readonly cache_write_tokens?: number;\n}\n\nconst openAiResponsesInputTokensDetails: Validator<IOpenAiResponsesInputTokensDetails> =\n  Validators.object<IOpenAiResponsesInputTokensDetails>({\n    cached_tokens: Validators.number.optional(),\n    cache_write_tokens: Validators.number.optional()\n  });\n\n/** @internal */\ninterface IOpenAiResponsesRawUsage {\n  readonly input_tokens?: number;\n  readonly output_tokens?: number;\n  readonly input_tokens_details?: IOpenAiResponsesInputTokensDetails;\n}\n\nconst openAiResponsesRawUsage: Validator<IOpenAiResponsesRawUsage> =\n  Validators.object<IOpenAiResponsesRawUsage>({\n    input_tokens: Validators.number.optional(),\n    output_tokens: Validators.number.optional(),\n    input_tokens_details: openAiResponsesInputTokensDetails.optional()\n  });\n\n/**\n * Normalizes an OpenAI/xAI Responses API `usage` block. This route is shared\n * by two providers that disagree about write reporting — OpenAI always sends\n * `cache_write_tokens` (even when `0`), xAI never does — so `reports` is\n * derived from field **presence**, not from provider identity: a wire that\n * sends the field, however small its value, is `'reads-and-writes'`; a wire\n * that omits it entirely is `'reads'`.\n * @internal\n */\nexport function normalizeOpenAiResponsesUsage(raw: JsonObject | undefined): IAiCompletionUsage | undefined {\n  if (raw === undefined) {\n    return undefined;\n  }\n  const parsed = openAiResponsesRawUsage.validate(raw);\n  if (parsed.isFailure()) {\n    return undefined;\n  }\n  const { input_tokens: inputTokens, output_tokens: outputTokens, input_tokens_details } = parsed.value;\n  const cachedInputTokens = input_tokens_details?.cached_tokens;\n  const cacheWriteTokens = input_tokens_details?.cache_write_tokens;\n  const reports: AiCacheReportingLevel = cacheWriteTokens !== undefined ? 'reads-and-writes' : 'reads';\n  const uncachedInputTokens =\n    cachedInputTokens !== undefined && inputTokens !== undefined\n      ? inputTokens - cachedInputTokens\n      : undefined;\n  return {\n    reports,\n    uncachedInputTokens,\n    cachedInputTokens,\n    cacheWriteTokens,\n    outputTokens,\n    totalInputTokens:\n      uncachedInputTokens !== undefined && cachedInputTokens !== undefined\n        ? uncachedInputTokens + cachedInputTokens\n        : undefined,\n    raw\n  };\n}\n\n// ============================================================================\n// Gemini generateContent / streamGenerateContent\n// ============================================================================\n\n/** @internal */\ninterface IGeminiRawUsage {\n  readonly promptTokenCount?: number;\n  readonly candidatesTokenCount?: number;\n  readonly cachedContentTokenCount?: number;\n}\n\nconst geminiRawUsage: Validator<IGeminiRawUsage> = Validators.object<IGeminiRawUsage>({\n  promptTokenCount: Validators.number.optional(),\n  candidatesTokenCount: Validators.number.optional(),\n  cachedContentTokenCount: Validators.number.optional()\n});\n\n/**\n * Normalizes a Gemini `usageMetadata` block. `reports` is unconditionally\n * `'reads'` — Gemini has no cache-write concept in a `generateContent` call;\n * writes happen out-of-band via the explicit `cachedContents` resource,\n * out of scope per the design (§10).\n *\n * @remarks\n * The Gemini-specific footgun: `promptTokenCount` already **includes**\n * `cachedContentTokenCount` (it is the total effective prompt size), unlike\n * OpenAI where the cached figure sits in a sub-object alongside a separate\n * total. `uncachedInputTokens` subtracts to correct for it — but only when\n * `cachedContentTokenCount` is itself present, per the module's absent-means-\n * absent rule.\n * @internal\n */\nexport function normalizeGeminiUsage(raw: JsonObject | undefined): IAiCompletionUsage | undefined {\n  if (raw === undefined) {\n    return undefined;\n  }\n  const parsed = geminiRawUsage.validate(raw);\n  if (parsed.isFailure()) {\n    return undefined;\n  }\n  const {\n    promptTokenCount,\n    candidatesTokenCount: outputTokens,\n    cachedContentTokenCount: cachedInputTokens\n  } = parsed.value;\n  const uncachedInputTokens =\n    cachedInputTokens !== undefined && promptTokenCount !== undefined\n      ? promptTokenCount - cachedInputTokens\n      : undefined;\n  return {\n    reports: 'reads',\n    uncachedInputTokens,\n    cachedInputTokens,\n    outputTokens,\n    totalInputTokens:\n      uncachedInputTokens !== undefined && cachedInputTokens !== undefined\n        ? uncachedInputTokens + cachedInputTokens\n        : undefined,\n    raw\n  };\n}\n"]}

package/lib/packlets/ai-assist/usageTypes.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Completion usage types: what a provider's wire shape can report about
+ * prompt-cache reads/writes, and the normalized token accounting built from it.
+ *
+ * @remarks
+ * Its own module rather than part of `model.ts` because it depends on nothing
+ * there — `model.ts` imports it, not the reverse — and because `model.ts` was
+ * at the `max-lines` cap. Same rationale as `structuredOutputTypes.ts`.
+ * @packageDocumentation
+ */
+import { type JsonObject } from '@fgv/ts-json-base';
+/**
+ * What a provider's wire shape is able to report about prompt-cache usage,
+ * given that a usage block was present on the response at all.
+ *
+ * @remarks
+ * `'reads'` — cache reads are reported; cache writes cannot be (either the API
+ * has no write concept, or the field structurally does not exist on this route).
+ * `'reads-and-writes'` — both reads and writes are reported.
+ *
+ * There is deliberately no `'none'` member: "no usage was reported at all" is
+ * already expressed by {@link AiAssist.IAiCompletionResponse.usage} itself
+ * being absent, and a third value here would be a second, reachable-only-via-
+ * bug way to say the same thing — check `usage === undefined`, not a `reports`
+ * value, to detect that case.
+ *
+ * See {@link AiAssist.IAiCompletionUsage.reports} for why this is required
+ * rather than optional.
+ * @public
+ */
+export type AiCacheReportingLevel = 'reads' | 'reads-and-writes';
+/**
+ * Token accounting for a completion, normalized across providers.
+ *
+ * @remarks
+ * Every field but `reports` is best-effort: a provider's wire shape reports
+ * what it reports, and an absent field here means the corresponding wire
+ * field was itself absent — never a guessed zero. See `reports` for the one
+ * exception this rule has to be explicit about.
+ * @public
+ */
+export interface IAiCompletionUsage {
+    /**
+     * What this response's wire shape *can* report about caching.
+     *
+     * @remarks
+     * **Required, not optional.** An optional field would make an absent
+     * `cacheWriteTokens` three-ways ambiguous — no write happened / this API
+     * cannot report writes / a build predating the field — and disambiguating
+     * exactly that is what this field exists for. Under `'reads-and-writes'`, an
+     * absent `cacheWriteTokens` genuinely means zero tokens were written this
+     * request — the actionable signal that a breakpoint did not take. Under
+     * `'reads'` it means the API cannot say, and inferring "zero writes" from it
+     * would be a fabricated fact. Same remedy as
+     * `IAiCompletionResponse.structuredOutput`.
+     */
+    readonly reports: AiCacheReportingLevel;
+    /** Input tokens **not** served from cache. Normalized — see `CAPABILITIES.md` for the per-provider table. */
+    readonly uncachedInputTokens?: number;
+    /** Input tokens served from cache. */
+    readonly cachedInputTokens?: number;
+    /**
+     * Input tokens written to cache.
+     *
+     * @remarks
+     * Two absence cases, disambiguated by `reports` — never by a `0` this field
+     * itself carries:
+     * - **`reports: 'reads-and-writes'` and this field absent** — the wire
+     *   genuinely reported zero tokens written. Treat absence as `0`, not as
+     *   unknown; this is the actionable "the breakpoint did not take" signal.
+     * - **`reports: 'reads'` and this field absent** — the API cannot report
+     *   writes on this route at all (structurally unfillable, e.g. OpenAI/xAI
+     *   Chat Completions). Never defaulted to `0` here — that would fabricate a
+     *   fact the wire never stated.
+     */
+    readonly cacheWriteTokens?: number;
+    /** Generated output tokens. */
+    readonly outputTokens?: number;
+    /** Total input = uncached + cached, when both are known. */
+    readonly totalInputTokens?: number;
+    /** The provider's own usage block, unnormalized, for anything this shape drops. */
+    readonly raw?: JsonObject;
+}
+//# sourceMappingURL=usageTypes.d.ts.map

package/lib/packlets/ai-assist/usageTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageTypes.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/usageTypes.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,kBAAkB,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,6GAA6G;IAC7G,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,sCAAsC;IACtC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,+BAA+B;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,mFAAmF;IACnF,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC;CAC3B"}

package/lib/packlets/ai-assist/usageTypes.js

@@ -0,0 +1,22 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=usageTypes.js.map

package/lib/packlets/ai-assist/usageTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageTypes.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/usageTypes.ts"],"names":[],"mappings":";AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Completion usage types: what a provider's wire shape can report about\n * prompt-cache reads/writes, and the normalized token accounting built from it.\n *\n * @remarks\n * Its own module rather than part of `model.ts` because it depends on nothing\n * there — `model.ts` imports it, not the reverse — and because `model.ts` was\n * at the `max-lines` cap. Same rationale as `structuredOutputTypes.ts`.\n * @packageDocumentation\n */\n\nimport { type JsonObject } from '@fgv/ts-json-base';\n\n/**\n * What a provider's wire shape is able to report about prompt-cache usage,\n * given that a usage block was present on the response at all.\n *\n * @remarks\n * `'reads'` — cache reads are reported; cache writes cannot be (either the API\n * has no write concept, or the field structurally does not exist on this route).\n * `'reads-and-writes'` — both reads and writes are reported.\n *\n * There is deliberately no `'none'` member: \"no usage was reported at all\" is\n * already expressed by {@link AiAssist.IAiCompletionResponse.usage} itself\n * being absent, and a third value here would be a second, reachable-only-via-\n * bug way to say the same thing — check `usage === undefined`, not a `reports`\n * value, to detect that case.\n *\n * See {@link AiAssist.IAiCompletionUsage.reports} for why this is required\n * rather than optional.\n * @public\n */\nexport type AiCacheReportingLevel = 'reads' | 'reads-and-writes';\n\n/**\n * Token accounting for a completion, normalized across providers.\n *\n * @remarks\n * Every field but `reports` is best-effort: a provider's wire shape reports\n * what it reports, and an absent field here means the corresponding wire\n * field was itself absent — never a guessed zero. See `reports` for the one\n * exception this rule has to be explicit about.\n * @public\n */\nexport interface IAiCompletionUsage {\n  /**\n   * What this response's wire shape *can* report about caching.\n   *\n   * @remarks\n   * **Required, not optional.** An optional field would make an absent\n   * `cacheWriteTokens` three-ways ambiguous — no write happened / this API\n   * cannot report writes / a build predating the field — and disambiguating\n   * exactly that is what this field exists for. Under `'reads-and-writes'`, an\n   * absent `cacheWriteTokens` genuinely means zero tokens were written this\n   * request — the actionable signal that a breakpoint did not take. Under\n   * `'reads'` it means the API cannot say, and inferring \"zero writes\" from it\n   * would be a fabricated fact. Same remedy as\n   * `IAiCompletionResponse.structuredOutput`.\n   */\n  readonly reports: AiCacheReportingLevel;\n  /** Input tokens **not** served from cache. Normalized — see `CAPABILITIES.md` for the per-provider table. */\n  readonly uncachedInputTokens?: number;\n  /** Input tokens served from cache. */\n  readonly cachedInputTokens?: number;\n  /**\n   * Input tokens written to cache.\n   *\n   * @remarks\n   * Two absence cases, disambiguated by `reports` — never by a `0` this field\n   * itself carries:\n   * - **`reports: 'reads-and-writes'` and this field absent** — the wire\n   *   genuinely reported zero tokens written. Treat absence as `0`, not as\n   *   unknown; this is the actionable \"the breakpoint did not take\" signal.\n   * - **`reports: 'reads'` and this field absent** — the API cannot report\n   *   writes on this route at all (structurally unfillable, e.g. OpenAI/xAI\n   *   Chat Completions). Never defaulted to `0` here — that would fabricate a\n   *   fact the wire never stated.\n   */\n  readonly cacheWriteTokens?: number;\n  /** Generated output tokens. */\n  readonly outputTokens?: number;\n  /** Total input = uncached + cached, when both are known. */\n  readonly totalInputTokens?: number;\n  /** The provider's own usage block, unnormalized, for anything this shape drops. */\n  readonly raw?: JsonObject;\n}\n"]}

package/lib/packlets/mustache/index.d.ts

@@ -1,3 +1,3 @@
-export { IContextValidationResult, IMissingVariableDetail, IMustacheTemplateOptions, IVariableRef, MustacheEscapeStrategy, MustacheTokenType } from './interfaces';
+export { IContextValidationResult, IMissingVariableDetail, IMustacheTemplateOptions, IRenderedSegment, IRenderedTemplate, IVariableRef, MustacheEscapeStrategy, MustacheTokenType } from './interfaces';
 export { MustacheTemplate } from './mustacheTemplate';
 //# sourceMappingURL=index.d.ts.map

package/lib/packlets/mustache/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/mustache/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,wBAAwB,EACxB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/mustache/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/lib/packlets/mustache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/mustache/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAWH,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nexport {\n  IContextValidationResult,\n  IMissingVariableDetail,\n  IMustacheTemplateOptions,\n  IVariableRef,\n  MustacheEscapeStrategy,\n  MustacheTokenType\n} from './interfaces';\n\nexport { MustacheTemplate } from './mustacheTemplate';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/mustache/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAaH,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nexport {\n  IContextValidationResult,\n  IMissingVariableDetail,\n  IMustacheTemplateOptions,\n  IRenderedSegment,\n  IRenderedTemplate,\n  IVariableRef,\n  MustacheEscapeStrategy,\n  MustacheTokenType\n} from './interfaces';\n\nexport { MustacheTemplate } from './mustacheTemplate';\n"]}

package/lib/packlets/mustache/interfaces.d.ts

@@ -3,6 +3,36 @@
  * @public
  */
 export type MustacheTokenType = 'text' | 'name' | '&' | '#' | '^' | '!' | '>' | '=';
+/**
+ * One contiguous run of the rendered output, attributed to what produced it.
+ * @public
+ */
+export interface IRenderedSegment {
+    /** `'literal'` for template text; `'substitution'` for an interpolated value. */
+    readonly kind: 'literal' | 'substitution';
+    /** Variable name, when `kind` is `'substitution'`. */
+    readonly name?: string;
+    /** Offset into `IRenderedTemplate.text`, in UTF-16 code units. */
+    readonly start: number;
+    /** Length in UTF-16 code units. May be `0` for a variable that rendered empty. */
+    readonly length: number;
+    /** `false` for a triple-stash / `{{&}}` interpolation, which bypasses escaping. */
+    readonly escaped: boolean;
+}
+/**
+ * A render plus the map of which part of the output came from where.
+ * @public
+ */
+export interface IRenderedTemplate {
+    /** The rendered output — identical to what `MustacheTemplate.render` returns. */
+    readonly text: string;
+    /**
+     * Document-ordered, contiguous and gapless: every code unit of `text` belongs to exactly one
+     * segment, so concatenating them reproduces `text` exactly. That identity is verified before
+     * this is returned.
+     */
+    readonly segments: ReadonlyArray<IRenderedSegment>;
+}
 /**
  * Represents a variable reference extracted from a Mustache template.
  * @public

package/lib/packlets/mustache/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../../src/packlets/mustache/interfaces.ts"],"names":[],"mappings":"AAuBA;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,MAAM,GACN,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,CAAC;AAER;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,sBAAsB,EAAE,CAAC;CAC5D;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;AAEnF;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;CACzC"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../../src/packlets/mustache/interfaces.ts"],"names":[],"mappings":"AAuBA;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,MAAM,GACN,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,CAAC;AAER;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc,CAAC;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;CACpD;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,sBAAsB,EAAE,CAAC;CAC5D;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;AAEnF;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;CACzC"}

package/lib/packlets/mustache/interfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../src/packlets/mustache/interfaces.ts"],"names":[],"mappings":";AAAA,8DAA8D;AAC9D;;;;;;;;;;;;;;;;;;;;GAoBG;;AA8JH,oBAAoB","sourcesContent":["/* c8 ignore start - Type definitions only, no runtime code */\n/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Type of a Mustache token as returned by Mustache.parse()\n * @public\n */\nexport type MustacheTokenType =\n  | 'text' // Raw text\n  | 'name' // {{ variable }} - escaped value\n  | '&' // {{{ variable }}} or {{& variable }} - unescaped value\n  | '#' // {{# section }} - section start\n  | '^' // {{^ section }} - inverted section\n  | '!' // {{! comment }} - comment\n  | '>' // {{> partial }} - partial\n  | '='; // {{= =}} - set delimiter\n\n/**\n * Represents a variable reference extracted from a Mustache template.\n * @public\n */\nexport interface IVariableRef {\n  /**\n   * The raw variable name as it appears in the template (e.g., 'user.name')\n   */\n  readonly name: string;\n\n  /**\n   * The path segments parsed from the variable name (e.g., ['user', 'name'])\n   */\n  readonly path: readonly string[];\n\n  /**\n   * The type of token this variable was extracted from\n   */\n  readonly tokenType: MustacheTokenType;\n\n  /**\n   * Whether this variable is used in a section context (# or ^)\n   * Section variables may reference arrays/objects for iteration\n   */\n  readonly isSection: boolean;\n}\n\n/**\n * Details about a missing variable in context validation.\n * @public\n */\nexport interface IMissingVariableDetail {\n  /**\n   * The variable reference that is missing\n   */\n  readonly variable: IVariableRef;\n\n  /**\n   * The path segment where the lookup failed\n   * (e.g., for 'user.profile.name' if 'profile' is missing, this would be 'profile')\n   */\n  readonly failedAtSegment?: string;\n\n  /**\n   * The parent path that exists (e.g., ['user'] if 'user' exists but 'user.profile' does not)\n   */\n  readonly existingPath: readonly string[];\n}\n\n/**\n * Result of context validation, containing details about missing variables.\n * @public\n */\nexport interface IContextValidationResult {\n  /**\n   * Whether the context is valid (has all required variables)\n   */\n  readonly isValid: boolean;\n\n  /**\n   * Variables that are present in the context\n   */\n  readonly presentVariables: readonly string[];\n\n  /**\n   * Variables that are missing from the context\n   */\n  readonly missingVariables: readonly string[];\n\n  /**\n   * Detailed information about each missing variable\n   */\n  readonly missingDetails: readonly IMissingVariableDetail[];\n}\n\n/**\n * Strategy applied to double-brace `{{name}}` tokens at render time.\n *\n * - `'html'`: the standard mustache.js HTML escape (back-compat default).\n * - `'none'`: verbatim passthrough — values are interpolated as-is\n *   (coerced to `String`). Suitable for LLM-prompt rendering and other\n *   non-HTML targets where `& → &` corrupts the output.\n * - `(value) => string`: caller-supplied escape function.\n *\n * Note: triple-brace `{{{name}}}` (and `{{&name}}`) tokens are always\n * rendered unescaped regardless of this strategy — that is the standard\n * mustache.js semantics and is not affected by this option.\n *\n * @public\n */\nexport type MustacheEscapeStrategy = 'html' | 'none' | ((value: string) => string);\n\n/**\n * Options for template parsing and validation.\n * @public\n */\nexport interface IMustacheTemplateOptions {\n  /**\n   * Custom opening and closing tags (default: `['{{', '}}']`)\n   */\n  readonly tags?: readonly [string, string];\n\n  /**\n   * Whether to include comment tokens in variable extraction (default: false)\n   */\n  readonly includeComments?: boolean;\n\n  /**\n   * Whether to include partial references in variable extraction (default: false)\n   */\n  readonly includePartials?: boolean;\n\n  /**\n   * Escape strategy applied to double-brace `{{name}}` tokens at render\n   * time. Default `'html'` preserves the existing mustache.js behavior\n   * (back-compat).\n   *\n   * Pass `'none'` for LLM-prompt or other non-HTML targets where the\n   * default `& → &` escape would corrupt the output. Pass a custom\n   * function for any other escape policy.\n   *\n   * The strategy is applied per-template via a private `Mustache.Writer`\n   * instance; no global state on the `mustache` module is mutated, so\n   * concurrent templates with different strategies are safe.\n   *\n   * Note: triple-brace `{{{name}}}` tokens are always rendered unescaped\n   * regardless of strategy (standard mustache.js semantics).\n   */\n  readonly escape?: MustacheEscapeStrategy;\n}\n\n/**\n * Required version of options with all fields populated.\n * @internal\n */\nexport interface IRequiredMustacheTemplateOptions {\n  readonly tags: [string, string];\n  readonly includeComments: boolean;\n  readonly includePartials: boolean;\n  readonly escape: MustacheEscapeStrategy;\n}\n\n/* c8 ignore stop */\n"]}
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../src/packlets/mustache/interfaces.ts"],"names":[],"mappings":";AAAA,8DAA8D;AAC9D;;;;;;;;;;;;;;;;;;;;GAoBG;;AA8LH,oBAAoB","sourcesContent":["/* c8 ignore start - Type definitions only, no runtime code */\n/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Type of a Mustache token as returned by Mustache.parse()\n * @public\n */\nexport type MustacheTokenType =\n  | 'text' // Raw text\n  | 'name' // {{ variable }} - escaped value\n  | '&' // {{{ variable }}} or {{& variable }} - unescaped value\n  | '#' // {{# section }} - section start\n  | '^' // {{^ section }} - inverted section\n  | '!' // {{! comment }} - comment\n  | '>' // {{> partial }} - partial\n  | '='; // {{= =}} - set delimiter\n\n/**\n * One contiguous run of the rendered output, attributed to what produced it.\n * @public\n */\nexport interface IRenderedSegment {\n  /** `'literal'` for template text; `'substitution'` for an interpolated value. */\n  readonly kind: 'literal' | 'substitution';\n  /** Variable name, when `kind` is `'substitution'`. */\n  readonly name?: string;\n  /** Offset into `IRenderedTemplate.text`, in UTF-16 code units. */\n  readonly start: number;\n  /** Length in UTF-16 code units. May be `0` for a variable that rendered empty. */\n  readonly length: number;\n  /** `false` for a triple-stash / `{{&}}` interpolation, which bypasses escaping. */\n  readonly escaped: boolean;\n}\n\n/**\n * A render plus the map of which part of the output came from where.\n * @public\n */\nexport interface IRenderedTemplate {\n  /** The rendered output — identical to what `MustacheTemplate.render` returns. */\n  readonly text: string;\n  /**\n   * Document-ordered, contiguous and gapless: every code unit of `text` belongs to exactly one\n   * segment, so concatenating them reproduces `text` exactly. That identity is verified before\n   * this is returned.\n   */\n  readonly segments: ReadonlyArray<IRenderedSegment>;\n}\n\n/**\n * Represents a variable reference extracted from a Mustache template.\n * @public\n */\nexport interface IVariableRef {\n  /**\n   * The raw variable name as it appears in the template (e.g., 'user.name')\n   */\n  readonly name: string;\n\n  /**\n   * The path segments parsed from the variable name (e.g., ['user', 'name'])\n   */\n  readonly path: readonly string[];\n\n  /**\n   * The type of token this variable was extracted from\n   */\n  readonly tokenType: MustacheTokenType;\n\n  /**\n   * Whether this variable is used in a section context (# or ^)\n   * Section variables may reference arrays/objects for iteration\n   */\n  readonly isSection: boolean;\n}\n\n/**\n * Details about a missing variable in context validation.\n * @public\n */\nexport interface IMissingVariableDetail {\n  /**\n   * The variable reference that is missing\n   */\n  readonly variable: IVariableRef;\n\n  /**\n   * The path segment where the lookup failed\n   * (e.g., for 'user.profile.name' if 'profile' is missing, this would be 'profile')\n   */\n  readonly failedAtSegment?: string;\n\n  /**\n   * The parent path that exists (e.g., ['user'] if 'user' exists but 'user.profile' does not)\n   */\n  readonly existingPath: readonly string[];\n}\n\n/**\n * Result of context validation, containing details about missing variables.\n * @public\n */\nexport interface IContextValidationResult {\n  /**\n   * Whether the context is valid (has all required variables)\n   */\n  readonly isValid: boolean;\n\n  /**\n   * Variables that are present in the context\n   */\n  readonly presentVariables: readonly string[];\n\n  /**\n   * Variables that are missing from the context\n   */\n  readonly missingVariables: readonly string[];\n\n  /**\n   * Detailed information about each missing variable\n   */\n  readonly missingDetails: readonly IMissingVariableDetail[];\n}\n\n/**\n * Strategy applied to double-brace `{{name}}` tokens at render time.\n *\n * - `'html'`: the standard mustache.js HTML escape (back-compat default).\n * - `'none'`: verbatim passthrough — values are interpolated as-is\n *   (coerced to `String`). Suitable for LLM-prompt rendering and other\n *   non-HTML targets where `& → &amp;` corrupts the output.\n * - `(value) => string`: caller-supplied escape function.\n *\n * Note: triple-brace `{{{name}}}` (and `{{&name}}`) tokens are always\n * rendered unescaped regardless of this strategy — that is the standard\n * mustache.js semantics and is not affected by this option.\n *\n * @public\n */\nexport type MustacheEscapeStrategy = 'html' | 'none' | ((value: string) => string);\n\n/**\n * Options for template parsing and validation.\n * @public\n */\nexport interface IMustacheTemplateOptions {\n  /**\n   * Custom opening and closing tags (default: `['{{', '}}']`)\n   */\n  readonly tags?: readonly [string, string];\n\n  /**\n   * Whether to include comment tokens in variable extraction (default: false)\n   */\n  readonly includeComments?: boolean;\n\n  /**\n   * Whether to include partial references in variable extraction (default: false)\n   */\n  readonly includePartials?: boolean;\n\n  /**\n   * Escape strategy applied to double-brace `{{name}}` tokens at render\n   * time. Default `'html'` preserves the existing mustache.js behavior\n   * (back-compat).\n   *\n   * Pass `'none'` for LLM-prompt or other non-HTML targets where the\n   * default `& → &amp;` escape would corrupt the output. Pass a custom\n   * function for any other escape policy.\n   *\n   * The strategy is applied per-template via a private `Mustache.Writer`\n   * instance; no global state on the `mustache` module is mutated, so\n   * concurrent templates with different strategies are safe.\n   *\n   * Note: triple-brace `{{{name}}}` tokens are always rendered unescaped\n   * regardless of strategy (standard mustache.js semantics).\n   */\n  readonly escape?: MustacheEscapeStrategy;\n}\n\n/**\n * Required version of options with all fields populated.\n * @internal\n */\nexport interface IRequiredMustacheTemplateOptions {\n  readonly tags: [string, string];\n  readonly includeComments: boolean;\n  readonly includePartials: boolean;\n  readonly escape: MustacheEscapeStrategy;\n}\n\n/* c8 ignore stop */\n"]}

package/lib/packlets/mustache/mustacheTemplate.d.ts

@@ -1,5 +1,5 @@
 import { Result } from '@fgv/ts-utils';
-import { IContextValidationResult, IMustacheTemplateOptions, IRequiredMustacheTemplateOptions, IVariableRef } from './interfaces';
+import { IContextValidationResult, IMustacheTemplateOptions, IRequiredMustacheTemplateOptions, IVariableRef, IRenderedTemplate } from './interfaces';
 /**
  * A helper class for working with Mustache templates that provides
  * validation, variable extraction, and context validation utilities.
@@ -63,6 +63,61 @@ export declare class MustacheTemplate {
      * @returns Success with the rendered string, or Failure if rendering fails
      */
     render(context: unknown): Result<string>;
+    /**
+     * Renders the template and reports which part of the output came from where.
+     *
+     * @remarks
+     * The rendered `text` is identical to `render`'s. What is added is
+     * `segments`: a document-ordered, contiguous, gapless attribution of every code unit to either
+     * template literal text or a named interpolation. It answers "what is in this output, in what
+     * order, and how much of it is each part" — a prompt's composition, a generated document's
+     * section sizes, a diff-free view of where a template's bulk actually goes.
+     *
+     * **Offsets are computed during the render, never recovered afterwards.** Recovering them by
+     * searching the output for each substituted value is the obvious shortcut and it is unsound: a
+     * value can occur more than once, can render empty, can be a substring of the surrounding
+     * literal text, and can be altered by escaping between input and output. That failure is silent
+     * and produces plausible offsets, which is the worst property a diagnostic can have.
+     *
+     * **Sections, inverted sections and partials are refused, not approximated.** Their rendered
+     * output is not a linear image of the token order — a section may repeat its body, or omit it —
+     * so a segment list walked from the template would mis-describe the result. Failing names the
+     * construct. Comments and set-delimiter tags emit nothing and are skipped; because each
+     * interpolation is rendered from its already-parsed token rather than from a re-parsed slice of
+     * the template, a set-delimiter tag has no effect on what this produces.
+     *
+     * **Every context value is evaluated exactly once, as `render()` evaluates it.** A lambda in the
+     * context is therefore invoked the same number of times either way, and a context whose lambda
+     * answers differently per call is rendered rather than rejected — the returned `segments` always
+     * describe the returned `text`, whatever that text was. (The concatenation identity is asserted
+     * across every shape in this package's test suite, not re-checked at runtime: re-checking means
+     * a second full render, which is precisely what would double those invocations.)
+     *
+     * @param context - The context object for template rendering.
+     * @returns Success with the rendered text and its segment map, or Failure if the
+     * template contains a construct this cannot describe
+     */
+    renderWithSegments(context: unknown): Result<IRenderedTemplate>;
+    /**
+     * Renders one interpolation token against a prepared lookup context.
+     *
+     * @remarks
+     * Delegates to the same `Writer` primitives `render()` reaches through `renderTokens`, so the
+     * value semantics — dotted paths, lambdas, `null` and `undefined` rendering empty, non-string
+     * coercion — are mustache.js's rather than a reimplementation of them.
+     *
+     * The token is passed as a freshly built `[type, name]` array rather than the parsed span. Both
+     * primitives read only the name, and `@types/mustache` declares the parameter as `string[]`
+     * while a parsed span carries its source offsets as numbers — so handing over the span would
+     * need a cast to work around the typings. Building the pair the primitives actually read needs
+     * none.
+     *
+     * @param type - `'name'` for an escaped interpolation, `'&'` for an unescaped one.
+     * @param name - The interpolation's name (may be a dotted path).
+     * @param lookup - The context to resolve the name against.
+     * @returns The rendered value; empty when the name resolves to `null` or `undefined`.
+     */
+    private _renderInterpolation;
     /**
      * Validates the context and renders the template if validation passes.
      * @param context - The context object to validate and render with

package/lib/packlets/mustache/mustacheTemplate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mustacheTemplate.d.ts","sourceRoot":"","sources":["../../../src/packlets/mustache/mustacheTemplate.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,MAAM,EAAgC,MAAM,eAAe,CAAC;AAGrE,OAAO,EACL,wBAAwB,EAExB,wBAAwB,EACxB,gCAAgC,EAChC,YAAY,EAGb,MAAM,cAAc,CAAC;AAmDtB;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC;;OAEG;IACH,SAAgB,OAAO,EAAE,QAAQ,CAAC,gCAAgC,CAAC,CAAC;IAEpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,UAAU,CAAC,CAA0B;IAE7C,OAAO;IAQP;;;;;OAKG;WACW,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAOpG;;;;;OAKG;WACW,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,MAAM,CAAC,IAAI,CAAC;IAK1F;;;;OAIG;IACI,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC;IAI/B;;;OAGG;IACI,gBAAgB,IAAI,SAAS,YAAY,EAAE;IAOlD;;;OAGG;IACI,oBAAoB,IAAI,SAAS,MAAM,EAAE;IAehD;;;;OAIG;IACI,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,wBAAwB,CAAC;IAmC1E;;;;;;OAMG;IACI,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;IAM/C;;;;OAIG;IACI,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;IAU1D,OAAO,CAAC,MAAM,CAAC,eAAe;IAa9B,OAAO,CAAC,MAAM,CAAC,YAAY;IAO3B,OAAO,CAAC,2BAA2B;IA6CnC,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,WAAW;CAgCpB"}
+{"version":3,"file":"mustacheTemplate.d.ts","sourceRoot":"","sources":["../../../src/packlets/mustache/mustacheTemplate.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,MAAM,EAAgC,MAAM,eAAe,CAAC;AAGrE,OAAO,EACL,wBAAwB,EAExB,wBAAwB,EACxB,gCAAgC,EAChC,YAAY,EAIZ,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAmDtB;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC;;OAEG;IACH,SAAgB,OAAO,EAAE,QAAQ,CAAC,gCAAgC,CAAC,CAAC;IAEpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,UAAU,CAAC,CAA0B;IAE7C,OAAO;IAQP;;;;;OAKG;WACW,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAOpG;;;;;OAKG;WACW,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,MAAM,CAAC,IAAI,CAAC;IAK1F;;;;OAIG;IACI,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC;IAI/B;;;OAGG;IACI,gBAAgB,IAAI,SAAS,YAAY,EAAE;IAOlD;;;OAGG;IACI,oBAAoB,IAAI,SAAS,MAAM,EAAE;IAehD;;;;OAIG;IACI,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,wBAAwB,CAAC;IAmC1E;;;;;;OAMG;IACI,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;IAM/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACI,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,iBAAiB,CAAC;IA0CtE;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;;;OAIG;IACI,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;IAU1D,OAAO,CAAC,MAAM,CAAC,eAAe;IAa9B,OAAO,CAAC,MAAM,CAAC,YAAY;IAO3B,OAAO,CAAC,2BAA2B;IA6CnC,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,WAAW;CAgCpB"}

package/lib/packlets/mustache/mustacheTemplate.js

@@ -185,6 +185,97 @@ class MustacheTemplate {
     render(context) {
         return (0, ts_utils_1.captureResult)(() => this._writer.render(this.template, context, undefined, { escape: this._escapeFn }));
     }
+    /**
+     * Renders the template and reports which part of the output came from where.
+     *
+     * @remarks
+     * The rendered `text` is identical to `render`'s. What is added is
+     * `segments`: a document-ordered, contiguous, gapless attribution of every code unit to either
+     * template literal text or a named interpolation. It answers "what is in this output, in what
+     * order, and how much of it is each part" — a prompt's composition, a generated document's
+     * section sizes, a diff-free view of where a template's bulk actually goes.
+     *
+     * **Offsets are computed during the render, never recovered afterwards.** Recovering them by
+     * searching the output for each substituted value is the obvious shortcut and it is unsound: a
+     * value can occur more than once, can render empty, can be a substring of the surrounding
+     * literal text, and can be altered by escaping between input and output. That failure is silent
+     * and produces plausible offsets, which is the worst property a diagnostic can have.
+     *
+     * **Sections, inverted sections and partials are refused, not approximated.** Their rendered
+     * output is not a linear image of the token order — a section may repeat its body, or omit it —
+     * so a segment list walked from the template would mis-describe the result. Failing names the
+     * construct. Comments and set-delimiter tags emit nothing and are skipped; because each
+     * interpolation is rendered from its already-parsed token rather than from a re-parsed slice of
+     * the template, a set-delimiter tag has no effect on what this produces.
+     *
+     * **Every context value is evaluated exactly once, as `render()` evaluates it.** A lambda in the
+     * context is therefore invoked the same number of times either way, and a context whose lambda
+     * answers differently per call is rendered rather than rejected — the returned `segments` always
+     * describe the returned `text`, whatever that text was. (The concatenation identity is asserted
+     * across every shape in this package's test suite, not re-checked at runtime: re-checking means
+     * a second full render, which is precisely what would double those invocations.)
+     *
+     * @param context - The context object for template rendering.
+     * @returns Success with the rendered text and its segment map, or Failure if the
+     * template contains a construct this cannot describe
+     */
+    renderWithSegments(context) {
+        return (0, ts_utils_1.captureResult)(() => {
+            const segments = [];
+            const lookup = new mustache_1.default.Context(context);
+            let text = '';
+            for (const token of this._tokens) {
+                const type = token[0];
+                if (type === '!' || type === '=') {
+                    continue; // emits nothing
+                }
+                if (type !== 'text' && type !== 'name' && type !== '&') {
+                    throw new Error(`renderWithSegments does not support '${type}' tokens (sections, inverted sections ` +
+                        `and partials render non-linearly, so a segment map walked from the template would ` +
+                        `misdescribe the output). Use render() for this template.`);
+                }
+                const rendered = type === 'text' ? String(token[1]) : this._renderInterpolation(type, String(token[1]), lookup);
+                segments.push(Object.assign(Object.assign({ kind: type === 'text' ? 'literal' : 'substitution' }, (type === 'text' ? {} : { name: String(token[1]) })), { start: text.length, length: rendered.length, escaped: type === 'name' }));
+                text += rendered;
+            }
+            // Deliberately NOT re-rendered and compared against render() here. Such a check did once
+            // catch a real defect, but paying for it means a second full render — which invokes every
+            // lambda in the context a second time, so the check both doubles a caller's side effects
+            // and turns a context whose lambda answers differently per call into a failure on a
+            // template that renders fine. The identity is asserted in the test suite instead, where a
+            // second render costs nobody anything.
+            return { text, segments };
+        });
+    }
+    /**
+     * Renders one interpolation token against a prepared lookup context.
+     *
+     * @remarks
+     * Delegates to the same `Writer` primitives `render()` reaches through `renderTokens`, so the
+     * value semantics — dotted paths, lambdas, `null` and `undefined` rendering empty, non-string
+     * coercion — are mustache.js's rather than a reimplementation of them.
+     *
+     * The token is passed as a freshly built `[type, name]` array rather than the parsed span. Both
+     * primitives read only the name, and `@types/mustache` declares the parameter as `string[]`
+     * while a parsed span carries its source offsets as numbers — so handing over the span would
+     * need a cast to work around the typings. Building the pair the primitives actually read needs
+     * none.
+     *
+     * @param type - `'name'` for an escaped interpolation, `'&'` for an unescaped one.
+     * @param name - The interpolation's name (may be a dotted path).
+     * @param lookup - The context to resolve the name against.
+     * @returns The rendered value; empty when the name resolves to `null` or `undefined`.
+     */
+    _renderInterpolation(type, name, lookup) {
+        const token = [type, name];
+        const value = type === 'name'
+            ? this._writer.escapedValue(token, lookup, { escape: this._escapeFn })
+            : this._writer.unescapedValue(token, lookup);
+        // Both primitives guard with `if (value != null)` and so return `undefined` — never `null` —
+        // for an absent value, which is why only `undefined` is tested here. `renderTokens` appends
+        // nothing in that case and string-coerces everything else.
+        return value === undefined ? '' : String(value);
+    }
     /**
      * Validates the context and renders the template if validation passes.
      * @param context - The context object to validate and render with

package/lib/packlets/mustache/mustacheTemplate.js.map

@@ -1 +1 @@
-{"version":3,"file":"mustacheTemplate.js","sourceRoot":"","sources":["../../../src/packlets/mustache/mustacheTemplate.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, captureResult, fail, succeed } from '@fgv/ts-utils';\nimport Mustache, { EscapeFunction, TemplateSpans, Writer } from 'mustache';\n\nimport {\n  IContextValidationResult,\n  IMissingVariableDetail,\n  IMustacheTemplateOptions,\n  IRequiredMustacheTemplateOptions,\n  IVariableRef,\n  MustacheEscapeStrategy,\n  MustacheTokenType\n} from './interfaces';\n\n/**\n * Default options for MustacheTemplate\n */\nconst DEFAULT_OPTIONS: IRequiredMustacheTemplateOptions = {\n  tags: ['{{', '}}'],\n  includeComments: false,\n  includePartials: false,\n  escape: 'html'\n};\n\n/**\n * HTML entity map matching mustache.js's internal `escapeHtml`. Held\n * locally so the `'html'` escape strategy does not depend on the global\n * `Mustache.escape` (which other packlets — notably `experimental` —\n * mutate at module load and which mustache.js itself defines as\n * mutable). Per-instance escape avoids that shared-state coupling.\n */\nconst HTML_ENTITY_MAP: Readonly<Record<string, string>> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&#39;',\n  '/': '&#x2F;',\n  '`': '&#x60;',\n  '=': '&#x3D;'\n};\n\nconst HTML_ESCAPE: EscapeFunction = (value) =>\n  String(value).replace(/[&<>\"'`=/]/g, (ch) => HTML_ENTITY_MAP[ch]);\n\nconst PASSTHROUGH_ESCAPE: EscapeFunction = (value) => String(value);\n\n/**\n * Resolves a {@link MustacheEscapeStrategy} into the per-render\n * `escape` function understood by `Mustache.Writer.render`. The\n * resolved function is always non-`undefined` so the writer never\n * consults the (mutable, process-global) `Mustache.escape`.\n */\nfunction _resolveEscapeFunction(strategy: MustacheEscapeStrategy): EscapeFunction {\n  if (strategy === 'html') {\n    return HTML_ESCAPE;\n  }\n  if (strategy === 'none') {\n    return PASSTHROUGH_ESCAPE;\n  }\n  return (value) => strategy(String(value));\n}\n\n/**\n * A helper class for working with Mustache templates that provides\n * validation, variable extraction, and context validation utilities.\n * @public\n */\nexport class MustacheTemplate {\n  /**\n   * The original template string\n   */\n  public readonly template: string;\n\n  /**\n   * The options used for parsing this template\n   */\n  public readonly options: Readonly<IRequiredMustacheTemplateOptions>;\n\n  private readonly _tokens: TemplateSpans;\n  private readonly _writer: Writer;\n  private readonly _escapeFn: EscapeFunction;\n  private _variables?: readonly IVariableRef[];\n\n  private constructor(template: string, tokens: TemplateSpans, options: IRequiredMustacheTemplateOptions) {\n    this.template = template;\n    this._tokens = tokens;\n    this.options = options;\n    this._writer = new Mustache.Writer();\n    this._escapeFn = _resolveEscapeFunction(options.escape);\n  }\n\n  /**\n   * Creates a new MustacheTemplate instance.\n   * @param template - The Mustache template string to parse\n   * @param options - Optional parsing options\n   * @returns Success with the template instance, or Failure if parsing fails\n   */\n  public static create(template: string, options?: IMustacheTemplateOptions): Result<MustacheTemplate> {\n    const resolvedOptions = MustacheTemplate._resolveOptions(options);\n    return MustacheTemplate._parseTokens(template, resolvedOptions).onSuccess((tokens) => {\n      return succeed(new MustacheTemplate(template, tokens, resolvedOptions));\n    });\n  }\n\n  /**\n   * Validates that a template string has valid Mustache syntax.\n   * @param template - The template string to validate\n   * @param options - Optional parsing options\n   * @returns Success with true if valid, or Failure with a descriptive error message\n   */\n  public static validate(template: string, options?: IMustacheTemplateOptions): Result<true> {\n    const resolvedOptions = MustacheTemplate._resolveOptions(options);\n    return MustacheTemplate._parseTokens(template, resolvedOptions).onSuccess(() => succeed(true as const));\n  }\n\n  /**\n   * Checks if this template instance has valid syntax.\n   * Always returns Success(true) since parsing succeeded in create().\n   * @returns Success with true\n   */\n  public validate(): Result<true> {\n    return succeed(true as const);\n  }\n\n  /**\n   * Extracts all variable references from the template.\n   * @returns An array of variable references found in the template\n   */\n  public extractVariables(): readonly IVariableRef[] {\n    if (this._variables === undefined) {\n      this._variables = this._extractVariablesFromTokens(this._tokens);\n    }\n    return this._variables;\n  }\n\n  /**\n   * Extracts unique variable names from the template.\n   * @returns An array of unique variable name strings (e.g., ['user.name', 'items'])\n   */\n  public extractVariableNames(): readonly string[] {\n    const variables = this.extractVariables();\n    const seen = new Set<string>();\n    const names: string[] = [];\n\n    for (const variable of variables) {\n      if (!seen.has(variable.name)) {\n        seen.add(variable.name);\n        names.push(variable.name);\n      }\n    }\n\n    return names;\n  }\n\n  /**\n   * Validates that a context object has all required variables.\n   * @param context - The context object to validate\n   * @returns Success with validation result containing details about present/missing variables\n   */\n  public validateContext(context: unknown): Result<IContextValidationResult> {\n    const variables = this.extractVariables();\n    const presentVariables: string[] = [];\n    const missingVariables: string[] = [];\n    const missingDetails: IMissingVariableDetail[] = [];\n    const checked = new Set<string>();\n\n    for (const variable of variables) {\n      if (checked.has(variable.name)) {\n        continue;\n      }\n      checked.add(variable.name);\n\n      const lookup = this._lookupPath(context, variable.path);\n\n      if (lookup.found) {\n        presentVariables.push(variable.name);\n      } else {\n        missingVariables.push(variable.name);\n        missingDetails.push({\n          variable,\n          failedAtSegment: lookup.failedAt,\n          existingPath: lookup.existingPath\n        });\n      }\n    }\n\n    return succeed({\n      isValid: missingVariables.length === 0,\n      presentVariables,\n      missingVariables,\n      missingDetails\n    });\n  }\n\n  /**\n   * Renders the template with the given context.\n   * Use this for pre-validated contexts where you've already checked\n   * that all required variables are present.\n   * @param context - The context object for template rendering\n   * @returns Success with the rendered string, or Failure if rendering fails\n   */\n  public render(context: unknown): Result<string> {\n    return captureResult(() =>\n      this._writer.render(this.template, context, undefined, { escape: this._escapeFn })\n    );\n  }\n\n  /**\n   * Validates the context and renders the template if validation passes.\n   * @param context - The context object to validate and render with\n   * @returns Success with the rendered string, or Failure with validation or render errors\n   */\n  public validateAndRender(context: unknown): Result<string> {\n    return this.validateContext(context).onSuccess((validation) => {\n      if (!validation.isValid) {\n        const missing = validation.missingVariables.join(', ');\n        return fail(`Missing required variables: ${missing}`);\n      }\n      return this.render(context);\n    });\n  }\n\n  private static _resolveOptions(options?: IMustacheTemplateOptions): IRequiredMustacheTemplateOptions {\n    if (options === undefined) {\n      return DEFAULT_OPTIONS;\n    }\n\n    return {\n      tags: options.tags ? [options.tags[0], options.tags[1]] : DEFAULT_OPTIONS.tags,\n      includeComments: options.includeComments ?? DEFAULT_OPTIONS.includeComments,\n      includePartials: options.includePartials ?? DEFAULT_OPTIONS.includePartials,\n      escape: options.escape ?? DEFAULT_OPTIONS.escape\n    };\n  }\n\n  private static _parseTokens(\n    template: string,\n    options: IRequiredMustacheTemplateOptions\n  ): Result<TemplateSpans> {\n    return captureResult(() => Mustache.parse(template, options.tags));\n  }\n\n  private _extractVariablesFromTokens(tokens: TemplateSpans): IVariableRef[] {\n    const variables: IVariableRef[] = [];\n\n    for (const token of tokens) {\n      const type = token[0] as MustacheTokenType;\n      const value = token[1] as string;\n\n      // Skip text tokens\n      if (type === 'text') {\n        continue;\n      }\n\n      // Handle comments based on options\n      if (type === '!' && !this.options.includeComments) {\n        continue;\n      }\n\n      // Handle partials based on options\n      if (type === '>' && !this.options.includePartials) {\n        continue;\n      }\n\n      // Handle variable tokens: 'name', '&', '#', '^', and optionally '!', '>'\n      if (type === 'name' || type === '&' || type === '#' || type === '^' || type === '!' || type === '>') {\n        const isSection = type === '#' || type === '^';\n        variables.push({\n          name: value,\n          path: this._parsePath(value),\n          tokenType: type,\n          isSection\n        });\n      }\n\n      // Recursively extract from nested tokens in sections\n      if ((type === '#' || type === '^') && token.length > 4) {\n        const nestedTokens = token[4] as TemplateSpans;\n        if (nestedTokens) {\n          variables.push(...this._extractVariablesFromTokens(nestedTokens));\n        }\n      }\n    }\n\n    return variables;\n  }\n\n  private _parsePath(name: string): readonly string[] {\n    // Handle special case of '.' which means current context\n    if (name === '.') {\n      return ['.'];\n    }\n\n    // Split on dots to get path segments\n    return name.split('.').filter((segment) => segment.length > 0);\n  }\n\n  private _lookupPath(\n    context: unknown,\n    path: readonly string[]\n  ): { found: boolean; existingPath: string[]; failedAt?: string } {\n    // Handle '.' which always exists if context is not null/undefined\n    if (path.length === 1 && path[0] === '.') {\n      return { found: context !== undefined && context !== null, existingPath: [] };\n    }\n\n    let current: unknown = context;\n    const existingPath: string[] = [];\n\n    for (const segment of path) {\n      if (current === undefined || current === null) {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      if (typeof current !== 'object') {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      const obj = current as Record<string, unknown>;\n      if (!(segment in obj)) {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      current = obj[segment];\n      existingPath.push(segment);\n    }\n\n    return { found: true, existingPath };\n  }\n}\n"]}
+{"version":3,"file":"mustacheTemplate.js","sourceRoot":"","sources":["../../../src/packlets/mustache/mustacheTemplate.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, captureResult, fail, succeed } from '@fgv/ts-utils';\nimport Mustache, { Context, EscapeFunction, TemplateSpans, Writer } from 'mustache';\n\nimport {\n  IContextValidationResult,\n  IMissingVariableDetail,\n  IMustacheTemplateOptions,\n  IRequiredMustacheTemplateOptions,\n  IVariableRef,\n  MustacheEscapeStrategy,\n  MustacheTokenType,\n  IRenderedSegment,\n  IRenderedTemplate\n} from './interfaces';\n\n/**\n * Default options for MustacheTemplate\n */\nconst DEFAULT_OPTIONS: IRequiredMustacheTemplateOptions = {\n  tags: ['{{', '}}'],\n  includeComments: false,\n  includePartials: false,\n  escape: 'html'\n};\n\n/**\n * HTML entity map matching mustache.js's internal `escapeHtml`. Held\n * locally so the `'html'` escape strategy does not depend on the global\n * `Mustache.escape` (which other packlets — notably `experimental` —\n * mutate at module load and which mustache.js itself defines as\n * mutable). Per-instance escape avoids that shared-state coupling.\n */\nconst HTML_ENTITY_MAP: Readonly<Record<string, string>> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&#39;',\n  '/': '&#x2F;',\n  '`': '&#x60;',\n  '=': '&#x3D;'\n};\n\nconst HTML_ESCAPE: EscapeFunction = (value) =>\n  String(value).replace(/[&<>\"'`=/]/g, (ch) => HTML_ENTITY_MAP[ch]);\n\nconst PASSTHROUGH_ESCAPE: EscapeFunction = (value) => String(value);\n\n/**\n * Resolves a {@link MustacheEscapeStrategy} into the per-render\n * `escape` function understood by `Mustache.Writer.render`. The\n * resolved function is always non-`undefined` so the writer never\n * consults the (mutable, process-global) `Mustache.escape`.\n */\nfunction _resolveEscapeFunction(strategy: MustacheEscapeStrategy): EscapeFunction {\n  if (strategy === 'html') {\n    return HTML_ESCAPE;\n  }\n  if (strategy === 'none') {\n    return PASSTHROUGH_ESCAPE;\n  }\n  return (value) => strategy(String(value));\n}\n\n/**\n * A helper class for working with Mustache templates that provides\n * validation, variable extraction, and context validation utilities.\n * @public\n */\nexport class MustacheTemplate {\n  /**\n   * The original template string\n   */\n  public readonly template: string;\n\n  /**\n   * The options used for parsing this template\n   */\n  public readonly options: Readonly<IRequiredMustacheTemplateOptions>;\n\n  private readonly _tokens: TemplateSpans;\n  private readonly _writer: Writer;\n  private readonly _escapeFn: EscapeFunction;\n  private _variables?: readonly IVariableRef[];\n\n  private constructor(template: string, tokens: TemplateSpans, options: IRequiredMustacheTemplateOptions) {\n    this.template = template;\n    this._tokens = tokens;\n    this.options = options;\n    this._writer = new Mustache.Writer();\n    this._escapeFn = _resolveEscapeFunction(options.escape);\n  }\n\n  /**\n   * Creates a new MustacheTemplate instance.\n   * @param template - The Mustache template string to parse\n   * @param options - Optional parsing options\n   * @returns Success with the template instance, or Failure if parsing fails\n   */\n  public static create(template: string, options?: IMustacheTemplateOptions): Result<MustacheTemplate> {\n    const resolvedOptions = MustacheTemplate._resolveOptions(options);\n    return MustacheTemplate._parseTokens(template, resolvedOptions).onSuccess((tokens) => {\n      return succeed(new MustacheTemplate(template, tokens, resolvedOptions));\n    });\n  }\n\n  /**\n   * Validates that a template string has valid Mustache syntax.\n   * @param template - The template string to validate\n   * @param options - Optional parsing options\n   * @returns Success with true if valid, or Failure with a descriptive error message\n   */\n  public static validate(template: string, options?: IMustacheTemplateOptions): Result<true> {\n    const resolvedOptions = MustacheTemplate._resolveOptions(options);\n    return MustacheTemplate._parseTokens(template, resolvedOptions).onSuccess(() => succeed(true as const));\n  }\n\n  /**\n   * Checks if this template instance has valid syntax.\n   * Always returns Success(true) since parsing succeeded in create().\n   * @returns Success with true\n   */\n  public validate(): Result<true> {\n    return succeed(true as const);\n  }\n\n  /**\n   * Extracts all variable references from the template.\n   * @returns An array of variable references found in the template\n   */\n  public extractVariables(): readonly IVariableRef[] {\n    if (this._variables === undefined) {\n      this._variables = this._extractVariablesFromTokens(this._tokens);\n    }\n    return this._variables;\n  }\n\n  /**\n   * Extracts unique variable names from the template.\n   * @returns An array of unique variable name strings (e.g., ['user.name', 'items'])\n   */\n  public extractVariableNames(): readonly string[] {\n    const variables = this.extractVariables();\n    const seen = new Set<string>();\n    const names: string[] = [];\n\n    for (const variable of variables) {\n      if (!seen.has(variable.name)) {\n        seen.add(variable.name);\n        names.push(variable.name);\n      }\n    }\n\n    return names;\n  }\n\n  /**\n   * Validates that a context object has all required variables.\n   * @param context - The context object to validate\n   * @returns Success with validation result containing details about present/missing variables\n   */\n  public validateContext(context: unknown): Result<IContextValidationResult> {\n    const variables = this.extractVariables();\n    const presentVariables: string[] = [];\n    const missingVariables: string[] = [];\n    const missingDetails: IMissingVariableDetail[] = [];\n    const checked = new Set<string>();\n\n    for (const variable of variables) {\n      if (checked.has(variable.name)) {\n        continue;\n      }\n      checked.add(variable.name);\n\n      const lookup = this._lookupPath(context, variable.path);\n\n      if (lookup.found) {\n        presentVariables.push(variable.name);\n      } else {\n        missingVariables.push(variable.name);\n        missingDetails.push({\n          variable,\n          failedAtSegment: lookup.failedAt,\n          existingPath: lookup.existingPath\n        });\n      }\n    }\n\n    return succeed({\n      isValid: missingVariables.length === 0,\n      presentVariables,\n      missingVariables,\n      missingDetails\n    });\n  }\n\n  /**\n   * Renders the template with the given context.\n   * Use this for pre-validated contexts where you've already checked\n   * that all required variables are present.\n   * @param context - The context object for template rendering\n   * @returns Success with the rendered string, or Failure if rendering fails\n   */\n  public render(context: unknown): Result<string> {\n    return captureResult(() =>\n      this._writer.render(this.template, context, undefined, { escape: this._escapeFn })\n    );\n  }\n\n  /**\n   * Renders the template and reports which part of the output came from where.\n   *\n   * @remarks\n   * The rendered `text` is identical to `render`'s. What is added is\n   * `segments`: a document-ordered, contiguous, gapless attribution of every code unit to either\n   * template literal text or a named interpolation. It answers \"what is in this output, in what\n   * order, and how much of it is each part\" — a prompt's composition, a generated document's\n   * section sizes, a diff-free view of where a template's bulk actually goes.\n   *\n   * **Offsets are computed during the render, never recovered afterwards.** Recovering them by\n   * searching the output for each substituted value is the obvious shortcut and it is unsound: a\n   * value can occur more than once, can render empty, can be a substring of the surrounding\n   * literal text, and can be altered by escaping between input and output. That failure is silent\n   * and produces plausible offsets, which is the worst property a diagnostic can have.\n   *\n   * **Sections, inverted sections and partials are refused, not approximated.** Their rendered\n   * output is not a linear image of the token order — a section may repeat its body, or omit it —\n   * so a segment list walked from the template would mis-describe the result. Failing names the\n   * construct. Comments and set-delimiter tags emit nothing and are skipped; because each\n   * interpolation is rendered from its already-parsed token rather than from a re-parsed slice of\n   * the template, a set-delimiter tag has no effect on what this produces.\n   *\n   * **Every context value is evaluated exactly once, as `render()` evaluates it.** A lambda in the\n   * context is therefore invoked the same number of times either way, and a context whose lambda\n   * answers differently per call is rendered rather than rejected — the returned `segments` always\n   * describe the returned `text`, whatever that text was. (The concatenation identity is asserted\n   * across every shape in this package's test suite, not re-checked at runtime: re-checking means\n   * a second full render, which is precisely what would double those invocations.)\n   *\n   * @param context - The context object for template rendering.\n   * @returns Success with the rendered text and its segment map, or Failure if the\n   * template contains a construct this cannot describe\n   */\n  public renderWithSegments(context: unknown): Result<IRenderedTemplate> {\n    return captureResult((): IRenderedTemplate => {\n      const segments: IRenderedSegment[] = [];\n      const lookup = new Mustache.Context(context);\n      let text = '';\n\n      for (const token of this._tokens) {\n        const type = token[0] as MustacheTokenType;\n        if (type === '!' || type === '=') {\n          continue; // emits nothing\n        }\n        if (type !== 'text' && type !== 'name' && type !== '&') {\n          throw new Error(\n            `renderWithSegments does not support '${type}' tokens (sections, inverted sections ` +\n              `and partials render non-linearly, so a segment map walked from the template would ` +\n              `misdescribe the output). Use render() for this template.`\n          );\n        }\n\n        const rendered =\n          type === 'text' ? String(token[1]) : this._renderInterpolation(type, String(token[1]), lookup);\n\n        segments.push({\n          kind: type === 'text' ? 'literal' : 'substitution',\n          ...(type === 'text' ? {} : { name: String(token[1]) }),\n          start: text.length,\n          length: rendered.length,\n          escaped: type === 'name'\n        });\n        text += rendered;\n      }\n\n      // Deliberately NOT re-rendered and compared against render() here. Such a check did once\n      // catch a real defect, but paying for it means a second full render — which invokes every\n      // lambda in the context a second time, so the check both doubles a caller's side effects\n      // and turns a context whose lambda answers differently per call into a failure on a\n      // template that renders fine. The identity is asserted in the test suite instead, where a\n      // second render costs nobody anything.\n      return { text, segments };\n    });\n  }\n\n  /**\n   * Renders one interpolation token against a prepared lookup context.\n   *\n   * @remarks\n   * Delegates to the same `Writer` primitives `render()` reaches through `renderTokens`, so the\n   * value semantics — dotted paths, lambdas, `null` and `undefined` rendering empty, non-string\n   * coercion — are mustache.js's rather than a reimplementation of them.\n   *\n   * The token is passed as a freshly built `[type, name]` array rather than the parsed span. Both\n   * primitives read only the name, and `@types/mustache` declares the parameter as `string[]`\n   * while a parsed span carries its source offsets as numbers — so handing over the span would\n   * need a cast to work around the typings. Building the pair the primitives actually read needs\n   * none.\n   *\n   * @param type - `'name'` for an escaped interpolation, `'&'` for an unescaped one.\n   * @param name - The interpolation's name (may be a dotted path).\n   * @param lookup - The context to resolve the name against.\n   * @returns The rendered value; empty when the name resolves to `null` or `undefined`.\n   */\n  private _renderInterpolation(type: 'name' | '&', name: string, lookup: Context): string {\n    const token: string[] = [type, name];\n    const value =\n      type === 'name'\n        ? this._writer.escapedValue(token, lookup, { escape: this._escapeFn })\n        : this._writer.unescapedValue(token, lookup);\n    // Both primitives guard with `if (value != null)` and so return `undefined` — never `null` —\n    // for an absent value, which is why only `undefined` is tested here. `renderTokens` appends\n    // nothing in that case and string-coerces everything else.\n    return value === undefined ? '' : String(value);\n  }\n\n  /**\n   * Validates the context and renders the template if validation passes.\n   * @param context - The context object to validate and render with\n   * @returns Success with the rendered string, or Failure with validation or render errors\n   */\n  public validateAndRender(context: unknown): Result<string> {\n    return this.validateContext(context).onSuccess((validation) => {\n      if (!validation.isValid) {\n        const missing = validation.missingVariables.join(', ');\n        return fail(`Missing required variables: ${missing}`);\n      }\n      return this.render(context);\n    });\n  }\n\n  private static _resolveOptions(options?: IMustacheTemplateOptions): IRequiredMustacheTemplateOptions {\n    if (options === undefined) {\n      return DEFAULT_OPTIONS;\n    }\n\n    return {\n      tags: options.tags ? [options.tags[0], options.tags[1]] : DEFAULT_OPTIONS.tags,\n      includeComments: options.includeComments ?? DEFAULT_OPTIONS.includeComments,\n      includePartials: options.includePartials ?? DEFAULT_OPTIONS.includePartials,\n      escape: options.escape ?? DEFAULT_OPTIONS.escape\n    };\n  }\n\n  private static _parseTokens(\n    template: string,\n    options: IRequiredMustacheTemplateOptions\n  ): Result<TemplateSpans> {\n    return captureResult(() => Mustache.parse(template, options.tags));\n  }\n\n  private _extractVariablesFromTokens(tokens: TemplateSpans): IVariableRef[] {\n    const variables: IVariableRef[] = [];\n\n    for (const token of tokens) {\n      const type = token[0] as MustacheTokenType;\n      const value = token[1] as string;\n\n      // Skip text tokens\n      if (type === 'text') {\n        continue;\n      }\n\n      // Handle comments based on options\n      if (type === '!' && !this.options.includeComments) {\n        continue;\n      }\n\n      // Handle partials based on options\n      if (type === '>' && !this.options.includePartials) {\n        continue;\n      }\n\n      // Handle variable tokens: 'name', '&', '#', '^', and optionally '!', '>'\n      if (type === 'name' || type === '&' || type === '#' || type === '^' || type === '!' || type === '>') {\n        const isSection = type === '#' || type === '^';\n        variables.push({\n          name: value,\n          path: this._parsePath(value),\n          tokenType: type,\n          isSection\n        });\n      }\n\n      // Recursively extract from nested tokens in sections\n      if ((type === '#' || type === '^') && token.length > 4) {\n        const nestedTokens = token[4] as TemplateSpans;\n        if (nestedTokens) {\n          variables.push(...this._extractVariablesFromTokens(nestedTokens));\n        }\n      }\n    }\n\n    return variables;\n  }\n\n  private _parsePath(name: string): readonly string[] {\n    // Handle special case of '.' which means current context\n    if (name === '.') {\n      return ['.'];\n    }\n\n    // Split on dots to get path segments\n    return name.split('.').filter((segment) => segment.length > 0);\n  }\n\n  private _lookupPath(\n    context: unknown,\n    path: readonly string[]\n  ): { found: boolean; existingPath: string[]; failedAt?: string } {\n    // Handle '.' which always exists if context is not null/undefined\n    if (path.length === 1 && path[0] === '.') {\n      return { found: context !== undefined && context !== null, existingPath: [] };\n    }\n\n    let current: unknown = context;\n    const existingPath: string[] = [];\n\n    for (const segment of path) {\n      if (current === undefined || current === null) {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      if (typeof current !== 'object') {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      const obj = current as Record<string, unknown>;\n      if (!(segment in obj)) {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      current = obj[segment];\n      existingPath.push(segment);\n    }\n\n    return { found: true, existingPath };\n  }\n}\n"]}