# @mwillbanks/tuil-story

Source: /tuil/docs/reference/packages/story
Locale: en

Portable tuil stories, browser bridges, snapshots, documentation, and Storybook adapters.



## Overview [#overview]

Portable tuil stories, browser bridges, snapshots, documentation, and Storybook adapters.

`@mwillbanks/tuil-story` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-story
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-story
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-story
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-story
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

Portable stories combine component args with terminal capabilities, themes, semantic nodes, focus state, events, ANSI output, and an action history. Adapters expose the same story to tests, browsers, static docs, and Storybook. Dynamic and static HTTP adapters stream untrusted bodies through a byte limit, validate their complete schema, bound recursive args, controls, dimensions, and simulated input, and apply a server-side timeout before render-lock acquisition.

<Mermaid
  chart="flowchart LR
  S0[&#x22;register story&#x22;]
  S1[&#x22;open session&#x22;]
  S2[&#x22;render&#x22;]
  S3[&#x22;interact/update&#x22;]
  S4[&#x22;close&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4"
/>

## API [#api]

| API                                                                                                            | Signature                                    | Description                                        |
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------- |
| [`ansiFrameToHtml`](/tuil/docs/reference/packages/story/api/ansi-frame-to-html)                                     | `function ansiFrameToHtml`                   | Public function ansiFrameToHtml.                   |
| [`browserStories`](/tuil/docs/reference/packages/story/api/browser-stories)                                         | `function browserStories`                    | Public function browserStories.                    |
| [`BrowserStorySet`](/tuil/docs/reference/packages/story/api/browser-story-set)                                      | `interface BrowserStorySet`                  | Public interface BrowserStorySet.                  |
| [`componentArgsFromAdapterArgs`](/tuil/docs/reference/packages/story/api/component-args-from-adapter-args)          | `function componentArgsFromAdapterArgs`      | Public function componentArgsFromAdapterArgs.      |
| [`createFumadocsStoryAdapter`](/tuil/docs/reference/packages/story/api/create-fumadocs-story-adapter)               | `function createFumadocsStoryAdapter`        | Public function createFumadocsStoryAdapter.        |
| [`createStaticStoryHttpHandler`](/tuil/docs/reference/packages/story/api/create-static-story-http-handler)          | `function createStaticStoryHttpHandler`      | Public function createStaticStoryHttpHandler.      |
| [`createStorybookAdapter`](/tuil/docs/reference/packages/story/api/create-storybook-adapter)                        | `function createStorybookAdapter`            | Public function createStorybookAdapter.            |
| [`createStoryHttpHandler`](/tuil/docs/reference/packages/story/api/create-story-http-handler)                       | `function createStoryHttpHandler`            | Public function createStoryHttpHandler.            |
| [`createTerminalStoryFrameEffect`](/tuil/docs/reference/packages/story/api/create-terminal-story-frame-effect)      | `function createTerminalStoryFrameEffect`    | Public function createTerminalStoryFrameEffect.    |
| [`defaultTerminalStoryControls`](/tuil/docs/reference/packages/story/api/default-terminal-story-controls)           | `export defaultTerminalStoryControls`        | Public export defaultTerminalStoryControls.        |
| [`defineTuilStories`](/tuil/docs/reference/packages/story/api/define-tuil-stories)                                  | `export defineTuilStories`                   | Public export defineTuilStories.                   |
| [`FumadocsStoryConfig`](/tuil/docs/reference/packages/story/api/fumadocs-story-config)                              | `interface FumadocsStoryConfig`              | Public interface FumadocsStoryConfig.              |
| [`FumadocsStoryProps`](/tuil/docs/reference/packages/story/api/fumadocs-story-props)                                | `type FumadocsStoryProps`                    | Public type FumadocsStoryProps.                    |
| [`generateStoryCatalogDocumentation`](/tuil/docs/reference/packages/story/api/generate-story-catalog-documentation) | `function generateStoryCatalogDocumentation` | Public function generateStoryCatalogDocumentation. |
| [`generateStoryCatalogSnapshots`](/tuil/docs/reference/packages/story/api/generate-story-catalog-snapshots)         | `function generateStoryCatalogSnapshots`     | Public function generateStoryCatalogSnapshots.     |
| [`handleStoryHttpRequest`](/tuil/docs/reference/packages/story/api/handle-story-http-request)                       | `function handleStoryHttpRequest`            | Public function handleStoryHttpRequest.            |
| [`OpenStoryOptions`](/tuil/docs/reference/packages/story/api/open-story-options)                                    | `interface OpenStoryOptions`                 | Public interface OpenStoryOptions.                 |
| [`renderStaticStoryRequest`](/tuil/docs/reference/packages/story/api/render-static-story-request)                   | `function renderStaticStoryRequest`          | Public function renderStaticStoryRequest.          |
| [`renderStoryRequest`](/tuil/docs/reference/packages/story/api/render-story-request)                                | `function renderStoryRequest`                | Public function renderStoryRequest.                |
| [`StaticStoryCatalog`](/tuil/docs/reference/packages/story/api/static-story-catalog)                                | `class StaticStoryCatalog`                   | Public class StaticStoryCatalog.                   |
| [`StaticStoryFrame`](/tuil/docs/reference/packages/story/api/static-story-frame)                                    | `type StaticStoryFrame`                      | Public type StaticStoryFrame.                      |
| [`StaticStoryRequest`](/tuil/docs/reference/packages/story/api/static-story-request)                                | `interface StaticStoryRequest`               | Public interface StaticStoryRequest.               |
| [`StoryAction`](/tuil/docs/reference/packages/story/api/story-action)                                               | `interface StoryAction`                      | Public interface StoryAction.                      |
| [`StorybookAdapter`](/tuil/docs/reference/packages/story/api/storybook-adapter)                                     | `interface StorybookAdapter`                 | Public interface StorybookAdapter.                 |
| [`StoryBridgeRequest`](/tuil/docs/reference/packages/story/api/story-bridge-request)                                | `interface StoryBridgeRequest`               | Public interface StoryBridgeRequest.               |
| [`StoryCatalogSnapshots`](/tuil/docs/reference/packages/story/api/story-catalog-snapshots)                          | `type StoryCatalogSnapshots`                 | Public type StoryCatalogSnapshots.                 |
| [`StoryFrame`](/tuil/docs/reference/packages/story/api/story-frame)                                                 | `interface StoryFrame`                       | Public interface StoryFrame.                       |
| [`storyFrameToMarkdown`](/tuil/docs/reference/packages/story/api/story-frame-to-markdown)                           | `function storyFrameToMarkdown`              | Public function storyFrameToMarkdown.              |
| [`StoryHttpHandlerOptions`](/tuil/docs/reference/packages/story/api/story-http-handler-options)                     | `interface StoryHttpHandlerOptions`          | Public interface StoryHttpHandlerOptions.          |
| [`storyHttpLimits`](/tuil/docs/reference/packages/story/api/story-http-limits)                                      | `constant storyHttpLimits`                   | Public constant storyHttpLimits.                   |
| [`StorySnapshot`](/tuil/docs/reference/packages/story/api/story-snapshot)                                           | `interface StorySnapshot`                    | Public interface StorySnapshot.                    |
| [`terminalControlArgNames`](/tuil/docs/reference/packages/story/api/terminal-control-arg-names)                     | `constant terminalControlArgNames`           | Public constant terminalControlArgNames.           |
| [`terminalControlsFromArgs`](/tuil/docs/reference/packages/story/api/terminal-controls-from-args)                   | `function terminalControlsFromArgs`          | Public function terminalControlsFromArgs.          |
| [`terminalControlsToArgs`](/tuil/docs/reference/packages/story/api/terminal-controls-to-args)                       | `function terminalControlsToArgs`            | Public function terminalControlsToArgs.            |
| [`TerminalStoryControls`](/tuil/docs/reference/packages/story/api/terminal-story-controls)                          | `export TerminalStoryControls`               | Public export TerminalStoryControls.               |
| [`TerminalStoryFrame`](/tuil/docs/reference/packages/story/api/terminal-story-frame)                                | `function TerminalStoryFrame`                | Public function TerminalStoryFrame.                |
| [`TerminalStoryFrameEffectOptions`](/tuil/docs/reference/packages/story/api/terminal-story-frame-effect-options)    | `interface TerminalStoryFrameEffectOptions`  | Public interface TerminalStoryFrameEffectOptions.  |
| [`TerminalStoryFrameProps`](/tuil/docs/reference/packages/story/api/terminal-story-frame-props)                     | `interface TerminalStoryFrameProps`          | Public interface TerminalStoryFrameProps.          |
| [`TerminalStoryFrameView`](/tuil/docs/reference/packages/story/api/terminal-story-frame-view)                       | `function TerminalStoryFrameView`            | Public function TerminalStoryFrameView.            |
| [`TerminalStoryFrameViewProps`](/tuil/docs/reference/packages/story/api/terminal-story-frame-view-props)            | `interface TerminalStoryFrameViewProps`      | Public interface TerminalStoryFrameViewProps.      |
| [`TuilStory`](/tuil/docs/reference/packages/story/api/tuil-story)                                                   | `export TuilStory`                           | Public export TuilStory.                           |
| [`TuilStoryCatalog`](/tuil/docs/reference/packages/story/api/tuil-story-catalog)                                    | `class TuilStoryCatalog`                     | Public class TuilStoryCatalog.                     |
| [`TuilStoryDefinition`](/tuil/docs/reference/packages/story/api/tuil-story-definition)                              | `export TuilStoryDefinition`                 | Public export TuilStoryDefinition.                 |
| [`TuilStorySession`](/tuil/docs/reference/packages/story/api/tuil-story-session)                                    | `class TuilStorySession`                     | Public class TuilStorySession.                     |
| [`TuilStorySet`](/tuil/docs/reference/packages/story/api/tuil-story-set)                                            | `interface TuilStorySet`                     | Public interface TuilStorySet.                     |
| [`validateStoryBridgeRequest`](/tuil/docs/reference/packages/story/api/validate-story-bridge-request)               | `function validateStoryBridgeRequest`        | Public function validateStoryBridgeRequest.        |

## Events and lifecycle [#events-and-lifecycle]

Every rendered frame captures the runtime's observed event history and story action timeline. HTTP request failures return 400, client disconnects return 499, and render timeouts return 504.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
import { defineTuilStories } from "@mwillbanks/tuil-story";

export const stories = defineTuilStories({ component: Button, stories: { Default: { args: { children: "Run" } } } });
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)