### Install Priompt with npm

Source: https://github.com/anysphere/priompt/blob/main/README.md

Install the Priompt library and its preview package using npm.

```bash
npm install @anysphere/priompt && npm install -D @anysphere/priompt-preview
```

--------------------------------

### Install Priompt with pnpm

Source: https://github.com/anysphere/priompt/blob/main/README.md

Install the Priompt library and its preview package using pnpm.

```bash
pnpm add @anysphere/priompt && pnpm add -D @anysphere/priompt-preview
```

--------------------------------

### Install Priompt with yarn

Source: https://github.com/anysphere/priompt/blob/main/README.md

Install the Priompt library and its preview package using yarn.

```bash
yarn add @anysphere/priompt && yarn add --dev @anysphere/priompt-preview
```

--------------------------------

### Install Priompt Package

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

Install the main Priompt package and the optional preview dashboard package using npm or yarn.

```bash
npm install @anysphere/priompt
npm install -D @anysphere/priompt-preview  # Optional, for dashboard
```

```bash
yarn add @anysphere/priompt
yarn add -D @anysphere/priompt-preview
```

--------------------------------

### Example Priompt Component Structure

Source: https://github.com/anysphere/priompt/blob/main/README.md

Demonstrates how to structure a prompt using JSX components with priority-based rendering. This example includes system messages, message history, and user messages, prioritizing recent items.

```jsx
function ExamplePrompt(
  props: PromptProps<{
    name: string,
    message: string,
    history: { case: "user" | "assistant", message: string }[],
  }>): PromptElement {
  const capitalizedName = props.name[0].toUpperCase() + props.name.slice(1);
  return (
    <>
      <SystemMessage>
        The user's name is {capitalizedName}. Please respond to them kindly.
      </SystemMessage>
      {props.history.map((m, i) => (
        <scope prel={-(props.history.length - i)}>
          {m.case === "user" ? (
            <UserMessage>{m.message}</UserMessage>
          ) : (
            <AssistantMessage>{m.message}</AssistantMessage>
          )}
        </scope>
      ))}
      <UserMessage>{props.message}</UserMessage>
      <empty tokens={1000} />
    </>
  );
}
```

--------------------------------

### Start Priompt Server

Source: https://github.com/anysphere/priompt/blob/main/examples/README.md

Run the priompt server in one terminal to handle prompt requests.

```bash
pnpm priompt
```

--------------------------------

### Usage Example for renderPrompt()

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/renderPrompt.md

Demonstrates how to use the renderPrompt function with a typed JSX prompt component, custom props, and render options. This example shows the import statements, prompt definition, and the asynchronous execution flow.

```typescript
import { renderPrompt, CL100K, createElement as h } from '@anysphere/priompt';

type ExampleProps = {
  name: string;
  message: string;
};

const examplePrompt = (props) => {
  return h('scope', null,
    h('scope', null, `Hello, ${props.name}`),
    h('scope', null, props.message)
  );
};

async function run() {
  const output = await renderPrompt({
    prompt: examplePrompt,
    props: { name: 'Alice', message: 'How are you?' },
    renderOptions: {
      tokenLimit: 2048,
      tokenizer: CL100K,
    },
  });

  console.log(`Rendered ${output.tokenCount} tokens.`);
}
```

--------------------------------

### Basic Prompt Component Setup

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

Defines a simple prompt component that renders system and user messages. Ensure Fragment is imported if not globally available.

```typescript
import { createElement as h, UserMessage, SystemMessage, PromptProps } from '@anysphere/priompt';

type MyPromptProps = {
  userName: string;
  userQuery: string;
};

const MyPrompt = (props: PromptProps<MyPromptProps>) => {
  return h(Fragment, null,
    h(SystemMessage, null, 'You are a helpful assistant.'),
    h(UserMessage, null, `Hello, ${props.userName}! ${props.userQuery}`)
  );
};

export default MyPrompt;
```

--------------------------------

### Start Priompt Watcher

Source: https://github.com/anysphere/priompt/blob/main/examples/README.md

Execute the priompt watcher in a separate terminal to monitor changes and updates.

```bash
pnpm watch
```

--------------------------------

### ZTools() Usage Example

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/tool-function-components.md

Example demonstrating how to use the ZTools() component with a Zod schema for tool parameters and custom handlers for tool calls and parse errors.

```typescript
import { ZTools, UserMessage } from '@anysphere/priompt';
import { z } from 'zod';

const WeatherSchema = z.object({
  city: z.string(),
  units: z.enum(['C', 'F']).default('C'),
});

const prompt = (
  <>
    <UserMessage>What's the weather in London?</UserMessage>
    <ZTools
      tools={[{
        name: 'get_weather',
        description: 'Get current weather',
        parameters: WeatherSchema,
        onCall: async (args, toolCallId, toolName) => {
          console.log(`${args.city} in ${args.units}`);
        },
        onParseError: async (error, rawArgs) => {
          console.error('Parse failed:', error.message);
        }
      }]}
      onReturn={async (output) => {
        for await (const chunk of output) {
          console.log(chunk);
        }
      }}
    />
  </>
);

```

--------------------------------

### Tools Component Usage Example

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/tool-function-components.md

Demonstrates how to use the `Tools` component to define a tool for fetching weather information. It includes setting up the tool's name, description, parameters, and an `onCall` handler.

```typescript
import { Tools, UserMessage } from '@anysphere/priompt';

const prompt = (
  <>
    <UserMessage>What's the weather in NYC?</UserMessage>
    <Tools
      tools={[{
        name: 'get_weather',
        description: 'Get weather for a city',
        parameters: {
          type: 'object',
          properties: {
            city: { type: 'string' }
          },
          required: ['city']
        },
        onCall: async (args, toolCallId, toolName, toolIndex) => {
          const { city } = JSON.parse(args);
          console.log(`Fetching weather for ${city}`);
        }
      }]}
      onReturn={async (output) => {
        for await (const chunk of output) {
          console.log(chunk);
        }
      }}
    />
  </>
);
```

--------------------------------

### Render a Prompt Element Tree

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/render.md

Demonstrates how to use the render() function with basic options. This example shows rendering a simple prompt structure with different priority levels and logging the resulting token count and cutoff.

```typescript
import { render, CL100K, createElement as h } from '@anysphere/priompt';

async function renderExample() {
  const prompt = h('scope', null,
    h('scope', null, 'System: You are helpful.'),
    h('scope', { prel: -1 }, 'Low priority content'),
    h('scope', { p: 100 }, 'High priority content')
  );

  const output = await render(prompt, {
    tokenLimit: 4096,
    tokenizer: CL100K,
  });

  console.log(`Rendered prompt has ${output.tokenCount} tokens.`);
  console.log(`Priority cutoff: ${output.priorityCutoff}`);
}
```

--------------------------------

### Priompt Isolate Usage Example

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/architecture.md

Demonstrates how to use the Isolate node to render a stable system message prefix before variable context, ensuring consistent LLM cache headers.

```typescript
<isolate tokenLimit={1024}>
  <SystemMessage>System instructions</SystemMessage>
  <br />
</isolate>
<scope prel={-1}>Variable context</scope>
```

--------------------------------

### Usage Example of DO_NOT_DUMP

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Demonstrates how to use the DO_NOT_DUMP prefix to exclude large data from being serialized by dumpProps.

```typescript
const props = {
  name: 'Alice',
  DO_NOT_DUMP_imageData: new Uint8Array(100000), // Won't be saved
};

const dump = dumpProps(config, props); // Only 'name' is serialized
```

--------------------------------

### renderun() Usage Example

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/renderun.md

Demonstrates how to use the renderun() function to render a prompt, call an OpenAI model, and capture the response content. Ensure necessary imports and an initialized OpenAI client are available.

```typescript
import { renderun, CL100K, createElement as h, UserMessage, AssistantMessage } from '@anysphere/priompt';
import { OpenAI } from 'openai';

const client = new OpenAI();

const myPrompt = (props) => {
  return h('scope', null,
    h(UserMessage, null, props.userMessage),
    h('capture', {
      onOutput: async (output) => {
        props.onReturn(output.content);
      }
    })
  );
};

async function run() {
  const result = await renderun({
    prompt: myPrompt,
    props: { userMessage: 'Hello!' },
    renderOptions: {
      tokenLimit: 2048,
      tokenizer: CL100K,
    },
    modelCall: async (request) => {
      const response = await client.chat.completions.create({
        model: 'gpt-4',
        messages: request.messages,
      });
      return { type: 'output', value: response };
    },
  });

  console.log('Model response:', result);
}
```

--------------------------------

### SystemMessage Usage Example

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/message-components.md

Use SystemMessage to render a system role message in a chat prompt. It requires importing SystemMessage, UserMessage, and createElement from '@anysphere/priompt'.

```typescript
import { SystemMessage, UserMessage, createElement as h } from '@anysphere/priompt';

const prompt = h('scope', null,
  h(SystemMessage, null, 'You are a helpful AI assistant.'),
  h(UserMessage, null, 'What is 2+2?')
);
```

--------------------------------

### Render Prompt with Specific Tokenizer

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/tokenizers.md

Use the `render` function to process a prompt with a specified tokenizer, like GPT-4o's O200K. This example shows how to set the `tokenLimit` and `tokenizer` options.

```typescript
import { render, O200K, UserMessage } from '@anysphere/priompt';

async function renderPrompt() {
  const prompt = <UserMessage>Hello, world!</UserMessage>;
  
  const output = await render(prompt, {
    tokenLimit: 2048,
    tokenizer: O200K,  // Use GPT-4o tokenizer
  });
  
  console.log(`Tokens used: ${output.tokenCount}`);
}
```

--------------------------------

### UserMessage Usage Example

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/message-components.md

Use UserMessage to render a user role message in a chat prompt. It requires importing UserMessage from '@anysphere/priompt'.

```typescript
import { UserMessage } from '@anysphere/priompt';

const message = <UserMessage>Tell me a joke.</UserMessage>;
```

--------------------------------

### ZFunction Component Usage Example

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/tool-function-components.md

Demonstrates how to use the ZFunction component with a Zod schema for defining and validating function parameters. Includes handlers for successful calls and potential parse errors.

```typescript
import { ZFunction, UserMessage } from '@anysphere/priompt';
import { z } from 'zod';

const AddSchema = z.object({
  a: z.number(),
  b: z.number(),
});

const prompt = (
  <>
    <UserMessage>Add 3 and 5</UserMessage>
    <ZFunction
      name="add"
      description="Add two numbers"
      parameters={AddSchema}
      onCall={async (args) => {
        console.log(`Result: ${args.a + args.b}`);
      }}
    />
  </>
);
```

--------------------------------

### Legacy Function Component Usage Example

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/tool-function-components.md

Demonstrates how to use the legacy Function component within a prompt to define a callable function for the model. Includes defining the function's name, description, parameters, and an onCall handler.

```typescript
import { Function, UserMessage } from '@anysphere/priompt';

const prompt = (
  <>
    <UserMessage>Calculate 2 + 2</UserMessage>
    <Function
      name="add"
      description="Add two numbers"
      parameters={{
        type: 'object',
        properties: {
          a: { type: 'number' },
          b: { type: 'number' }
        },
        required: ['a', 'b']
      }}
      onCall={async (args) => {
        const { a, b } = JSON.parse(args);
        console.log(`Result: ${a + b}`);
      }}
    />
  </>
);
```

--------------------------------

### Optimize Large Prompt Trees with Isolate

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

Use the 'isolate' component to break large prompt trees into independent, cached sections, significantly reducing render time. This example shows before and after optimization.

```typescript
// Before: ~5000 scopes, 500ms render time
const prompt = (
  <>
    {largeArray.map((item, i) => (
      <scope prel={-(largeArray.length - i)}>
        {item}
      </scope>
    ))}
  </>
);

// After: ~500 scopes, 50ms render time
const prompt = (
  <>
    <isolate tokenLimit={8000}>
      {largeArray.map((item, i) => (
        <scope prel={-(largeArray.length - i)}>
          {item}
        </scope>
      ))}
    </isolate>
  </>
);
```

--------------------------------

### Initialize Project

Source: https://github.com/anysphere/priompt/blob/main/examples/README.md

Navigate to the parent directory and run the initialization script. Ensure your OpenAI API key is configured in the .env file before proceeding.

```bash
cd .. && ./init.sh
```

--------------------------------

### Enable Preview Dashboard and Logs

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

Configure environment variables to enable the preview dashboard and verbose render logs during development. This helps in debugging and monitoring.

```bash
NODE_ENV=development PRINT_PRIOMPT_LOGS=true npm run dev
```

--------------------------------

### Get Tokenizer by Name

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/tokenizers.md

Retrieve a tokenizer instance by its name, specifically for OpenAI-compatible tokenizers. This is useful for programmatically selecting tokenizers.

```typescript
import { getTokenizerByName_ONLY_FOR_OPENAI_TOKENIZERS } from '@anysphere/priompt';

const tokenizer = getTokenizerByName_ONLY_FOR_OPENAI_TOKENIZERS('o200k_base');
```

--------------------------------

### configFromPrompt()

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Extract or generate PreviewConfig from a Prompt. If the prompt already has a config, it is returned. Otherwise, a new config is created using the prompt's name.

```APIDOC
## configFromPrompt() <a name="configFromPrompt"></a>

### Description

Extract or generate PreviewConfig from a Prompt. If `prompt.config` exists, returns it. Otherwise creates a config with `id: prompt.name`.

### Method

```typescript
function configFromPrompt<T, ReturnT>(prompt: Prompt<T, ReturnT>): PreviewConfig<T>
```

### Source

`src/preview.ts:79`
```

--------------------------------

### Root Documentation Files

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/MANIFEST.md

Lists the files generated for root documentation, including README, INDEX, MANIFEST, and architecture.

```markdown
README.md                  1,207 lines   Project overview, quick start, patterns
INDEX.md                   1,048 lines   Documentation index and navigation
MANIFEST.md                  (this)      File inventory and statistics
architecture.md              927 lines   Internal design, algorithms, patterns
```

--------------------------------

### ImageComponent Usage Example

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/message-components.md

Embeds an image in a prompt for vision models. Provide raw image bytes, dimensions, and the desired detail level. The 'bytes' parameter should be a Uint8Array.

```typescript
import { ImageComponent, UserMessage } from '@anysphere/priompt';
import fs from 'fs';

const imageBytes = fs.readFileSync('photo.jpg');
const message = (
  <UserMessage>
    <ImageComponent
      bytes={new Uint8Array(imageBytes)}
      dimensions={{ width: 1200, height: 800 }}
      detail="high"
    />
    What is in this image?
  </UserMessage>
);
```

--------------------------------

### Basic Prompt Rendering

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/README.md

Renders a simple prompt with system and user messages using createElement. Ensure Priompt and O200K tokenizer are imported.

```typescript
import { render, O200K, UserMessage, SystemMessage, createElement as h } from '@anysphere/priompt';

const prompt = h('scope', null,
  h(SystemMessage, null, 'You are helpful.'),
  h(UserMessage, null, 'Hello!')
);

const output = await render(prompt, {
  tokenLimit: 2048,
  tokenizer: O200K,
});

console.log(`Rendered: ${output.tokenCount} tokens`);
```

--------------------------------

### register()

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

A convenience function that acts as a shorthand for calling `PreviewManager.registerConfig()`. It simplifies the process of registering a prompt configuration.

```APIDOC
## register()

### Description
Convenience function to register a prompt via `register(config)`.

### Method
`register<T>(config: PreviewConfig<T>): void`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (PreviewConfig<T>) - Required - Configuration object with id, prompt, and optional dump/hydrate functions.

### Request Example
```typescript
import { register } from '@anysphere/priompt';

const config = {
  id: 'my-prompt',
  prompt: MyPromptComponent,
};

register(config);
```

### Response
#### Success Response (200)
None (void return type)

#### Response Example
None

### Notes
Equivalent to `PreviewManager.registerConfig(config)`.
```

--------------------------------

### Handle TooManyTokensForBasePriority Error

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/errors.md

Safely render prompts by catching and handling the TooManyTokensForBasePriority error. This example demonstrates retrying with a larger token limit when the base prompt exceeds the initial limit.

```typescript
import { render, O200K, TooManyTokensForBasePriority } from '@anysphere/priompt';

async function renderSafely(prompt) {
  try {
    const output = await render(prompt, {
      tokenLimit: 2048,
      tokenizer: O200K,
    });
    return output;
  } catch (error) {
    if (error instanceof TooManyTokensForBasePriority) {
      console.error('Base prompt is too large. Increase tokenLimit or reduce fixed content.');
      console.error(`Needed: ${error.message}`);
      // Fallback: use larger limit or different prompt
      return await render(prompt, {
        tokenLimit: 8192,  // Try larger limit
        tokenizer: O200K,
      });
    }
    throw error;
  }
}
```

--------------------------------

### ToolResultMessage Usage Example

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/message-components.md

Renders a tool result message. Use this component to display the output of a tool call within a conversation. Ensure the 'name' prop matches the tool name.

```typescript
import { ToolResultMessage, AssistantMessage } from '@anysphere/priompt';

const conversation = (
  <>
    <AssistantMessage toolCalls={[{ id: 'call_123', index: 0, tool: { type: 'function', function: { name: 'search', arguments: '{}' } } }]} />
    <ToolResultMessage name="search">Found 5 results</ToolResultMessage>
  </>
);
```

--------------------------------

### API Reference - Core Files

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/MANIFEST.md

Lists the files for the core API reference, including rendering functions and element creation.

```markdown
api-reference/
├── render.md                 185 lines   Core rendering function
├── renderPrompt.md           118 lines   Type-safe rendering
├── renderun.md               161 lines   Render + model execution
└── createElement.md          286 lines   JSX element creation
```

--------------------------------

### Extract PreviewConfig from Prompt

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Returns the existing config if prompt.config exists, otherwise creates a new config with id: prompt.name.

```typescript
function configFromPrompt<T, ReturnT>(prompt: Prompt<T, ReturnT>): PreviewConfig<T>
```

--------------------------------

### PreviewConfig

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Configuration object for a prompt component, including its ID, the prompt itself, and optional custom serializer/deserializer functions.

```APIDOC
## PreviewConfig

### Description
Configuration object for a prompt component.

### Properties
- **id** (string) - Yes - Unique identifier for the prompt.
- **prompt** (Prompt) - Yes - The prompt component function.
- **dump** (function) - No - Custom serializer. Defaults to JSON.
- **hydrate** (function) - No - Custom deserializer. Defaults to JSON.parse.
```

--------------------------------

### FunctionMessage Component Usage

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/message-components.md

Use FunctionMessage to render legacy function result messages. It requires the name of the function that returned the result. This example also shows its use in a conversation alongside AssistantMessage.

```typescript
import { FunctionMessage, AssistantMessage } from '@anysphere/priompt';

const conversation = (
  <>
    <AssistantMessage functionCall={{ name: 'getWeather', arguments: '{"city":"NYC"}' }} />
    <FunctionMessage name="getWeather">{"temp": 72, "condition": "sunny"}</FunctionMessage>
  </>
);
```

--------------------------------

### Registering a Prompt Component for Preview

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

Registers a prompt component with the PreviewManager for interactive testing. Requires importing `PreviewManager` and `PreviewConfig`.

```typescript
import MyPrompt from './MyPrompt';
import { PreviewManager, PreviewConfig } from '@anysphere/priompt';

const config: PreviewConfig<MyPromptProps> = {
  id: 'my-prompt',
  prompt: MyPrompt,
  dump: (props) => JSON.stringify(props),
  hydrate: (dump) => JSON.parse(dump),
};

PreviewManager.registerConfig(config);
```

--------------------------------

### API Reference - Utilities Files

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/MANIFEST.md

Lists the files for the API reference concerning utilities, including tokenizers and helper functions.

```markdown
api-reference/
├── tokenizers.md             236 lines   Token counting, encoding
├── utility-functions.md      283 lines   Helper functions, type guards
└── preview.md                251 lines   Dashboard integration
```

--------------------------------

### Layered Context with Scopes

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/architecture.md

Use layered context with scopes to define different levels of information like core rules, examples, and edge cases. This pattern helps in organizing prompt components for caching and enrichment.

```typescript
<isolate tokenLimit={1024}>
  <SystemMessage>Core rules</SystemMessage>
</isolate>

<scope prel={-100}>
  <SystemMessage>Examples</SystemMessage>
</scope>

<scope prel={-1000}>
  <SystemMessage>Edge cases</SystemMessage>
</scope>

<UserMessage>User query</UserMessage>
```

--------------------------------

### Send a Prompt Request

Source: https://github.com/anysphere/priompt/blob/main/examples/README.md

Use curl to send a message to the priompt server. The request includes a message and a name, and expects a response within seconds.

```bash
curl 'localhost:8008/message?message=what%20is%20the%20advantage%20of%20rust%20over%20c&name=a%20curious%20explorer'
```

--------------------------------

### SynchronousPreviewConfig

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Configuration for synchronous (non-async) prompts, extending PreviewConfig with an optional dump extension.

```APIDOC
## SynchronousPreviewConfig

### Description
Configuration for synchronous (non-async) prompts. Same as `PreviewConfig`, with optional `dumpExtension` (e.g., `.yaml` instead of `.json`).

### Properties
- **id** (string) - Yes - Unique identifier for the prompt.
- **prompt** (SynchronousPrompt) - Yes - The prompt component function.
- **dump** (function) - No - Custom serializer. Defaults to JSON.
- **hydrate** (function) - No - Custom deserializer. Defaults to JSON.parse.
- **dumpExtension** (string) - No - Optional file extension for the dump, e.g., `.yaml`.
```

--------------------------------

### render() Function

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/render.md

Renders a prompt element tree into a structured prompt, calculating token counts and applying priority-based content inclusion. It uses a binary search algorithm to find the optimal priority cutoff that fits within the specified token limit.

```APIDOC
## render() Function

### Description
Core function for rendering a prompt element tree into a structured prompt with token counting and priority-based content inclusion. It implements a binary search algorithm to find the maximum priority cutoff that fits within the token limit.

### Signature
```typescript
async function render(elem: PromptElement, options: RenderOptions): Promise<RenderOutput>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **elem** (PromptElement) - Required - The JSX element tree to render. Can be a single element or array of elements.
- **options** (RenderOptions) - Required - Rendering configuration object.
  - **options.tokenLimit** (number) - Required - Maximum token count for the rendered prompt (hard limit).
  - **options.tokenizer** (PriomptTokenizer) - Required - Tokenizer instance for counting tokens and encoding. Defines token model (e.g., CL100K, O200K).
  - **options.countTokensFast_UNSAFE** (boolean) - Optional - If true, use fast approximation for token counting (reduces accuracy by ~5%). Defaults to `false`.
  - **options.shouldBuildSourceMap** (boolean) - Optional - If true, generate a source map linking prompt characters to JSX tree positions. Defaults to `false`.
  - **options.lastMessageIsIncomplete** (boolean) - Optional - If true, assume the last message in a chat prompt is incomplete (affects token counting for streaming). Defaults to `false`.

### Return Type
`Promise<RenderOutput>`

### Return Value Fields
- **prompt** (RenderedPrompt) - Final rendered prompt (string, chat messages, or content wrapper).
- **tokenCount** (number) - Exact token count of rendered prompt.
- **tokenLimit** (number) - Token limit used during rendering.
- **tokenizer** (PriomptTokenizer) - Tokenizer instance used.
- **tokensReserved** (number) - Tokens reserved by `<empty>` elements.
- **priorityCutoff** (number) - Priority level used to include/exclude content.
- **outputHandlers** (OutputHandler[]) - Handlers from `<capture>` elements (called on model output).
- **streamHandlers** (OutputHandler[]) - Handlers for streamed output.
- **streamResponseObjectHandlers** (OutputHandler[]) - Handlers for streamed response objects.
- **config** (ConfigProps) - Configuration from `<config>` elements.
- **durationMs** (number | undefined) - Rendering time in milliseconds (if measured).
- **sourceMap** (SourceMap | undefined) - Source map (if requested).

### Behavior
The render function implements a binary search algorithm to find the maximum priority cutoff that fits within the token limit:

1. **Priority collection** — Walks the element tree and extracts all distinct priority levels.
2. **Isolate hydration** — Renders all `<isolate>` elements to cache their output and token counts.
3. **Empty token hydration** — Resolves token functions in `<empty>` elements.
4. **Binary search** — Tests priority levels in log(n) passes, each counting tokens to find the optimal cutoff.
5. **Inclusion logic** — Includes all elements with priority ≥ cutoff; excludes those with priority < cutoff.

### Throws
- **TooManyTokensForBasePriority**: Rendered prompt at base priority (1e9) exceeds token limit. Indicates invalid prompt design.
- **Error**: Invalid tokenizer, malformed prompt tree, or missing required configuration.

### Usage Example
```typescript
import { render, CL100K, createElement as h } from '@anysphere/priompt';

async function renderExample() {
  const prompt = h('scope', null,
    h('scope', null, 'System: You are helpful.'),
    h('scope', { prel: -1 }, 'Low priority content'),
    h('scope', { p: 100 }, 'High priority content')
  );

  const output = await render(prompt, {
    tokenLimit: 4096,
    tokenizer: CL100K,
  });

  console.log(`Rendered prompt has ${output.tokenCount} tokens.`);
  console.log(`Priority cutoff: ${output.priorityCutoff}`);
}
```
```

--------------------------------

### Register Prompt Configuration with PreviewManager

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Use this method to register a prompt component configuration with the PreviewManager. Ensure the config object includes an id, the prompt component, and optional dump/hydrate functions.

```typescript
import { PreviewManager } from '@anysphere/priompt';

const config = {
  id: 'my-prompt',
  prompt: MyPromptComponent,
  dump: (props) => JSON.stringify(props),
  hydrate: (dump) => JSON.parse(dump),
};

PreviewManager.registerConfig(config);
```

--------------------------------

### PreviewManager.registerConfig()

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Registers a prompt component configuration with the Preview Manager. This allows the component to be displayed and managed within the preview dashboard.

```APIDOC
## PreviewManager.registerConfig()

### Description
Register a prompt component for the preview dashboard.

### Method
`PreviewManager.registerConfig<T>(config: PreviewConfig<T>): void`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (PreviewConfig<T>) - Required - Configuration object with id, prompt, and optional dump/hydrate functions.

### Request Example
```typescript
import { PreviewManager } from '@anysphere/priompt';

const config = {
  id: 'my-prompt',
  prompt: MyPromptComponent,
  dump: (props) => JSON.stringify(props),
  hydrate: (dump) => JSON.parse(dump),
};

PreviewManager.registerConfig(config);
```

### Response
#### Success Response (200)
None (void return type)

#### Response Example
None
```

--------------------------------

### PriomptTokenizer Interface Methods

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/tokenizers.md

This section details the methods available on the PriomptTokenizer interface, including their parameters, return types, and asynchronous nature.

```APIDOC
## PriomptTokenizer Interface Methods

This documentation outlines the methods available on the `PriomptTokenizer` interface.

### Methods

| Method | Return | Async | Description |
|---|---|---|---|
| **encodeTokens(text)** | `number[]` | Yes | Encode text to token IDs. |
| **decodeTokens(tokens)** | `string` | Yes | Decode token IDs back to text. |
| **numTokens(text)** | `number` | Yes | Exact token count (expensive). |
| **estimateNumTokensFast_SYNCHRONOUS_BE_CAREFUL(text)** | `number` | No | Fast sync estimate (~5% error). WARNING: May block event loop. |
| **estimateNumTokensFast(text)** | `number` | Yes | Fast async estimate (~5% error). |
| **estimateTokensUsingCharCount(text)** | `[lower, upper]` | No | Conservative bounds based on character count. |
| **getHeaderStringForMessage(msg)** | `string` | No | Message header string (e.g., `<\|im_start\|>user<\|im_sep\|>`). |
| **getHeaderTokensForMessage(msg)** | `number[]` | Yes | Token IDs for message header. |
| **getEosTokenId()** | `number` | No | End-of-sequence token ID. |
| **getEosToken()** | `string` | No | End-of-sequence token string. |
| **applyChatTemplate(messages, options)** | `string` | No | Apply tokenizer's chat template to messages. |
| **applyChatTemplateTokens(messages, options)** | `number[]` | Yes | Apply template and encode. |

### Properties

| Property | Type | Description |
|---|---|---|
| **shouldAddEosTokenToEachMessage** | `boolean` | Whether EOS is added after each message. |
```

--------------------------------

### Binary Search for Optimal Render Level

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/architecture.md

Implements a binary search algorithm to find the optimal priority level for rendering the prompt based on token limits. It iteratively refines a lower and upper bound to determine the best cutoff.

```plaintext
sortedLevels = priorityLevels.sort((a, b) => a - b)
lowerBound = -1
upperBound = sortedLevels.length - 1

while (lowerBound < upperBound - 1):
  mid = (lowerBound + upperBound) / 2
  candidateLevel = sortedLevels[mid]
  
  prompt = renderWithLevel(elem, candidateLevel)
  tokenCount = countTokens(prompt)
  
  if tokenCount > tokenLimit:
    lowerBound = mid  // Level too low, need higher cutoff
  else:
    upperBound = mid  // Level sufficient, try lower cutoff
```

--------------------------------

### Register Preview Configuration

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/architecture.md

Register a configuration for the preview dashboard using `PreviewManager.registerConfig`. This pattern allows custom prompt components to be integrated with the dashboard for debugging and review.

```typescript
const config: PreviewConfig<MyProps> = {
  id: 'my-prompt',
  prompt: MyPrompt,
  dump: (props) => YAML.stringify(props),
  hydrate: (dump) => YAML.parse(dump),
};

PreviewManager.registerConfig(config);
```

--------------------------------

### PreviewManagerLiveModeQuery

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Query type for requesting live-mode prompt updates.

```APIDOC
## PreviewManagerLiveModeQuery

### Description
Request for live-mode prompt updates.

### Properties
- **alreadySeenLiveModeId** (string) - No - The ID of the last seen live mode update.
```

--------------------------------

### PreviewManagerGetPromptQuery

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Query type for requesting the rendering of a saved prompt variant.

```APIDOC
## PreviewManagerGetPromptQuery

### Description
Request to render a saved prompt variant.

### Properties
- **promptId** (string) - Yes - The ID of the prompt to render.
- **propsId** (string) - Yes - The ID of the prompt properties.
- **tokenLimit** (number) - Yes - The token limit for the rendering.
- **tokenizer** (UsableTokenizer) - Yes - The tokenizer to use.
- **shouldBuildSourceMap** (boolean) - Yes - Whether to build a source map.
```

--------------------------------

### renderun() Function

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/renderun.md

Renders a prompt component, optionally handles tokenization, converts the prompt to an OpenAI chat request format, invokes a provided model call function, dispatches the model's output to registered handlers, and returns the result from the highest-priority handler.

```APIDOC
## renderun()

### Description

Render a prompt component and execute a model call in one step, capturing output via `<capture>` handlers.

### Signature

```typescript
async function renderun<ReturnT, PropsT extends object>({ 
  prompt, 
  props, 
  renderOptions, 
  modelCall, 
  loggingOptions, 
  renderedMessagesCallback, 
}: { 
  prompt: Prompt<PropsT, ReturnT>; 
  props: Omit<PropsT, "onReturn">; 
  renderOptions: Omit<RenderOptions, "countTokensFast_UNSAFE"> & { countTokensFast_UNSAFE?: RenderunCountTokensFast_UNSAFE }; 
  modelCall: (args: ReturnType<typeof promptToOpenAIChatRequest>) => Promise<{ type: "output", value: CreateChatCompletionResponse } | { type: "stream", value: AsyncIterable<ChatCompletionResponseMessage> } | { type: "streamResponseObject", value: AsyncIterable<StreamChatCompletionResponse> }>; 
  loggingOptions?: { promptElementRef?: { current: PromptElement | undefined }; renderOutputRef?: { current: RenderOutput | undefined }; }; 
  renderedMessagesCallback?: (messages: ChatCompletionRequestMessage[]) => void; 
}): Promise<ReturnT>
```

### Parameters

#### Parameters

- **prompt** (Prompt<PropsT, ReturnT>) - Required - Prompt component function.
- **props** (Omit<PropsT, "onReturn">) - Required - Props object. `onReturn` is managed by renderun.
- **renderOptions** (RenderOptions & countTokensFast_UNSAFE) - Required - Rendering config. `countTokensFast_UNSAFE` can be "yes", "no", or "try_retry".
- **modelCall** (Function) - Required - Async function that calls the LLM. Receives OpenAI chat request format and returns output, stream, or response object stream.
- **loggingOptions** (Object) - Optional - Refs to capture intermediate values: promptElement and renderOutput.
- **renderedMessagesCallback** (Function) - Optional - Called with final rendered messages before model call. Useful for logging.

### Return Type

```typescript
Promise<ReturnT>
```

The return type is determined by the highest-priority `<capture>` handler's `onReturn` callback type. If multiple handlers exist, the first-resolved one is returned.

### Behavior

1. **Render** — Calls `render()` with the prompt element tree.
2. **Tokenize** — Optionally retries with exact tokenization if fast mode overshoots.
3. **Convert** — Transforms rendered prompt to OpenAI chat request format.
4. **Call** — Invokes `modelCall()` with the request.
5. **Dispatch** — Passes model output to all registered handlers (from `<capture>` elements).
6. **Return** — Returns the highest-priority handler's result.

Throws if no `<capture>` handler is included or if model returns no choices.

### Throws

- **Error**: No output was captured (no `<capture>` handler).
- **Error**: Model returned no choices or no message.
- **TooManyTokensForBasePriority**: Base prompt exceeds token limit.

### Usage Example

```typescript
import { renderun, CL100K, createElement as h, UserMessage, AssistantMessage } from '@anysphere/priompt';
import { OpenAI } from 'openai';

const client = new OpenAI();

const myPrompt = (props) => {
  return h('scope', null,
    h(UserMessage, null, props.userMessage),
    h('capture', {
      onOutput: async (output) => {
        props.onReturn(output.content);
      }
    })
  );
};

async function run() {
  const result = await renderun({
    prompt: myPrompt,
    props: { userMessage: 'Hello!' },
    renderOptions: {
      tokenLimit: 2048,
      tokenizer: CL100K,
    },
    modelCall: async (request) => {
      const response = await client.chat.completions.create({
        model: 'gpt-4',
        messages: request.messages,
      });
      return { type: 'output', value: response };
    },
  });

  console.log('Model response:', result);
}
```
```

--------------------------------

### Reference Documentation Files

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/MANIFEST.md

Lists the files generated for reference documentation, covering types, configuration, and errors.

```markdown
types.md                     823 lines   All type definitions
configuration.md             487 lines   Setup, exports, environment, tuning
errors.md                    583 lines   Custom errors, handling, solutions
```

--------------------------------

### API Reference - Components Files

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/MANIFEST.md

Lists the files for the API reference related to components, such as message and tool function components.

```markdown
api-reference/
├── message-components.md     322 lines   Chat messages, images
├── tool-function-components.md 398 lines Tool/function components
└── Fragment.md                41 lines   Fragment utility
```

--------------------------------

### configFromSynchronousPrompt()

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Extract or generate PreviewConfig from a SynchronousPrompt. This function can optionally accept options to provide proto properties.

```APIDOC
## configFromSynchronousPrompt() <a name="configFromSynchronousPrompt"></a>

### Description

Extract or generate PreviewConfig from a SynchronousPrompt. This function can optionally accept options to provide proto properties.

### Method

```typescript
function configFromSynchronousPrompt<T, ReturnT>(
  prompt: SynchronousPrompt<T, ReturnT>,
  options?: { protoProps?: ProtoPropsType<T> }
): SynchronousPreviewConfig<T, ReturnT>
```

### Source

`src/preview.ts:89`
```

--------------------------------

### Configure TypeScript for Priompt JSX

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

Set up tsconfig.json to use Priompt's JSX transform and import source. This ensures correct rendering of JSX elements.

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@anysphere/priompt",
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"]
  }
}
```

--------------------------------

### emptyConfig()

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/utility-functions.md

Creates an empty configuration object. This function is primarily for internal use but can be helpful when constructing custom prompt structures.

```APIDOC
## emptyConfig()

### Description
Creates an empty configuration object. This function is primarily for internal use but can be helpful when constructing custom prompt structures.

### Signature
```typescript
function emptyConfig(): ConfigProps
```

### Return Type
```typescript
ConfigProps
```

Returns: `{ maxResponseTokens: undefined, stop: undefined }`
```

--------------------------------

### Preview Dashboard

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

Utilities for integrating with the preview dashboard, including managing prompt registration and serialization.

```APIDOC
## Preview Dashboard

### `PreviewManager`

- **Type**: class
- **Purpose**: Singleton for registering prompts with preview dashboard.

### `dumpProps`

- **Type**: function
- **Purpose**: Serialize prompt props.

### `register`

- **Type**: function
- **Purpose**: Register prompt config (alias for PreviewManager.registerConfig).
```

--------------------------------

### Export Preview Dashboard Components

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

Imports components and types for integrating with the preview dashboard. Use `PreviewManager` to register prompts and `dumpProps` to serialize prompt properties.

```typescript
export { PreviewManager, dumpProps, register } from './preview';
export type { PreviewManagerGetPromptQuery, PreviewManagerLiveModeQuery, PreviewManagerLiveModeResultQuery } from './preview';
```

--------------------------------

### Prompt Rendering with Model Call

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/README.md

Integrates a custom model call function with `renderun` for direct interaction with language models. Requires an OpenAI client and Priompt imports.

```typescript
import { renderun, O200K } from '@anysphere/priompt';
import { OpenAI } from 'openai';

const client = new OpenAI();

const result = await renderun({
  prompt: MyPrompt,
  props: { name: 'Alice', query: 'What is AI?' },
  renderOptions: { tokenLimit: 2048, tokenizer: O200K },
  modelCall: async (request) => {
    const response = await client.chat.completions.create({
      model: 'gpt-4o',
      ...request,
    });
    return { type: 'output', value: response };
  },
});

console.log('Model response:', result);
```

--------------------------------

### Core Functions

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/INDEX.md

Key functions for rendering and manipulating prompts.

```APIDOC
## Functions

### `render`

Core rendering function.

### `renderPrompt`

Type-safe render function.

### `renderun`

Renders a prompt and calls a model.

### `createElement`

Creates JSX elements.

### `Fragment`

Flattens fragments for rendering.

### `PreviewManager`

Manages dashboard previews.

### `dumpProps`

Serializes component props.

### `register`

Registers a prompt.

### `getTokenizerByName_ONLY_FOR_OPENAI_TOKENIZERS`

Retrieves a tokenizer by name, specifically for OpenAI tokenizers.

### `chatPromptToString`

Converts a chat prompt to a string.

### `replaceOpenaiSpecialTokens`

Sanitizes tokens by replacing OpenAI-specific ones.
```

--------------------------------

### PreviewManagerLiveModeResultQuery

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Response type containing live-mode rendered output.

```APIDOC
## PreviewManagerLiveModeResultQuery

### Description
Response containing live-mode rendered output.

### Properties
- **output** (string) - Yes - The rendered output from the live mode prompt.
```

--------------------------------

### Render Time Performance

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/architecture.md

Render time scales linearly with node count for scopes under 1000. Performance degrades significantly beyond 5000 nodes.

```text
Nodes    Time (ms)
100      1-2
500      5-10
1000     15-25
5000     100-200 (warning)
10000    200-500 (crisis)
```

--------------------------------

### Unit Test Priompt Rendering within Token Limit

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

This unit test verifies that a Priompt component renders correctly and stays within the specified token limit using a given tokenizer. It requires 'vitest' for testing and '@anysphere/priompt' for rendering.

```typescript
import { render, O200K } from '@anysphere/priompt';
import { describe, it, expect } from 'vitest';

describe('MyPrompt', () => {
  it('renders within token limit', async () => {
    const output = await render(MyPrompt({ userName: 'Alice', userQuery: 'Hi' }), {
      tokenLimit: 2048,
      tokenizer: O200K,
    });

    expect(output.tokenCount).toBeLessThan(2048);
    expect(output.prompt).toBeDefined();
  });
});
```

--------------------------------

### Preview Manager

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/README.md

Utilities for integrating with the preview dashboard, including serialization.

```APIDOC
## Preview Manager

### `PreviewManager`

#### Description
Manages and registers prompts for the preview dashboard.

### `dumpProps()`, `register()`

#### Description
Utilities for serializing and registering prompt data.
```

--------------------------------

### Select Tokenizer for GPT-4o

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

Choose the appropriate tokenizer for different models when rendering prompts. Use O200K for GPT-4o and GPT-4o mini.

```typescript
import { render, CL100K, O200K } from '@anysphere/priompt';

// For GPT-4o
const output = await render(prompt, {
  tokenLimit: 2048,
  tokenizer: O200K,  // ← Choose tokenizer here
});
```

--------------------------------

### Conditional Rendering with Fragment Shorthand

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/Fragment.md

Demonstrates how Fragment's shorthand can be used to conditionally render multiple elements within a prompt. The content inside the Fragment will only be included if the condition is met.

```typescript
const prompt = (
  <>
    <SystemMessage>System rules.</SystemMessage>
    {includeOptional && (
      <>
        <UserMessage>Optional part 1</UserMessage>
        <UserMessage>Optional part 2</UserMessage>
      </>
    )}
  </>
);
```

--------------------------------

### PreviewConfig Type Definition

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/api-reference/preview.md

Defines the configuration object for a general prompt component, including its ID, the prompt function, and optional custom serialization/deserialization functions.

```typescript
type PreviewConfig<PropsT, ReturnT = never> = {
  id: string;
  prompt: Prompt<PropsT, ReturnT>;
  dump?: (props: Omit<PropsT, "onReturn">) => string;
  hydrate?: (dump: string) => PropsT;
}
```

--------------------------------

### Element Creation

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/configuration.md

Functions and components for creating and managing JSX elements within the Priompt system.

```APIDOC
## Element Creation

### `createElement`

- **Type**: function
- **Purpose**: Create JSX elements (typically via JSX syntax).

### `Fragment`

- **Type**: component
- **Purpose**: Flatten child arrays (typically via `<>...</>` shorthand).
```

--------------------------------

### Structure Prompt with Functions and Tools

Source: https://github.com/anysphere/priompt/blob/main/_autodocs/architecture.md

Shows the structure of a prompt object, including messages, functions, and tools. Note the constraint that functions and tools cannot be mixed in the same prompt.

```typescript
const prompt = {
  type: 'chat',
  messages: [...],
  functions: [...],   // From all <Function> components
  tools: [...]        // From all <Tools> components
}
```