@fastpaca/cria 0.0.1 → 1.0.1

package/dist/snapshot.js

@@ -0,0 +1,140 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
+import { markdownRenderer } from "./renderers/markdown";
+/**
+ * Create a deterministic snapshot of a fitted prompt tree.
+ *
+ * - Keeps the tree structure (no flattening) and mirrors PromptElement shape.
+ * - Adds per-node token counts (using renderer.tokenString) and stable hashes.
+ * - Excludes strategy/context from the snapshot; this is for observability only.
+ */
+export function createSnapshot(element, { tokenizer, renderer = markdownRenderer }) {
+    const root = snapshotElement(element, tokenizer, renderer);
+    return {
+        root,
+        totalTokens: root.tokens,
+        hash: root.hash,
+    };
+}
+export function createSnapshotHooks({ tokenizer, renderer, onSnapshot, }) {
+    return {
+        onFitComplete: async (event) => {
+            if (!event.result) {
+                return;
+            }
+            const snapshot = createSnapshot(event.result, {
+                tokenizer,
+                ...(renderer && { renderer }),
+            });
+            await onSnapshot(snapshot);
+        },
+    };
+}
+export function diffSnapshots(before, after) {
+    const added = [];
+    const removed = [];
+    const changed = [];
+    compareNodes(before.root, after.root, [], added, removed, changed);
+    return { added, removed, changed };
+}
+function compareNodes(before, after, path, added, removed, changed) {
+    if (handlePrimitives(before, after, path, added, removed, changed)) {
+        return;
+    }
+    const beforeElement = before;
+    const afterElement = after;
+    recordElementChange(beforeElement, afterElement, path, changed);
+    compareChildren(beforeElement, afterElement, path, added, removed, changed);
+}
+function handlePrimitives(before, after, path, added, removed, changed) {
+    if (typeof before === "string" && typeof after === "string") {
+        if (before !== after) {
+            changed.push({ path, before, after });
+        }
+        return true;
+    }
+    if (typeof before === "string") {
+        removed.push({ path, node: before });
+        added.push({ path, node: after });
+        return true;
+    }
+    if (typeof after === "string") {
+        removed.push({ path, node: before });
+        added.push({ path, node: after });
+        return true;
+    }
+    return false;
+}
+function recordElementChange(before, after, path, changed) {
+    const identityChanged = elementIdentity(before) !== elementIdentity(after);
+    const contentChanged = before.hash !== after.hash || before.tokens !== after.tokens;
+    if (identityChanged || contentChanged) {
+        changed.push({ path, before, after });
+    }
+}
+function compareChildren(before, after, path, added, removed, changed) {
+    const maxChildren = Math.max(before.children.length, after.children.length);
+    for (let i = 0; i < maxChildren; i++) {
+        const beforeChild = before.children[i];
+        const afterChild = after.children[i];
+        const childPath = [...path, i];
+        if (beforeChild === undefined && afterChild !== undefined) {
+            added.push({ path: childPath, node: afterChild });
+            continue;
+        }
+        if (beforeChild !== undefined && afterChild === undefined) {
+            removed.push({ path: childPath, node: beforeChild });
+            continue;
+        }
+        if (beforeChild !== undefined && afterChild !== undefined) {
+            compareNodes(beforeChild, afterChild, childPath, added, removed, changed);
+        }
+    }
+}
+function elementIdentity(element) {
+    return element.id ?? `${element.kind ?? "region"}:${element.priority}`;
+}
+function snapshotElement(element, tokenizer, renderer) {
+    const childSnapshots = element.children.map((child) => typeof child === "string"
+        ? child
+        : snapshotElement(child, tokenizer, renderer));
+    const contentProjection = renderer.tokenString(element);
+    const tokens = tokenizer(contentProjection);
+    const childHashes = childSnapshots.map((child) => typeof child === "string" ? hashString(child) : child.hash);
+    const hasToolId = element.kind === "tool-call" || element.kind === "tool-result";
+    const hash = hashElement({
+        kind: element.kind,
+        priority: element.priority,
+        role: element.kind === "message" ? element.role : undefined,
+        text: element.kind === "reasoning" ? element.text : undefined,
+        toolCallId: hasToolId ? element.toolCallId : undefined,
+        toolName: hasToolId ? element.toolName : undefined,
+        id: element.id,
+        tokens,
+        childHashes,
+    });
+    return {
+        ...element,
+        children: childSnapshots,
+        tokens,
+        hash,
+    };
+}
+function hashElement(input) {
+    const payload = {
+        kind: input.kind ?? "region",
+        priority: input.priority,
+        role: input.role,
+        text: input.text,
+        toolCallId: input.toolCallId,
+        toolName: input.toolName,
+        id: input.id,
+        tokens: input.tokens,
+        children: input.childHashes,
+    };
+    return hashString(JSON.stringify(payload));
+}
+function hashString(value) {
+    return bytesToHex(sha256(utf8ToBytes(value)));
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"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"}

package/dist/snapshot.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=snapshot.test.d.ts.map

package/dist/snapshot.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.test.d.ts","sourceRoot":"","sources":["../src/snapshot.test.tsx"],"names":[],"mappings":""}

package/dist/snapshot.test.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@fastpaca/cria/jsx-runtime";
+import { describe, expect, test } from "vitest";
+import { Omit, Region } from "./components";
+import { render } from "./render";
+import { createSnapshot, createSnapshotHooks, diffSnapshots } from "./snapshot";
+const tokenizer = (text) => text.length;
+const buildBaseTree = () => (_jsxs(Region, { priority: 0, children: ["Intro", _jsx(Region, { priority: 1, children: "Keep" }), _jsx(Omit, { priority: 2, children: "Drop" })] }));
+const buildChangedTree = () => (_jsxs(Region, { priority: 0, children: ["Intro updated", _jsx(Region, { priority: 1, children: "Keep" }), _jsx(Region, { priority: 2, children: "Replace" })] }));
+describe("createSnapshot", () => {
+    test("produces deterministic snapshots for the same input", async () => {
+        const element = await buildBaseTree();
+        const first = await createSnapshot(element, { tokenizer });
+        const second = await createSnapshot(element, { tokenizer });
+        expect(first.hash).toBe(second.hash);
+        expect(first.root).toEqual(second.root);
+        expect(first.totalTokens).toBe(second.totalTokens);
+    });
+    test("hash changes when structural content changes", async () => {
+        const base = await createSnapshot(await buildBaseTree(), { tokenizer });
+        const changed = await createSnapshot(await buildChangedTree(), {
+            tokenizer,
+        });
+        expect(base.hash).not.toBe(changed.hash);
+    });
+});
+describe("diffSnapshots", () => {
+    test("reports changed nodes and no false adds/removals when shapes align", async () => {
+        const base = await createSnapshot(await buildBaseTree(), { tokenizer });
+        const changed = await createSnapshot(await buildChangedTree(), {
+            tokenizer,
+        });
+        const diff = diffSnapshots(base, changed);
+        const changedPaths = diff.changed
+            .map((entry) => entry.path.join("."))
+            .sort();
+        expect(diff.added).toHaveLength(0);
+        expect(diff.removed).toHaveLength(0);
+        expect(changedPaths).toEqual(["", "0", "2", "2.0"]);
+    });
+});
+describe("createSnapshotHooks", () => {
+    test("invokes callback with snapshot on fit complete", async () => {
+        const snapshots = [];
+        const element = (_jsxs(Region, { priority: 0, children: ["A", _jsx(Omit, { priority: 1, children: "BBBB" })] }));
+        const hooks = createSnapshotHooks({
+            tokenizer,
+            onSnapshot: (snapshot) => {
+                snapshots.push(snapshot.hash);
+            },
+        });
+        const result = await render(element, { tokenizer, budget: 1, hooks });
+        expect(result).toBe("A");
+        expect(snapshots).toHaveLength(1);
+    });
+    test("propagates errors from snapshot creation", async () => {
+        const element = _jsx(Region, { priority: 0, children: "Hi" });
+        const hooks = createSnapshotHooks({
+            tokenizer: () => {
+                throw new Error("tokenizer failed");
+            },
+            onSnapshot: () => {
+                throw new Error("callback failed");
+            },
+        });
+        await expect(render(element, { tokenizer, budget: 10, hooks })).rejects.toThrow("tokenizer failed");
+    });
+});
+//# sourceMappingURL=snapshot.test.js.map

package/dist/snapshot.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.test.js","sourceRoot":"","sources":["../src/snapshot.test.tsx"],"names":[],"mappings":"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"}

package/dist/tokenizers.d.ts

@@ -0,0 +1,14 @@
+import type { Tokenizer } from "./types";
+/**
+ * Rough heuristic tokenizer: ~4 characters per token.
+ *
+ * Suitable as a default estimate when no model-specific tokenizer is available.
+ * For accurate budgeting, pass a model-aware tokenizer (e.g. tiktoken).
+ */
+export declare const approximateTokenizer: Tokenizer;
+/**
+ * Best-effort tokenizer using tiktoken. Falls back to approximate if the encoding
+ * is unavailable.
+ */
+export declare function tiktokenTokenizer(modelHint?: string): Tokenizer;
+//# sourceMappingURL=tokenizers.d.ts.map

package/dist/tokenizers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizers.d.ts","sourceRoot":"","sources":["../src/tokenizers.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,SACP,CAAC;AA6B7B;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAO/D"}

package/dist/tokenizers.js

@@ -0,0 +1,45 @@
+import { encodingForModel, getEncoding, } from "js-tiktoken";
+/**
+ * Rough heuristic tokenizer: ~4 characters per token.
+ *
+ * Suitable as a default estimate when no model-specific tokenizer is available.
+ * For accurate budgeting, pass a model-aware tokenizer (e.g. tiktoken).
+ */
+export const approximateTokenizer = (text) => Math.ceil(text.length / 4);
+const tiktokenCache = new Map();
+function getTiktokenEncoder(modelHint) {
+    const cacheKey = modelHint ?? "cl100k_base";
+    const cached = tiktokenCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    try {
+        const encoder = modelHint
+            ? encodingForModel(modelHint)
+            : getEncoding("cl100k_base");
+        tiktokenCache.set(cacheKey, encoder);
+        return encoder;
+    }
+    catch (error) {
+        // Fall through to allow approximate fallback
+        const debugEnv = process.env
+            .DEBUG;
+        if (debugEnv?.includes("cria:tokenizer")) {
+            // eslint-disable-next-line no-console
+            console.warn("Falling back to approximate tokenizer:", error);
+        }
+        return null;
+    }
+}
+/**
+ * Best-effort tokenizer using tiktoken. Falls back to approximate if the encoding
+ * is unavailable.
+ */
+export function tiktokenTokenizer(modelHint) {
+    const encoder = getTiktokenEncoder(modelHint);
+    if (!encoder) {
+        return approximateTokenizer;
+    }
+    return (text) => encoder.encode(text).length;
+}
+//# sourceMappingURL=tokenizers.js.map

package/dist/tokenizers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizers.js","sourceRoot":"","sources":["../src/tokenizers.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,WAAW,GAGZ,MAAM,aAAa,CAAC;AAGrB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAc,CAAC,IAAI,EAAE,EAAE,CACtD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAE7B,MAAM,aAAa,GAAG,IAAI,GAAG,EAAoB,CAAC;AAElD,SAAS,kBAAkB,CAAC,SAAkB;IAC5C,MAAM,QAAQ,GAAG,SAAS,IAAI,aAAa,CAAC;IAC5C,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,SAAS;YACvB,CAAC,CAAC,gBAAgB,CAAC,SAA0B,CAAC;YAC9C,CAAC,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;QAC/B,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,6CAA6C;QAC7C,MAAM,QAAQ,GAAI,OAAO,CAAC,GAA8C;aACrE,KAAK,CAAC;QACT,IAAI,QAAQ,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACzC,sCAAsC;YACtC,OAAO,CAAC,IAAI,CAAC,wCAAwC,EAAE,KAAK,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAkB;IAClD,MAAM,OAAO,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IAED,OAAO,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AACvD,CAAC"}

package/dist/types.d.ts

@@ -1,126 +1,254 @@
+import { z } from "zod";
 /**
- * What can be passed as children to a Cria component.
+ * Message role used by semantic `kind: "message"` regions.
  *
- * Includes all JSX-compatible values: elements, strings, numbers, booleans,
- * null/undefined (ignored), and arrays (flattened). The jsx-runtime normalizes
- * these into `(PromptElement | string)[]` before storing in the element.
- *
- * @example
- * ```tsx
- * <Region>
- *   {"Hello"}
- *   {123}
- *   {items.map(item => <Region>{item}</Region>)}
- * </Region>
- * ```
+ * This is intentionally compatible with common LLM SDKs (system/user/assistant/tool),
+ * while still allowing custom roles for bespoke targets.
+ */
+export declare const PromptRoleSchema: z.ZodString;
+export type PromptRole = z.infer<typeof PromptRoleSchema>;
+/**
+ * A message in a completion request.
+ */
+export interface CompletionMessage {
+    role: PromptRole;
+    content: string;
+}
+/**
+ * Request parameters for a completion.
+ */
+export interface CompletionRequest {
+    /** Messages to send to the model */
+    messages: CompletionMessage[];
+    /** Optional system prompt (some providers handle this separately) */
+    system?: string;
+}
+/**
+ * Result from a completion request.
  */
-export type PromptChildren = PromptElement | string | number | boolean | null | undefined | readonly PromptChildren[];
+export interface CompletionResult {
+    /** The generated text response */
+    text: string;
+}
 /**
- * The core IR node type. All Cria components return a PromptElement.
+ * A model provider that can generate completions.
  *
- * This is the normalized representation after JSX transformation.
- * The render pipeline traverses this tree to produce fragments for fitting.
+ * This abstraction allows Cria components to call AI models without
+ * being coupled to a specific SDK.
+ */
+export interface ModelProvider {
+    /** Provider identifier for debugging */
+    name: string;
+    /**
+     * Tokenizer for this provider's model.
+     *
+     * Used for budget fitting when the caller doesn't pass a tokenizer directly.
+     * Providers should supply an estimate that matches the chosen model; callers
+     * can still override via render options.
+     */
+    tokenizer?: Tokenizer;
+    /**
+     * Generate a completion from the model.
+     */
+    completion(request: CompletionRequest): MaybePromise<CompletionResult>;
+}
+/**
+ * Context that can be provided through the component tree.
  *
- * @property priority - Lower number = higher importance (kept longer during fitting)
- * @property strategy - Optional function to reduce this region when over budget
- * @property id - Optional stable identifier for caching/debugging
- * @property children - Normalized array of child elements and text
+ * Provider components (like `<AISDKProvider>`) inject context that
+ * child components can access during rendering and strategy execution.
+ */
+export interface CriaContext {
+    /** Model provider for AI-powered operations */
+    provider?: ModelProvider | undefined;
+}
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * A function that counts tokens in a string.
+ * Cria doesn't bundle a tokenizer. You provide one.
  *
  * @example
- * ```tsx
- * // Created via JSX:
- * <Region priority={0}>System prompt</Region>
+ * ```typescript
+ * import { encoding_for_model } from "tiktoken";
  *
- * // Produces:
- * { priority: 0, children: ["System prompt"] }
+ * const enc = encoding_for_model("gpt-4");
+ * const tokenizer: Tokenizer = (text) => enc.encode(text).length;
  * ```
  */
-export interface PromptElement {
+export type Tokenizer = (text: string) => number;
+export declare const PromptKindSchema: z.ZodUnion<[z.ZodObject<{
+    kind: z.ZodOptional<z.ZodUndefined>;
+}, "strip", z.ZodTypeAny, {
+    kind?: undefined;
+}, {
+    kind?: undefined;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"message">;
+    role: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "message";
+    role: string;
+}, {
+    kind: "message";
+    role: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool-call">;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    input: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    kind: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    input?: unknown;
+}, {
+    kind: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    input?: unknown;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool-result">;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    output: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    kind: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    output?: unknown;
+}, {
+    kind: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    output?: unknown;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"reasoning">;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "reasoning";
+    text: string;
+}, {
+    kind: "reasoning";
+    text: string;
+}>]>;
+export type PromptKind = z.infer<typeof PromptKindSchema>;
+export type PromptNodeKind = PromptKind["kind"];
+export interface PromptElementBase {
     priority: number;
-    strategy?: Strategy;
-    id?: string;
-    children: (PromptElement | string)[];
+    strategy?: Strategy | undefined;
+    id?: string | undefined;
+    context?: CriaContext | undefined;
+    children: PromptChildren;
 }
+export type PromptElement = (PromptElementBase & {
+    kind?: undefined;
+}) | (PromptElementBase & {
+    kind: "message";
+    role: PromptRole;
+}) | (PromptElementBase & {
+    kind: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}) | (PromptElementBase & {
+    kind: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    output: unknown;
+}) | (PromptElementBase & {
+    kind: "reasoning";
+    text: string;
+});
+export type PromptChild = string | PromptElement;
+export type PromptChildren = PromptChild[];
+export declare const PromptElementSchema: z.ZodType<PromptElement>;
+export declare const PromptChildSchema: z.ZodType<PromptChild>;
+export declare const PromptChildrenSchema: z.ZodType<PromptChildren>;
 /**
- * A flattened text fragment produced by the render pipeline.
+ * A renderer that converts a fitted prompt tree into an output format.
  *
- * The render step walks the PromptElement tree and emits an ordered list of
- * fragments. The fit loop then applies strategies to reduce token count.
+ * Renderers are used for two things:
+ * - **Token accounting / fitting** via `tokenString` (a stable string projection)
+ * - **Final output** via `render` (can be async, and can produce any type)
  *
- * @property content - The text content of this fragment
- * @property tokens - Token count (computed via the provided tokenizer)
- * @property priority - Inherited from the emitting element
- * @property regionId - Stable identifier (from element.id or auto-generated)
- * @property strategy - If present, this fragment can be reduced during fitting
- * @property index - Position in the fragment list (for stable ordering)
+ * @template TOutput - The produced output type (e.g. `string`, `ModelMessage[]`, etc.).
  */
-export interface PromptFragment {
-    content: string;
-    tokens: number;
-    priority: number;
-    regionId: string;
-    strategy?: Strategy;
-    index: number;
+export interface PromptRenderer<TOutput> {
+    /** A short identifier for debugging/observability. */
+    name: string;
+    /**
+     * A deterministic string projection of the prompt tree used for token counting.
+     *
+     * Important properties:
+     * - **Pure / deterministic**: same tree => same string
+     * - **Cheap**: called frequently during fitting
+     * - **Representative**: should correlate with what `render()` produces (especially for string targets)
+     *
+     * For structured targets (e.g. AI SDK messages), this can be a markdown-ish projection
+     * that approximates the effective prompt content for token budgeting.
+     */
+    tokenString: (element: PromptElement) => string;
+    /**
+     * Render the fitted prompt tree to the target output.
+     *
+     * May be async (e.g. when a renderer needs to fetch/resolve attachments, or when
+     * strategies summarized content during fitting).
+     */
+    render: (element: PromptElement) => MaybePromise<TOutput>;
+    /**
+     * The “empty” value for this renderer.
+     *
+     * Used when the budget is <= 0, or when strategies remove the entire tree.
+     */
+    empty: () => TOutput;
 }
 /**
- * A strategy function that reduces a fragment when the prompt is over budget.
- *
- * Strategies are called during the fit loop, starting with the least important
- * priority (highest number). They receive context about the current state and
- * must return replacement fragments (or empty array to remove entirely).
- *
- * Strategies must be:
- * - **Pure**: Don't mutate the input fragments
- * - **Deterministic**: Same input = same output
- * - **Idempotent**: Applying twice has no additional effect
- *
- * @example
- * ```typescript
- * // A strategy that removes the fragment entirely
- * const omitStrategy: Strategy = () => [];
+ * Canonical normalized child node type stored in the IR.
  *
- * // A strategy that truncates from the end
- * const truncateStrategy: Strategy = ({ target, tokenizer }) => {
- *   let content = target.content.slice(0, 100);
- *   return [{ ...target, content, tokens: tokenizer(content) }];
- * };
- * ```
+ * This is the only type you’ll find inside `PromptElement.children` after JSX normalization.
  */
-export type Strategy = (input: StrategyInput) => PromptFragment[];
+export type JsonValue = null | string | number | boolean | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare const JsonValueSchema: z.ZodType<JsonValue>;
+export type StrategyResult = PromptElement | null;
 /**
  * Context passed to strategy functions during the fit loop.
  *
- * @property fragments - All current fragments (readonly, don't mutate)
- * @property target - The specific fragment this strategy should reduce
+ * @property target - The specific region to reduce
  * @property budget - The total token budget we're trying to fit within
  * @property tokenizer - Function to count tokens in a string
- * @property totalTokens - Current total token count across all fragments
+ * @property tokenString - Renderer-provided projection used for token counting
+ * @property totalTokens - Current total token count for the prompt
  * @property iteration - Which iteration of the fit loop (for debugging)
+ * @property context - Inherited context from ancestor provider components
  */
 export interface StrategyInput {
-    fragments: readonly PromptFragment[];
-    target: PromptFragment;
+    target: PromptElement;
     budget: number;
     tokenizer: Tokenizer;
+    tokenString: (element: PromptElement) => string;
     totalTokens: number;
     iteration: number;
+    /** Context inherited from ancestor provider components */
+    context: CriaContext;
 }
 /**
- * A function that counts tokens in a string.
+ * A Strategy function that rewrites a region subtree when the prompt is over budget.
  *
- * Cria doesn't bundle a tokenizer—you provide one. Common choices:
- * - `tiktoken` for OpenAI models (cl100k_base for GPT-4)
- * - Simple approximation: `text => Math.ceil(text.length / 4)`
+ * Strategies are applied during fitting, starting from the least important
+ * priority (highest number). Strategies run **bottom-up** (post-order) so nested
+ * regions get a chance to shrink before their parents.
  *
- * @example
- * ```typescript
- * import { encoding_for_model } from "tiktoken";
+ * Strategies must be:
+ * - **Pure**: don't mutate the input element
+ * - **Deterministic**
+ * - **Idempotent**
  *
- * const enc = encoding_for_model("gpt-4");
- * const tokenizer: Tokenizer = (text) => enc.encode(text).length;
- * ```
+ * Strategies have full ownership of their subtree: they can replace the element
+ * and/or rewrite any children.
  */
-export type Tokenizer = (text: string) => number;
+export type Strategy = (input: StrategyInput) => MaybePromise<StrategyResult>;
 /**
  * Error thrown when the prompt cannot be fit within the budget.
  *