# toonstrip documentation

---

# Getting started

> Drop in a script tag and a custom element, render your first strip.

Source: https://toonstrip.danielkimdev.com/docs/getting-started/

toonstrip renders a comic strip from data you supply. There is nothing to generate and no
image pipeline: you write a small JSON document, the page draws it on canvases. This page
gets you from an empty HTML file to a rendered panel, no install and no build step.

## 1. Add the element

`@toonstrip/element` is a custom element with no framework dependency.
[esm.sh](https://esm.sh) resolves it and its dependencies for you, straight from a
`<script type="module">`:

```html
<script type="module">
  import "https://esm.sh/@toonstrip/element@0.1.11";
</script>
```

Pin the exact version, same as any other dependency.

## 2. Point it at a pack

The default pack is the fifteen-character Comic Chat roster with three backdrops. unpkg
serves a pack's files (`pack.json`, sprite sheets, backdrops) as-is, with CORS enabled, so
there is nothing to copy anywhere:

```js
strip.packs = ["https://unpkg.com/@toonstrip/pack-comic-chat@0.1.1/"];
```

## 3. Render a strip

Put a `<comic-strip>` tag in the page and set its `document` property.

```html
<comic-strip id="strip"></comic-strip>

<script type="module">
  import "https://esm.sh/@toonstrip/element@0.1.11";

  const strip = document.getElementById("strip");
  strip.packs = ["https://unpkg.com/@toonstrip/pack-comic-chat@0.1.1/"];
  strip.document = {
    version: 1,
    panels: [
      {
        backdrop: "field",
        camera: "medium",
        bodies: [{ character: "anna", emotion: { angle: 0, intensity: 0.6 } }],
        speakers: [{ speaker: "anna", balloon: "speech", text: "My first strip." }],
      },
    ],
  };
</script>
```


(Example strip `firstStrip` — see https://toonstrip.danielkimdev.com/docs/getting-started/ for the rendered version.)


That is the whole embed: a script tag, a pack URL, and a document. Save it as `index.html`
and open it, no server required.


`npm install @toonstrip/element @toonstrip/pack-comic-chat` works too, but a bare
`import "@toonstrip/element"` only resolves in a browser through a bundler or an import
map — a plain `<script type="module">` cannot do it alone. See [Plain HTML](/docs/plain-html/)
for wiring it into a bundler and serving a pack from your own static files.


## Next

[Write a strip](/docs/writing-a-strip/) walks through the document format with live
examples. [Plain HTML](/docs/plain-html/) covers the element's full API and using it from
a framework. Using Astro, React, or Vue directly? See the
[Astro](/docs/astro-reference/), [React](/docs/react-reference/), or
[Vue](/docs/vue-reference/) reference.

---

# Writing a strip

> The Comic Strip Document, built up from one panel to a two-speaker scene.

Source: https://toonstrip.danielkimdev.com/docs/writing-a-strip/

A strip is a JSON document: a version number and a list of panels. Each panel names a
backdrop, puts some bodies on stage, and gives some of them lines. That is the entire
format. You can write it by hand, generate it from any language, or store it in a CMS field.

## One panel, one speaker


(Example strip `firstStrip` — see https://toonstrip.danielkimdev.com/docs/writing-a-strip/ for the rendered version.)


- `backdrop` is an id from a registered pack. The default pack has `field`, `pastoral`,
  and `room8bs`.
- `bodies` lists who is on stage, left to right. Each body names a `character` id and an
  `emotion`.
- `speakers` lists the balloons. A line's `speaker` must be a body in this panel, or
  `"caption"`.

## Emotion is a point, not a word

`emotion` is `{ angle, intensity }` on a wheel. Angle 0 is HAPPY and each named emotion sits
π/4 further round; intensity runs 0 to 1, and 0 means NEUTRAL whatever the angle. The
renderer picks the nearest face the pack has, so you never get an error for an angle
between two names. [Emotions and poses](/docs/emotions-and-poses/) shows the whole wheel.

| Feeling | angle | intensity |
|---|---|---|
| Neutral | `0` | `0` |
| Happy | `0` | `0.4`–`1` |
| Coy | `0.785` (π/4) | `0.4`–`1` |
| Bored | `1.571` (π/2) | `0.4`–`1` |
| Scared | `2.356` (3π/4) | `0.4`–`1` |
| Sad | `3.142` (π) | `0.4`–`1` |
| Angry | `3.927` (5π/4) | `0.4`–`1` |
| Shout | `4.712` (3π/2) | `0.4`–`1` |
| Laugh | `5.498` (7π/4) | `0.4`–`1` |

## Two speakers

Add a second body and a second line. Balloons draw in `speakers` order and the layout
places each one beside its speaker's head.


(Example strip `twoSpeakers` — see https://toonstrip.danielkimdev.com/docs/writing-a-strip/ for the rendered version.)


## A three-panel strip

Panels are independent: each one names its own backdrop, camera, and cast. Characters keep
their identity across panels, and their pose cycles so the same face is not repeated
panel after panel.


(Example strip `hero` — see https://toonstrip.danielkimdev.com/docs/writing-a-strip/ for the rendered version.)


## Validating

`@toonstrip/schema` ships the JSON Schema and a validator. The element and the Astro
component validate at the boundary, but validating in your build catches mistakes earlier
and with a path to the field.

```ts

try {
  const doc = validateDocument(JSON.parse(raw));
} catch (err) {
  if (err instanceof ComicStripValidationError) console.error(err.message);
}
```

A validation error names the path and the problem:

```
Invalid ComicStripDocument:
  /panels/0/camera must be equal to one of the allowed values
  /panels/0 must NOT have additional property 'emotions'
```


Unknown keys are rejected, not ignored. `emotions` instead of `emotion` is an error, which
is what you want from a format that other tools will write.


The validator checks structure only. Whether a `character` or `backdrop` id exists is
checked when the strip loads against the registered packs, and an unknown id there is a
hard error, never a silent fallback.

## Next

[Emotions and poses](/docs/emotions-and-poses/), then [cameras and panels](/docs/cameras-and-panels/).
Or skip to the [playground](/playground/) and edit any of these strips.

---

# Emotions and poses

> The emotion wheel, rendered face by face, and the three gestures that claim the torso.

Source: https://toonstrip.danielkimdev.com/docs/emotions-and-poses/

A body's `emotion` is a point on a wheel: `angle` in radians, `intensity` from 0 to 1. The
renderer finds the nearest face the character's pack declares and draws that. Because it is
nearest-neighbour, any angle is valid; the names below are the eight points the default
pack draws distinctly.

## The wheel

Nine close-ups of the same character: NEUTRAL, then the eight named angles at intensity 0.8.


(Example strip `emotions` — see https://toonstrip.danielkimdev.com/docs/emotions-and-poses/ for the rendered version.)


| Name | angle | radians |
|---|---|---|
| HAPPY | 0 | `0` |
| COY | π/4 | `0.785` |
| BORED | π/2 | `1.571` |
| SCARED | 3π/4 | `2.356` |
| SAD | π | `3.142` |
| ANGRY | 5π/4 | `3.927` |
| SHOUT | 3π/2 | `4.712` |
| LAUGH | 7π/4 | `5.498` |

## Intensity

Intensity picks between faces at the same angle when a pack has several, and at 0 it
means NEUTRAL regardless of angle. The default pack has two or three faces per emotion for
most characters, so a low and a high intensity often look different.


(Example strip `intensity` — see https://toonstrip.danielkimdev.com/docs/emotions-and-poses/ for the rendered version.)



NEUTRAL shares HAPPY's angle. `{ angle: 0, intensity: 0 }` and `{ angle: 3.142, intensity: 0 }`
are the same face. Think of intensity 0 as the centre of the wheel.


## Poses

`pose` is a separate channel from emotion. It claims the **torso** with a gesture while
`emotion` still picks the **face**, so a character can wave while looking sad. Three
gestures exist: `wave`, `point`, `shrug`. A pack supports a gesture by declaring a torso
for it; the default pack supports all three for every character.


(Example strip `poses` — see https://toonstrip.danielkimdev.com/docs/emotions-and-poses/ for the rendered version.)


## How selection works

Each character has faces and torsos as separate sprites. Per panel, the renderer:

1. Picks the nearest face to the body's emotion point.
2. Picks a torso: the pose's gesture torso if a pose is set, otherwise the torso nearest
   the emotion.
3. Cycles through equally good candidates across panels, so a character repeated in three
   panels does not show the identical drawing three times.

The cycle is frozen per panel when the strip loads, so a resize redraws the same figures.

---

# Cameras and panels

> The six framing presets on one scene, plus room titles, dark panels, and silent bodies.

Source: https://toonstrip.danielkimdev.com/docs/cameras-and-panels/

A panel's `camera` sets how much of the figures and the backdrop you see. The presets are
the six rungs Comic Chat used, and alternating between them is most of what makes a
strip read like a comic rather than a row of identical portraits.

## The six presets

Same two characters, same backdrop, six cameras.


(Example strip `cameras` — see https://toonstrip.danielkimdev.com/docs/cameras-and-panels/ for the rendered version.)


| Preset | Use it for |
|---|---|
| `establishing` | A new location. Figures small, backdrop fully visible. |
| `wide` | A location already seen. Both figures, backdrop incidental. |
| `medium` | The default. Waist-up, room for balloons. |
| `over-shoulder` | One speaker addressing another; the listener is close and partly cropped. |
| `close-up` | One face, most of the frame, backdrop faint. |
| `reaction` | Tight on the head, no balloon expected. A beat panel. |


A three-panel strip that goes establishing → medium → reaction reads naturally: set the
scene, have the conversation, land the beat.


## Room title

`roomTitle` draws a small banner in the panel's top-left. Use it for a place or a channel
name.

## Dark panels

`dark: true` paints the panel black and omits the figures; balloons still draw. Useful for
"the lights go out" beats and for a caption-only panel that should not show a location.

## Silent bodies

A body with no line in a panel is dropped from the stage by default, so a two-character
strip can spend a panel on one of them without editing `bodies`. Set `requested: true` to
keep a silent body on stage.


(Example strip `panelOptions` — see https://toonstrip.danielkimdev.com/docs/cameras-and-panels/ for the rendered version.)

---

# Balloons

> Speech, thought, and caption balloons; how they wrap, stack, and find space beside a head.

Source: https://toonstrip.danielkimdev.com/docs/balloons/

Every entry in a panel's `speakers` becomes one balloon. The `balloon` field picks the
shape; the `speaker` field decides where its tail points.

## Three kinds


(Example strip `balloons` — see https://toonstrip.danielkimdev.com/docs/balloons/ for the rendered version.)


- `speech`: a rounded balloon with a tail to the speaker's head.
- `thought`: a cloud with a trail of bubbles.
- `caption`: a box at the top of the panel, no tail. Its speaker must be `"caption"`.

## Order and placement

Balloons draw in `speakers` order: the caption first (it takes the top), then each speaking
body. The layout tries to put each speech balloon beside its speaker's head in a column
that does not cross another speaker's head, and only when nothing fits does it stack
balloons across the panel. Two speakers in one panel is comfortable; three is possible at
wide cameras; more than that is a strip, not a panel.

## Long lines

Text wraps to the balloon's width, and a balloon grows downward before it grows wider. The
panel does not grow, so a very long line squeezes the figures. Short lines read better and
lay out better.


(Example strip `balloonsLong` — see https://toonstrip.danielkimdev.com/docs/balloons/ for the rendered version.)



Layout never fails. If a balloon truly cannot be placed beside its speaker it stacks in a
corridor the layout reserves per speaker, and at the narrowest panel sizes the text scales
with the panel. From v0.7.11 every layout constant scales with panel width, so the same
document lays out the same way from 400 px panels down to 260 px.


## Writing for the balloon

- One idea per line. Split a long thought into two lines from the same speaker.
- Put the caption first in `speakers`; it is drawn first anyway.
- A `reaction` camera has no room for a balloon; give that panel a caption or no line.
- Avoid text that depends on the tail's exact position. The tail always finds the head;
  the balloon's side is the layout's choice.

---

# Responsive layout

> How the strip decides on one, two, or three columns, and what happens to panel size.

Source: https://toonstrip.danielkimdev.com/docs/responsive-layout/

A strip is a grid of canvases, one per panel, and the column count is computed from the
container's width every time it changes. Nothing is stored; a `ResizeObserver` on the
element re-runs the layout and repaints the affected panels.

## Try it



## The policy

The native panel is 400 × 340 CSS pixels and the maximum is three columns. For a container
`w` pixels wide with a 10 px gutter:

1. Count how many panels of at least 85 % native width fit across `w`, capped at 3.
2. Divide `w` between that many columns.
3. Never stretch a panel past native size. If the share is wider than 400 px, the panel
   stays 400 px and the row is centred.
4. If even one column is narrower than native, the lone panel shrinks to fit.

So a blog column around 700 px gets two columns of ~345 px panels; a full-width section
above ~1060 px gets three native panels; a phone gets one column, scaled down.

| Container width | Columns | Panel width |
|---|---|---|
| 360 px | 1 | 360 px |
| 700 px | 2 | 345 px |
| 900 px | 2 | 400 px (centred) |
| 1100 px | 3 | 360 px |
| 1300 px | 3 | 400 px (centred) |

## Sharpness

Each canvas has a backing store sized `width × devicePixelRatio`, so a 2× display gets a
2× bitmap. Zooming the page re-lays out and repaints; nothing is a scaled bitmap.

## Off-screen panels

Panels are painted only when they are within one viewport of the visible area, and their
bitmaps are released when they scroll far away. A strip with fifty panels costs as much
memory as the handful near the reader. The consequence for tooling: a full-page screenshot
shows unpainted panels as dark boxes. Scroll them into view first.

## Embedding advice

- Give the element the full width of its column. It is `display: block` and measures its
  own box.
- Do not set a height. The height follows from the column count.
- Do not style the canvases. Put spacing, borders, or a background on a wrapper.

---

# Asset packs

> Using the two shipped packs, registering more than one, and adding a character of your own.

Source: https://toonstrip.danielkimdev.com/docs/asset-packs/

An asset pack supplies the art a document refers to by id: character sprite sheets with a
pose table, and backdrop images. The renderer never ships art of its own.

## The two shipped packs

| Pack | npm | name | Contents |
|---|---|---|---|
| Comic Chat | `@toonstrip/pack-comic-chat` | `comic-chat` | 15 characters, 3 backdrops. The original Microsoft Comic Chat art, MIT. |
| Example | `@toonstrip/pack-example` | `example` | 1 character (`pip`), 1 backdrop (`meadow`). Original, tiny, and the template for your own. |


(Example strip `pip` — see https://toonstrip.danielkimdev.com/docs/asset-packs/ for the rendered version.)


## Registering more than one

List every pack in the integration and name the ones a strip needs in the component. Ids
resolve across all registered packs; a character or backdrop id declared by two packs is a
load-time error, not a silent first-match.

```js
// astro.config.mjs
toonstrip({ packs: ["@toonstrip/pack-comic-chat", "@toonstrip/pack-example"] })
```

```astro

```


(Example strip `mixedPacks` — see https://toonstrip.danielkimdev.com/docs/asset-packs/ for the rendered version.)


## Pack layout

```
my-pack/
  pack.json                      # name, version, license, characters[], backdrops[]
  characters/<id>/sheet.png      # one sprite sheet per character
  characters/<id>/<id>.json      # that character's parts: faces, torsos, rects, sockets
  backdrops/<id>.png
  NOTICE                         # required if any art is not wholly yours
```

`pack.json`:

```json
{
  "name": "my-pack",
  "version": "0.1.0",
  "license": "MIT",
  "characters": [
    { "id": "pip", "name": "Pip", "manifest": "characters/pip/pip.json", "sheet": "characters/pip/sheet.png" }
  ],
  "backdrops": [
    { "id": "meadow", "file": "backdrops/meadow.png", "width": 240, "height": 240 }
  ]
}
```

`name` is what strips reference, not the npm package name. `license` is required on every
pack.

## A character manifest

A character is parts, not finished drawings: faces and torsos as rectangles in the sheet,
each tagged with an emotion point, plus the neck socket so a face sits on any torso.

```ts
interface PackedAvatar {
  name: string;
  type: string;
  torsoFirst: boolean;     // torso draws over the collar, or under it
  sheet: string;           // path relative to this manifest
  sheetWidth: number;
  sheetHeight: number;
  faces: PackedPart[];
  torsos: PackedPart[];
  bodies: PackedPart[];    // unused today; leave empty
}

interface PackedPart {
  kind: "face" | "torso" | "body";
  index: number;
  emotion: string;         // "NEUTRAL", "HAPPY", … or a gesture name
  angle: number;           // wheel angle, or 1001 wave / 1002 point / 1005 shrug
  intensity: number;
  cx: number; cy: number;  // neck socket
  cxDelta: number; cyDelta: number;
  x: number;               // where a balloon tail attaches
  figure: { x: number; y: number; width: number; height: number };
  aura: { x: number; y: number; width: number; height: number } | null;
}
```

Minimum: one face with `emotion: "NEUTRAL"` and one torso. Gestures are torsos at the
sentinel angles (`1001` wave, `1002` point, `1005` shrug); support the ones you draw.

## Validate

```
npx -p @toonstrip/cli toonstrip pack validate ./my-pack
```

Checks `pack.json`, every declared file, the NEUTRAL face, and that each backdrop's real
pixel size matches what `pack.json` claims. It lists every problem, not just the first.


A character with faces but no torsos validates today and then renders nothing. Always
declare at least one torso.


## Adding a character, step by step

1. Draw the parts on one sheet (any editor, or a script). At minimum a NEUTRAL face and a
   torso, each a clean rectangle.
2. Write the manifest: copy `pip.json` from the example pack and replace the rectangles
   and sockets with yours.
3. Add the character to `pack.json`.
4. Run `pack validate`.
5. Render one panel with it in the [playground](/playground/) by serving your pack
   locally, or in a Node script through `@toonstrip/core`'s `renderPanel`.

The example pack's sheet is drawn by a 60-line script with `@napi-rs/canvas`; it is the
smallest complete pack and the one to copy.


Doing this from real drawings rather than rectangles? Don't write the manifest by hand:
[`@toonstrip/asset-packager`](/docs/asset-packager/) takes a folder of per-pose PNGs, or one
labelled sheet, and writes `pack.json`, the sprite sheets and the sockets for you.


## Licensing

Say what the art is. If any of it is not wholly yours, ship a `NOTICE` crediting the
source and its licence. The default pack's `NOTICE` (Microsoft Comic Chat art, MIT, with a
trademark disclaimer) is the worked example.

---

# Plain HTML

> The comic-strip custom element without Astro, in any page or framework.

Source: https://toonstrip.danielkimdev.com/docs/plain-html/

`@toonstrip/element` is a custom element with no framework dependency. The Astro component
is a thin wrapper around it; everything it does, the element does on its own.

## Install

```
npm install @toonstrip/element @toonstrip/pack-comic-chat
```

Serve the pack's files somewhere the browser can fetch them. The pack package contains
`pack.json`, `characters/`, and `backdrops/`; copy that directory to your static assets, for
example `public/packs/comic-chat/`.

## Use

```html
<comic-strip id="strip"></comic-strip>

<script type="module">
  import "@toonstrip/element";

  const strip = document.getElementById("strip");
  strip.packs = ["/packs/comic-chat/"];
  strip.document = {
    version: 1,
    panels: [
      {
        backdrop: "pastoral",
        camera: "establishing",
        bodies: [{ character: "dan", emotion: { angle: 0, intensity: 0.6 } }],
        speakers: [{ speaker: "caption", balloon: "caption", text: "A field outside town." }],
      },
    ],
  };
</script>
```

## API

| Member | Type | Meaning |
|---|---|---|
| `packs` | `string[]` property | Base URLs of asset packs, each serving `pack.json` and its files. Searched in order; duplicate ids across packs throw. |
| `document` | `ComicStripDocument` property | The strip. Validated on set. Setting it again re-renders. |
| `columns` | `number` getter | Column count from the last layout pass. |

Setting `document` before `packs` is fine; the element rebuilds on either change and the
last set wins.


Validation errors and unknown ids are reported by replacing the strip with a short red
notice and logging to the console. Nothing throws out of a property setter.


## From a framework

React, Vue, Svelte, and the rest can all render a custom element and set properties on it.
The one thing to remember is that `packs` and `document` are **properties**, not
attributes: set them from a ref after mount, or use your framework's property-binding
syntax (`.document={doc}` in Lit, `prop:document={doc}` in Solid, `:document.prop` in Vue).
For React and Vue specifically, `@toonstrip/react` and `@toonstrip/vue` package exactly
this pattern as a `` component. See [React reference](/docs/react-reference/)
and [Vue reference](/docs/vue-reference/).

## Bundling

The element imports `@toonstrip/core` and `@toonstrip/schema`; any ESM bundler handles it.
The schema is embedded at build time as plain data, and validation runs as ordinary JS
with no `eval`, so a strict Content Security Policy does not need `unsafe-eval`.

## No build step at all

The `install`/`npm`/bundler steps above assume *something* resolves the bare
`import "@toonstrip/element"` specifier. With no bundler and no import map, use
[esm.sh](https://esm.sh) instead, which resolves a package's own dependencies for you:

```html
<script type="module">
  import "https://esm.sh/@toonstrip/element@0.1.11";
</script>
```

Point `packs` at a CDN too: unpkg serves a pack's static files (`pack.json`, sprite
sheets, backdrops) as-is, with CORS enabled:

```js
strip.packs = ["https://unpkg.com/@toonstrip/pack-comic-chat@0.1.1/"];
```

The full worked example is `examples/vanilla-html/index.html` in the repo: one file, no
`package.json`, opens from `file://` or any static file server. Pin exact versions in
both URLs, same as any other dependency. See the repo's `docs/vanilla-html.md` for the
esm.sh-vs-unpkg reasoning in full.

---

# Astro reference

> Every option of the integration and the component, and the current limitations.

Source: https://toonstrip.danielkimdev.com/docs/astro-reference/

## `toonstrip(options)`

The integration, added to `integrations` in `astro.config.mjs`.

| Option | Type | Meaning |
|---|---|---|
| `packs` | `string[]` | npm specifiers of asset packs to serve. Each is resolved, and its `pack.json`, `characters/`, and `backdrops/` are copied to `public/_toonstrip/<pack name>/` during `astro:config:setup`. Default: none. |

The integration also registers a renderer for ``. The server half emits an
inert `<comic-strip>` tag; the client half imports `@toonstrip/element` and sets the
properties. Nothing else touches your Vite config.

## ``

```astro
---
---

```

| Prop | Type | Meaning |
|---|---|---|
| `document` | `ComicStripDocument` | The strip. Any object of the right shape; usually an imported JSON file. |
| `packs` | `string[]` | Pack **names** (the `name` field of each `pack.json`), resolved to `/_toonstrip/<name>/`. Default `[]`, which renders nothing useful, so always pass at least one. |

Any Astro client directive works. `client:visible` is the documented default; use
`client:load` above the fold and `client:idle` for a strip near the top that is not the
first thing the reader needs.

## What renders on the server

Only the tag. There is no server-side canvas in the component, so there is no content
without JavaScript beyond the element's `aria-label`s, which are generated client-side too.
For a static image (Open Graph, RSS, a `<noscript>` fallback) render the same document at
build time with `npx -p @toonstrip/cli toonstrip render strip.json --out strip.png` from `@toonstrip/cli`; it
uses the same layout policy and figure selection as the element.

## Limitations

- Tested against Astro 7. Astro 5 and 6 should work (nothing version-specific is used) but
  are not in the test matrix.
- The renderer is hand-written, not `@astrojs/lit`, because the element is a plain
  `HTMLElement` with no framework dependency. This is deliberate.
- `packs` in the integration and `packs` in the component take different things
  (specifiers vs names). The names come from each pack's `pack.json`.


The `public/_toonstrip/` directory is generated on every build and dev start. Add it to
`.gitignore`.

---

# React reference

> The <ComicStrip> component's props, and why prop updates don't remount the element.

Source: https://toonstrip.danielkimdev.com/docs/react-reference/

## ``

```tsx


```

| Prop | Type | Meaning |
|---|---|---|
| `document` | `ComicStripDocument` | The strip. Any object of the right shape; usually an imported JSON file. Pushed onto the element whenever it changes. |
| `packs` | `string[]` | Base URLs of asset packs (same shape as `packages/element`'s own `.packs`, not the pack **names** `@toonstrip/astro`'s component takes, since there's no integration step resolving names to URLs here). Default `[]`. |
| `placeholder` | `{ src, width, height }` | An SSR-rendered PNG to show, as a light-DOM `<img>`, until the live canvas paints. See [Next.js reference](/docs/next-reference/): `@toonstrip/cli`'s `renderPlaceholder` produces this shape. Optional; most apps don't set it directly. |
| `className` / `style` | n/a | Forwarded straight to the underlying `<comic-strip>` element. |

The component has no rendering logic of its own: it mounts `<comic-strip>` via a ref and
sets `document`/`packs` as DOM properties in a `useEffect`, the same way
`@toonstrip/astro`'s client renderer does.

## Updating without a remount

`` always renders the same host tag in the same position, so React's
reconciliation reuses the existing `<comic-strip>` DOM node across re-renders. A new
`document` value updates that node in place rather than tearing it down and rebuilding
it. Verified during M10 by tagging the live element with a scratch property from
devtools' console, then confirming it survived a `document` change.

## Worked example

`examples/react-vite` in the repo is a Vite + React app: a toggle button swaps between
two hand-written documents, and `scripts/copy-pack-assets.mjs` copies
`@toonstrip/pack-comic-chat`'s files into `public/packs/comic-chat/` before `dev`/`build`
(Vite has no integration-hook system the way Astro does, so this is a plain Node script
rather than a config-time hook). Run it locally:

```
pnpm --filter react-vite-example dev
```

## Current limitations

- Tested against React 18. The `peerDependencies` range also allows React 19, but 19
  isn't in the test matrix yet.


Importing `@toonstrip/element` no longer throws on the server (it guards `HTMLElement`/
`customElements` access), so this package is safe to render server-side. ``
also carries its own `'use client'` directive, so it's directly usable from a Next.js App
Router Server Component with no extra wrapper. See
[Next.js reference](/docs/next-reference/) for the SSR-placeholder helper
(`@toonstrip/cli`'s `renderPlaceholder`) that goes with it.



Vue is also published. See [Vue reference](/docs/vue-reference/). Svelte isn't yet;
until then, [Plain HTML](/docs/plain-html/)'s "From a framework" section covers using the
custom element directly with any framework's property-binding syntax.

---

# Vue reference

> The <ComicStrip> component's props, and why prop updates don't remount the element.

Source: https://toonstrip.danielkimdev.com/docs/vue-reference/

## ``

```vue
<script setup>
</script>

<template>
  
</template>
```

| Prop | Type | Meaning |
|---|---|---|
| `document` | `ComicStripDocument` | The strip. Any object of the right shape; usually an imported JSON file. Pushed onto the element whenever it changes. |
| `packs` | `string[]` | Base URLs of asset packs (same shape as `packages/element`'s own `.packs`, not the pack **names** `@toonstrip/astro`'s component takes, since there's no integration step resolving names to URLs here). Default `[]`. |
| `class` / `style` | n/a | Fall through to the underlying `<comic-strip>` element automatically (Vue's default single-root attribute inheritance), not declared as props. |

The component has no rendering logic of its own: it mounts `<comic-strip>` via a template
ref and sets `document`/`packs` as DOM properties from a `watch`, the same way
`@toonstrip/astro`'s client renderer does.

## Updating without a remount

`` always renders the same host tag (`h("comic-strip", { ref })`, a render
function rather than an SFC `<template>` for this one tag, which sidesteps needing
`compilerOptions.isCustomElement` just for `comic-strip`), so Vue's patching reuses the
existing `<comic-strip>` DOM node across re-renders. A new `document` value updates that
node in place rather than tearing it down and rebuilding it. Verified during M11 by
tagging the live element with a scratch property from devtools' console, then confirming
it survived a `document` change.

## Worked example

`examples/vue-vite` in the repo is a Vite + Vue app: a toggle button swaps between two
hand-written documents, and `scripts/copy-pack-assets.mjs` copies
`@toonstrip/pack-comic-chat`'s files into `public/packs/comic-chat/` before `dev`/`build`
(Vite has no integration-hook system the way Astro does, so this is a plain Node script
rather than a config-time hook, the same script `examples/react-vite` uses). Run it
locally:

```
pnpm --filter vue-vite-example dev
```

## Current limitations

- Tested against Vue 3.5. No Nuxt-specific wrapper yet. `@toonstrip/element`'s module no
  longer throws when imported on a server (it guards `HTMLElement`/`customElements`
  access, dev plan §13.4), so this package is safe to import in a Nuxt server render pass.
  Per [Next.js reference](/docs/next-reference/)'s deprecation of `@toonstrip/next`,
  a dedicated Nuxt package probably isn't the answer either: a client-boundary marker
  (Nuxt's own equivalent of `'use client'`) belongs directly on this package's component,
  and an SSR-placeholder helper already exists on `@toonstrip/cli`.


Svelte isn't published yet. Until then, [Plain HTML](/docs/plain-html/)'s "From a
framework" section covers using the custom element directly with any framework's
property-binding syntax.

---

# Next.js (deprecated)

> <ComicStrip> behind an App-Router-safe client boundary, plus an SSR placeholder helper, now built into @toonstrip/react and @toonstrip/cli directly.

Source: https://toonstrip.danielkimdev.com/docs/next-reference/

`@toonstrip/next` used to wrap two things Next.js App Router needs: a `'use client'`
boundary and a server-only PNG-placeholder helper. Both now live directly on the
packages that do the work, so the wrapper adds nothing on top of them. Existing installs
keep working (it's a re-export shim, not removed); new code should import from
[`@toonstrip/react`](/docs/react-reference/) and `@toonstrip/cli` instead, as shown below.


## ``

```tsx
// app/page.tsx: a Server Component; no "use client" needed here


```

Same props as [`@toonstrip/react`](/docs/react-reference/)'s ``. The
component itself carries a `'use client'` directive, the boundary React Server
Components require around anything using `useRef`/`useEffect`. You can import it directly
from a Server Component; you don't need to mark your own page `'use client'`.

## SSR placeholder

```tsx
// app/page.tsx

export default async function Page() {
  // Dynamic + webpackIgnore, not a static import; see the callout below.
  const { renderPlaceholder } = await import(/* webpackIgnore: true */ "@toonstrip/cli");
  const placeholder = await renderPlaceholder(doc, { width: 640 });
  return ;
}
```

`renderPlaceholder` reuses `@toonstrip/cli`'s headless-canvas render path (the same one
behind [`toonstrip render`](/docs/astro-reference/)) to produce a PNG on the server,
sized in CSS pixels to match the `width` you give it. `` renders that as a
light-DOM `<img slot="placeholder">` inside `<comic-strip>`, present in the raw server
HTML with no client JS, so it shows with JavaScript disabled and in "view source". Once
client JS hydrates and the live canvas is ready, `@toonstrip/element` hides the placeholder
and shows the live strip itself; no code drives that swap directly.

Match the `width` you pass to `renderPlaceholder` to the CSS width your `` is
actually laid out at. A mismatch produces a placeholder sized differently than the live
strip, which shows up as a layout shift on hydration.

`renderPlaceholder` pulls in `@toonstrip/cli`, which loads `@napi-rs/canvas`, a native
Node addon that must never end up in a client bundle. Only call it from a Server
Component or other server-only code.


`@toonstrip/cli`'s native dependency needs two things in your app's own `next.config`:
list `@napi-rs/canvas` and `@toonstrip/cli` under `serverExternalPackages`, and add
`@toonstrip/cli` as your app's own direct dependency (not only a transitive one). Even
with both, a **static** import of `renderPlaceholder` still makes webpack try to bundle
the native binaries when `@toonstrip/cli` is a workspace-symlinked local package (as in
this monorepo's own example), hence the `webpackIgnore`d dynamic `import()` above. See
`examples/next-app`'s `next.config.mjs` and `app/page.tsx` for a working setup.


## Worked example

`examples/next-app` in the repo is an App Router app: a Server Component page renders a
strip with a placeholder, `scripts/copy-pack-assets.mjs` copies
`@toonstrip/pack-comic-chat`'s files into `public/packs/comic-chat/` for the client-side
cast fetch (same script `examples/react-vite` and `examples/vue-vite` use), and
`renderPlaceholder` reads the pack straight from `node_modules` for the server-side render.
Run it locally:

```
pnpm --filter next-app-example build && pnpm --filter next-app-example start
```

## Current limitations

- Tested against Next.js 15 (App Router) and React 18. Pages Router isn't covered.
- No Nuxt-equivalent wrapper yet. See [Vue reference](/docs/vue-reference/)'s note on
  that.


`@toonstrip/element`'s module no longer throws when imported on a server. That guard
(dev plan §13.4) is what makes ``'s client boundary safe to import from a
Server Component in the first place.

---

# Schema reference

> Every field of the Comic Strip Document, generated from the published JSON Schema.

Source: https://toonstrip.danielkimdev.com/docs/schema-reference/

The tables below are generated at build time from `@toonstrip/schema`'s `schema.json`
(draft-07, `additionalProperties: false` throughout). Field names, types, and required-ness
come from the schema; the one-line descriptions are maintained on this site.


The TypeScript types are exported from `@toonstrip/schema` as `ComicStripDocument`,
`Panel`, `Body`, `Line`, `Emotion`, `CameraPreset`, and `BalloonKind`. The JSON Schema is
the authoritative machine-checkable version for non-TypeScript producers.

---

# Accessibility

> What the element emits for assistive technology, and how to write lines that read well aloud.

Source: https://toonstrip.danielkimdev.com/docs/accessibility/

A canvas is a bitmap; on its own it says nothing to a screen reader. The element fixes
that per panel, from the document itself, so the same data that draws the strip describes
it.

## What the element emits

Every panel's `<canvas>` carries `role="img"` and an `aria-label` generated from the panel:
the camera shot, the room title if any, then each line in order with its speaker and
balloon kind. The three panels on the home page read as:

```
establishing shot; caption: toonstrip draws comic strips from data.; dan says "You write the panels as JSON."
medium shot; anna says "And it draws them right here, on a canvas?"; dan says "Live. Resize the page and watch it reflow."
reaction shot; anna thinks "No build step for the art. No image files to keep in sync."
```

Thought balloons read as "thinks", speech as "says", captions as "caption:". A dark panel
is announced as such.

The generator is `describePanel` in `@toonstrip/element`, exported so a site can reuse it
for a visible transcript or a `<figcaption>`.

## Writing lines that read well

- Use the character's display name in the text when it matters; the label uses the id
  (`dan`), which is what the document has.
- Put the beat in words. A `reaction` panel with no line is announced only as "reaction
  shot"; a caption gives it content.
- Keep punctuation conventional. Screen readers pause on periods and commas, not on
  ellipses or dashes.
- Do not encode meaning in emotion alone. `SAD` changes the face, not the label.

## Around the element

- Wrap a strip in `<figure>` with a `<figcaption>` when it illustrates surrounding text.
- Do not rely on colour in captions or titles; the art is monochrome anyway.
- Motion: the element animates nothing. Resizes repaint instantly.

## Known gaps

- There is no visible-text fallback when JavaScript is off, because the labels are
  generated client-side. Pair a `<noscript>` image from `toonstrip render` with a written
  transcript if that matters for your page.
- Focus: canvases are not focusable and there is nothing to operate, so the strip is
  skipped in the tab order, which is correct for an image.

---

# FAQ

> No AI, no game engine, the licence and the trademark, browser support, and server rendering.

Source: https://toonstrip.danielkimdev.com/docs/faq/

## Does toonstrip generate the comic for me?

No, and it never will. toonstrip renders a document you give it. Writing the dialogue,
choosing emotions and cameras, deciding what is funny: that is the author's job, or a
script's, or a language model's if you choose to call one. Whatever produces the JSON, it
lives outside this library. The playground on this site is an editor, not a generator.

## Is there text-to-emotion inference?

No. Comic Chat guessed a mood from the words you typed; toonstrip does not read your text.
You set `emotion` per body. If you want inference, build it in front of toonstrip and
write the result into the document.

## Is this a game engine or a chat client?

No. There is no session, no turn, no event stream. A panel is authored data. toonstrip
was extracted from a project that did have a game behind it, and the game stayed there.

## What is the licence, and can I use the characters commercially?

The code is MIT. The default pack's art is Microsoft Comic Chat art redistributed under
MIT with Microsoft's copyright notice preserved; see the repository's `NOTICE`. MIT permits
commercial use. COMIC CHAT is a Microsoft trademark and this project is not affiliated
with Microsoft, so do not name your product after it. Your own packs carry whatever
licence you put in their `pack.json`.

## Which browsers?

Anything with Canvas 2D, custom elements, `ResizeObserver`, and `IntersectionObserver`:
every current browser. No polyfills are shipped.

## Does it render on the server?

Not in the Astro component: the server emits an inert tag and the browser draws. For a
static PNG (Open Graph images, RSS, `<noscript>` fallbacks) use the CLI, which runs the
same renderer in Node:

```
npx -p @toonstrip/cli toonstrip render strip.json --out strip.png --width 1200
```

## Can I use it outside Astro?

Yes. The custom element has no framework dependency; see [plain HTML](/docs/plain-html/).
Astro is the first-class wrapper because it is what the author uses. Other wrappers would
be a few lines each.

## How big is it?

The element plus core plus the schema validator is about 36 KB gzipped (measured on the
published builds).
Sprite sheets are fetched per character actually used in a document, so a three-character
strip loads three sheets and one backdrop, not the whole pack.

## Why does Korean (or other non-Latin) text look wrong?

Balloon text is drawn on a canvas in Comic Sans, which has no Hangul, so those glyphs
fall through the font stack: Noto Sans KR first, then the platform's Korean sans face
(Apple SD Gothic Neo, Malgun Gothic). Before `@toonstrip/core` 0.1.7 the stack named no Korean face at all
and Windows landed on Gungseo, a brush script. To get Noto Sans KR everywhere, declare it
on the page (this site uses Astro's fonts API with the `korean` subset); the element
waits for `document.fonts` before painting and repaints if a face arrives late. For
`toonstrip render`, pass `--font NotoSansKR-Regular.ttf`.

## Why is the art black and white?

Because the original Comic Chat art is. A pack can be in colour; nothing in the renderer
assumes monochrome.

## Can an AI agent write documents for me?

toonstrip still won't generate content (see the first question above), but there's an
[agent skill](/docs/agent-skill/) that teaches a coding agent the document shape, the
emotion-wheel angles, and the real character/backdrop ids, so it stops guessing and
validates what it writes before handing it back.

## Where do I report a bug or contribute a character?

[GitHub issues](https://github.com/dkdev24/toonstrip/issues). For a character, read
[asset packs](/docs/asset-packs/) and open a pull request against `pack-example` or your
own pack repository.

---

# Agent skill

> A packaged SKILL.md that teaches an AI coding agent the document shape, so it stops guessing.

Source: https://toonstrip.danielkimdev.com/docs/agent-skill/

toonstrip does not generate strips (see the [FAQ](/docs/faq/)), but if you're asking an
AI coding agent to author a `ComicStripDocument` for you, it should not have to guess the
shape, the emotion-wheel angles, or which character ids actually exist. `skills/toonstrip/SKILL.md`
in the repository packages exactly that knowledge into one file an agent can load.

## What it teaches

- The full [`ComicStripDocument`](/docs/schema-reference/) v1 shape (`Panel`, `Body`,
  `Line`), including that every object is `additionalProperties: false`, so a typo'd key
  fails validation instead of being silently ignored.
- The exact [emotion wheel](/docs/emotions-and-poses/) angles (`HAPPY` at `0`, `SAD` at
  `Math.PI`, and so on) as a lookup table, so the agent hits a named point instead of
  inventing a number.
- The default `@toonstrip/pack-comic-chat` pack's real 15 character ids and 3 backdrop
  ids. An agent using this skill will not fabricate a `character` or `backdrop` that
  doesn't exist, which is otherwise a hard error at render time, not a silent fallback.
- The `toonstrip render` workflow as the required last step: never hand back a document
  without actually running it through the CLI first.

## Using it

Drop the file into wherever your agent looks for skills. For [Claude Code](https://claude.com/claude-code),
that's a `SKILL.md` under `.claude/skills/`:

```
mkdir -p .claude/skills/toonstrip
curl -o .claude/skills/toonstrip/SKILL.md \
  https://raw.githubusercontent.com/dkdev24/toonstrip/main/skills/toonstrip/SKILL.md
```

Other agents that support a similar convention can point at the same file directly.
It's plain Markdown with a YAML frontmatter header, so no toonstrip-specific tooling
is required to read it.


No skill support in your agent? Paste the file's contents into the prompt directly, or
point the agent at <a href="/llms-full.txt">/llms-full.txt</a>, the whole docs site as
one Markdown file, which covers the same schema and workflow in more depth.


## Verifying it worked

The skill's own instructions end with "run `toonstrip render`, don't just hand back
JSON." If an agent using this skill gives you a document, the fast check is the same one
the skill teaches:

```
npx @toonstrip/cli render doc.json --out strip.png
```

A schema error or an unresolved character/backdrop id fails loudly (`FAIL:`, exit 1)
with every problem listed, not just the first. A clean run means the document is both
structurally valid and actually resolves against a real pack.

## Source

[`skills/toonstrip/SKILL.md`](https://github.com/dkdev24/toonstrip/blob/main/skills/toonstrip/SKILL.md)
in the repository. It has no dependency on any other milestone in this project's plan.
The schema and CLI it teaches are already stable and published.

---

# Asset packager

> Turn a folder of PNGs, or one labelled sheet, into a valid toonstrip asset pack.

Source: https://toonstrip.danielkimdev.com/docs/asset-packager/

Writing a [pack](/docs/asset-packs/) by hand means writing `pack.json`, a manifest per
character, sprite-sheet rectangles and a face/torso socket for every pose. `@toonstrip/asset-packager`
does that part: you supply finished drawings, it validates them, packs the sheets, derives
the join and writes the pack.

It is offline and deterministic. No model call, no network: it consumes PNGs, whether they
came out of an image model, Procreate or Aseprite. toonstrip still generates no art (see the
[FAQ](/docs/faq/)); this is the step *after* you have some.

```
npm install -D @toonstrip/asset-packager
```

## The whole loop

```
# 1. scaffold a source pack
npx -p @toonstrip/asset-packager toonstrip-pack init ./my-source --name my-pack

# 2. draw or generate the poses into ./my-source/characters/<id>/, then check them
npx -p @toonstrip/asset-packager toonstrip-pack validate ./my-source

# 3. build, and look at the join preview before shipping
npx -p @toonstrip/asset-packager toonstrip-pack build ./my-source --out ./my-pack --preview joins.png

# 4. the output is a normal pack
npx -p @toonstrip/cli toonstrip pack validate ./my-pack
npx -p @toonstrip/cli toonstrip render strip.json --out strip.png --pack ./my-pack
```

`--force` builds despite errors, for when you want to look at a broken pack rather than read
about it.


`toonstrip-pack` (the packager, source in) and `toonstrip` (the [CLI](/docs/getting-started/),
pack out) are separate commands. Step 4 above runs the second one against the first one's
output as an independent check.


## Two ways in

### One PNG per pose

```
my-source/
  source.json                      # name, version, license, spec overrides
  characters/<id>/
    face-NEUTRAL.png               # required
    torso-NEUTRAL.png              # required
    face-HAPPY.png
    torso-WAVE.png
    face-SAD@0.5-2.png             # optional intensity and variant
  backdrops/<id>.png
```

Filenames are `<kind>-[@<intensity>][-<variant>].png`, with `kind` either `face` or
`torso` and `EMOTION` one of the nine face names (`NEUTRAL`, `HAPPY`, `COY`, `BORED`,
`SCARED`, `SAD`, `ANGRY`, `SHOUT`, `LAUGH`) or nine torso names (`NEUTRAL`, `WAVE`,
`POINTOTHER`, `POINTSELF`, `DOUBLEPOINT`, `SHRUG`, `3QRWALK`, `SIDEWALK`, `3QFWALK`). Case
matters, and anything unrecognised in the directory is ignored rather than rejected, so
reference sketches can live alongside the art.

Every part is a **square, transparent PNG, one pose per file**, at least 256×256 and ideally
1024×1024. A face is a head with a short neck stub, ending at the join; a torso is shoulders
to waist with the neck line at its top edge and the bottom running off the canvas. The full
rules are in [`docs/asset-image-spec.md`](https://github.com/dkdev24/toonstrip/blob/main/docs/asset-image-spec.md).

### One sheet, many assets

When the art comes from an image model, generate a grid in one pass instead of a file per
pose: identity cannot drift between cells, and the packager registers every pose against the
character's NEUTRAL cell. Backdrops work the same way: one image, many scenes.

```
# a reference sheet to prompt with; also prints the source.json fragment and a prompt
npx -p @toonstrip/asset-packager toonstrip-pack template --out ref.png
npx -p @toonstrip/asset-packager toonstrip-pack template --out scenes.png --kind backdrop --ids hall,cellar,attic --columns 2
```

The grid shape is yours to declare. Name the cells in `source.json`:

```json
{
  "characters": [
    {
      "id": "pim",
      "sheet": {
        "file": "characters/pim/sheet.png",
        "layout": [
          ["face-NEUTRAL", "face-HAPPY"],
          ["torso-NEUTRAL", "torso-WAVE"]
        ],
        "labelBand": 0.1
      }
    }
  ],
  "backdropSheets": [
    { "file": "backdrops/interiors.png", "ids": ["hall", "cellar", "attic", "kitchen"], "columns": 2 }
  ]
}
```

Cells are sliced on the gutters actually present rather than on an even division, so a
model's imprecision is absorbed. Label bands are cropped first, and character cells are keyed
by flood-filling in from the edges: a flat white background is expected here, because few
models emit transparency. A white shirt stays white; it is not connected to the edge.


A background that is not flat (a gradient, a painted room, a checkerboard standing in for
transparency) cannot be keyed, and you get `background is not transparent`. Ask for a plain
single-colour background.


A sheet costs detail. A model capping at 1536px gives roughly 512px cells on a 3×3 and about
300px on a 5×4; against the default 256px `cell`, a 3×3 is comfortable and a 5×4 is marginal.
The packager errors when the grid cannot carry the pack's cell size. Options and diagnostics
in full: [`docs/asset-sheets.md`](https://github.com/dkdev24/toonstrip/blob/main/docs/asset-sheets.md).

### Mixing the two

A per-pose file **overrides** a sheet cell of the same name. That is the fix for one weak
cell: regenerate that pose on its own with the sheet as reference, drop it in as
`characters/<id>/face-LAUGH.png`, rebuild. No edit to `source.json`.

## The join

A face and a torso are separate drawings composited at render time, so the packager has to
know where the head meets the neck. Three routes, in priority order:

1. `anchors` in `source.json`: explicit input-canvas pixel coordinates.
2. A single opaque magenta (`#ff00ff`) marker pixel in the art, erased before packing.
3. The convention: a face joins at the bottom-centre of its drawing, a torso at the
   top-centre of its.

The join is derived once per character from its **NEUTRAL** pose and reused for every other
pose. Keep the head and body in the same place across poses and change only the expression or
the arms.

A wrong join still produces a *valid* pack, which is what `--preview` is for: it composites
each character's NEUTRAL pair and crosses the join, so a floating or buried head is visible
at a glance. Look at it before shipping.

## Errors vs warnings

`validate` and `build` both report the same two-tier diagnostics, and list every problem
rather than stopping at the first.

**Errors** block the build: a non-square canvas, an opaque background on the per-pose path, a
missing NEUTRAL face or torso, an unknown emotion name, a blank or misnamed sheet cell, a
grid too dense for the pack's cell size.

**Warnings** build anyway and are worth a look: a soft or feathered outline, a drawing running
into a gutter, a pose more than 12% off the NEUTRAL cell's scale, a torso floating above the
bottom of its canvas, a character with only one pose, two near-identical backdrop cells.

Sheet diagnostics name the cell they are about, as `sheet.png[column,row] -> name`.

## As a library

The CLI is a thin wrapper; both stages are importable.

```ts

const { report } = await analyze("./my-source");   // errors + warnings
const result = await buildPack({ source: "./my-source", out: "./my-pack" });
```

## Licensing what you build

Say what the art is. If any of it is not wholly yours (including anything a model produced
from a reference you do not own), ship a `NOTICE` crediting the source and its licence. The
default pack's `NOTICE` (Microsoft Comic Chat art, MIT, with a trademark disclaimer) is the
worked example. `source.json`'s `license` field lands in the built `pack.json`.