asciify-engine 4.13.0 → 4.14.0

package/skills/asciify-engine/references/applying-asciify.md

@@ -0,0 +1,234 @@
+# Applying Asciify: the house design
+
+How asciify.org puts characters into a real interface. Read this before choosing a component or a background, then take the call from [components.md](components.md) and its options from [kit.md](kit.md). Every rule here is one you can check in the browser.
+
+The site's claim is the brief: ASCII that belongs in your interface. Characters are a material the interface uses for a job (showing work, confirming an outcome, moving between states, setting one ground for a page), drawn in the page's own ink, inside its own shapes, at its own pace.
+
+## 1. Give the characters a job
+
+Pick by what the field does for the person, not by how it looks.
+
+| Job | Use |
+| --- | --- |
+| Show that work is running | `buttonLoading`, `statusOrb`, `thinking`, `streamText`, `skeleton`, `imageGenerate`, `pullRefresh` |
+| Confirm or refuse an outcome | `statusOrb` success, warning or error; `slideToConfirm`; `codeInput` `verify()`; `beam` `success()` or `error()` |
+| Show a value changing | `odometer`, `pill` counts, `blockChart` |
+| Move between states or views | `tabs`, `pageDissolve`, `commandPalette`, `toastStack`, `disintegrate` |
+| Answer a gesture | `likeBurst`, `swipeDeck`, `compare`, `accordion`, `dropzone` |
+| Carry a brand moment or media | `decode`, `wordmark`, `asciiVideo`, `artPanel`, `pricingGlow`, `fieldBackground` `notFound` |
+| Set the page's one ground | `fieldBackground` `hero`, or `background()` with a preset (section 9) |
+
+Do not use characters:
+
+- behind body copy, forms, tables, code, docs pages or navigation;
+- on every card in a grid, or as a second ground on a page that has one;
+- as the only carrier of a state: the label, the live region or the HTML still says it;
+- for a loader with no real work behind it, or for decoration that never answers an event.
+
+Test: hide the canvas. If the interface loses no feedback and the field was not the page's one ground, remove it. A ground earns its place by answering the interface. On asciify.org the hero field pulses when the command is copied:
+
+```ts
+import { fieldBackground } from 'asciify-engine/kit';
+
+const bg = fieldBackground(hero, { preset: 'hero', clear: heroCopy });
+copyButton.addEventListener('click', () => bg.pulse(copyButton));
+```
+
+## 2. Ink: quiet by default, colour only for meaning
+
+Inks come from theme tokens, defined for both schemes. The kit re-reads them when `prefers-color-scheme` changes and when `class` or `data-theme` changes on `<html>` or `<body>`, so define the dark values under both selectors. These are the engine's own fallbacks and the site's graphite:
+
+```css
+:root {
+  --ascii-ink: #76746e;        /* grounds, rings, quiet strokes */
+  --ascii-ink-strong: #1d1d1b; /* a component that is the focus */
+  --ascii-success: #17844a; --ascii-warning: #9a6700; --ascii-error: #c93636;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) { --ascii-ink: #7a7872; --ascii-ink-strong: #d8d6cf; --ascii-success: #3ccf7e; --ascii-warning: #f5b83d; --ascii-error: #ff6b6b; }
+}
+:root[data-theme="dark"] { --ascii-ink: #7a7872; --ascii-ink-strong: #d8d6cf; --ascii-success: #3ccf7e; --ascii-warning: #f5b83d; --ascii-error: #ff6b6b; }
+```
+
+Rules:
+
+- **Default to graphite.** Leave `ink` unset: components pick `--ascii-ink` or `--ascii-ink-strong` and background presets use their graphite. On another brand, map these tokens to its muted text colour, never to its accent.
+- **Colour means something.** Green, amber and red are for outcomes only, and come from `--ascii-success`, `--ascii-warning` and `--ascii-error`. The site's phosphor marks live states only and is never a button or text.
+- **Palettes are deliberate.** `beam` `colorful`, `voiceOrb` `aurora` and `fieldBackground` `brand` are chosen palettes for one moment the user asked for, not a page default.
+- **Never a new colour.** No hex that is not a token, no black canvas on a light page, no white glow on a coloured image.
+
+```ts
+import { background, halftone, statusOrb, beam } from 'asciify-engine/kit';
+
+background(pricing, { preset: halftone, clear: pricingCopy, ink: '--ascii-ink' }); // the token, re-read per theme
+const orb = statusOrb(orbSlot); // strong ink at rest; outcomes read --ascii-success, --ascii-warning, --ascii-error
+beam(planCard, { palette: 'mono', mode: 'pulse' }); // the quiet beam; 'colorful' only when asked for
+orb.loading();
+```
+
+## 3. Text over a field: clear zone plus frosted veil
+
+Text never sits on raw characters, and never in a box. Two layers do the work:
+
+1. **The clear zone.** Pass the text block as `clear`; the field fades out around it (`fieldBackground` in a soft ellipse, the GPU background presets in a feathered rectangle 32px out, canvas presets in a soft ellipse).
+2. **The veil.** A frosted, radially masked wash of the ground behind the text, so characters blur and fade toward the words instead of stopping at an edge. This is asciify.org's CSS:
+
+```css
+.hero-copy { position: relative; isolation: isolate; }
+.hero-copy::before {
+  content: ""; position: absolute; z-index: -1; inset: -36px -64px; pointer-events: none;
+  background: color-mix(in oklab, var(--bg) 62%, transparent);
+  -webkit-backdrop-filter: blur(9px) saturate(1.1); backdrop-filter: blur(9px) saturate(1.1);
+  -webkit-mask-image: radial-gradient(closest-side, #000 52%, rgb(0 0 0 / .6) 74%, transparent);
+  mask-image: radial-gradient(closest-side, #000 52%, rgb(0 0 0 / .6) 74%, transparent);
+}
+/* A smaller block, such as a card's title and button: a tighter veil from the surface it sits on. */
+.card-copy::before { inset: -24px -40px; background: color-mix(in oklab, var(--surface-2) 58%, transparent); }
+```
+
+- No solid panels, cards or hard-edged scrims behind headline copy. Buttons keep their own opaque fill.
+- A header over a field: mask the field to about a quarter strength under the header strip, as the site does: `mask-image: linear-gradient(to bottom, rgb(0 0 0 / .26), rgb(0 0 0 / .26) 56px, #000 152px, #000 80%, transparent)`.
+- **Contrast.** Body and lede text 4.5:1, display text of 24px and up 3:1, measured against the busiest frame under the text, in both themes. Fix a failure with the clear zone, the veil, a lower `opacity` or larger cells. Never dim, recolour or shadow the text to fix it.
+
+## 4. Density and cell size by surface
+
+| Surface | Cell size | Characters | Site reference |
+| --- | --- | --- | --- |
+| Page hero ground | 10–12px, broad shapes | Sparse: `' .:+*#'` in the mono face | `fieldBackground` `hero` (10px), `drift` (11px), `halftone` (14px dot spacing) |
+| Section band or card stage | 7–10px | Fuller ramp for images (`' .:-=+*#%@'`), quiet ramp for grounds | images 7px, character fields 10px, halftone 9px |
+| Control: button, pill, tabs, code input, odometer | Leave it to the kit | The kit fits cells to the element's text | Use a monospaced label for `buttonLoading` |
+
+- One density per surface: a stage does not mix a 7px image and a 12px ground.
+- Nothing under 6px on a phone; the GPU grounds already enlarge their shapes under 760px.
+- Tune with `look: { cellSize }` on a component or `cellSize` on `background()`, and only after looking at it at 1x and 2x.
+
+```ts
+import { background, drift } from 'asciify-engine/kit';
+
+const band = background(featureBand, { preset: drift, cellSize: 12, clear: bandCopy }); // a touch quieter than the default 11
+band.update({ charset: ' .:+*#' }); // the hero's sparse ramp
+```
+
+## 5. Radii and containment
+
+The kit clips every field to its host's computed corner radii, so the shape must be on the host.
+
+- Put `border-radius` on the element you pass, from the project's tokens, never a literal. asciify.org: `--r-xs` 8px, `--r-inner` 18px, `--r-panel` 24px, `--r-dialog` 28px, and every control a pill (`--r-control: 999px`).
+- Nest radii: an inner frame inset by `p` takes `calc(var(--r-panel) - p)`, as the site's video frame does (`calc(var(--r-panel) - 8px)` inside an 8px padding).
+- Give `overflow: hidden` and a background to hosts the kit draws inside: `artPanel`, `imageGenerate`, `compare`, `accordion`, `dropzone`.
+- Some components draw past their host on purpose: `voiceOrb` 8%, `codeInput` 16px, `toastStack` 24px, `likeBurst` 40px (`outset`), `swipeDeck` 56px (`outset`). Their container must have that much room, or bound them:
+
+```ts
+import { likeBurst, swipeDeck } from 'asciify-engine/kit';
+
+likeBurst(likeButton, { limit: postBody, outset: 24 }); // nothing above the post body, sparks inside the card's padding
+swipeDeck(stack, { outset: 32 }); // the stage's own padding, so a fling thins out before its edge
+```
+
+Check: with the page zoomed to 200%, no character lands outside a rounded corner or past a container edge.
+
+## 6. Motion
+
+- **Interface: 280ms or less.** Anything a person waits on: tab indicator (`tabs` defaults to 280), panel open (`accordion` 280), tone change (`pill` 240), poster fade (280), view swap (`pageDissolve` 140 + 160).
+- **Decorative: 800ms or less.** One-shot flourishes: `disintegrate` 620, `dropzone` develop 720, the like burst. `decode` defaults to 900, so pass `duration: 800` or less.
+- **Ambient loops: slow.** Keep `speed` at or below the preset's own. Motion should be noticed on the second look, not the first.
+- **Easing.** CSS around the field uses the house ease-out, `--ease: cubic-bezier(.23, 1, .32, 1)`, with 140ms for control colour changes. The kit's own motion runs on `cubic-bezier(.16, 1, .3, 1)`. No linear or ease-in entries; a spring only where the material earns a settle (a like, a badge).
+- **Reduced motion.** The kit draws each state settled in one frame and each background as one still; poster fades become instant. Drop your own transitions too, and never hide a playing canvas with CSS instead.
+- **Off screen.** The kit pauses fields off screen and in hidden tabs. Call `pause()` on fields inside closed overlays. Give video and any field that is the content, not a texture, a visible pause control.
+
+```ts
+import { tabs, decode } from 'asciify-engine/kit';
+
+tabs(tablist, { duration: 280, panels: 'attribute' }); // interface
+decode(headline, { duration: 800, settle: 'text' }); // decorative, under the 800ms ceiling
+```
+
+```css
+:root { --ease: cubic-bezier(.23, 1, .32, 1); --fast: 140ms; }
+@media (prefers-reduced-motion: reduce) { .tab, .panel, .btn { transition: none; animation: none; } }
+```
+
+## 7. Performance
+
+- **About 12 fields per page.** At most 12 kit fields hold a WebGL context at once (`setFieldBudget` changes it). asciify.org's home page runs 12. Past that, share: one `pill()` call over a list draws every pill with one field.
+- **Lazy by default.** Fields mount within half a viewport and release beyond one. Use `lazy: false` only for the hero in the first viewport.
+- **Posters.** Give every field above the fold, and every field that matters without WebGL, a still per theme, and swap it on theme change with `update({ poster })` rather than remounting.
+- **Canvas presets cost CPU, not contexts.** Count them toward the page anyway; one animated ground per viewport.
+- **Import by name.** Presets are separate exports, so import only those you mount.
+- **Destroy on unmount.** In React, create the handle in an effect and return its `destroy`.
+
+```ts
+import { fieldBackground, setFieldBudget } from 'asciify-engine/kit';
+
+setFieldBudget(10); // a page with heavy media of its own
+const dark = matchMedia('(prefers-color-scheme: dark)');
+const still = (isDark: boolean) => `/stills/hero-${isDark ? 'dark' : 'light'}.webp`;
+const ground = fieldBackground(hero, { preset: 'hero', clear: heroCopy, lazy: false, poster: still(dark.matches) });
+dark.addEventListener('change', event => ground.update({ poster: still(event.matches) }));
+```
+
+## 8. Accessibility
+
+- **Canvases are decoration.** Kit fields are `aria-hidden` and ignore the pointer. Only the canvases that are the content take a `label`: `fieldBackground` `notFound`, `asciiVideo`, `artPanel`.
+- **Real text stays in the DOM.** `decode`, `wordmark` and `streamText` keep the actual words selectable and readable; `odometer` and `pill` counts add a hidden copy; `blockChart` adds a hidden table. Do not replace text with a field.
+- **Status is announced.** Pass a live region to `buttonLoading` (`announce`) and `thinking` (`label`), write `statusOrb` outcomes to one yourself, and give `pullRefresh` its `messages`. `toastStack` adds its own `role="status"` region.
+- **Keyboard and focus.** The kit wires keys for `tabs`, `commandPalette`, `slideToConfirm`, `compare`, `accordion`, `swipeDeck` and `codeInput`; keep them (`manage` stays true). Keep a Refresh button beside pull to refresh. A field never covers a focus ring: `beam` draws inside the border, so a 2px outline at 3px offset stays clear.
+
+```ts
+import { statusOrb, buttonLoading } from 'asciify-engine/kit';
+
+// <p id="publish-status" role="status" aria-live="polite"></p>
+const orb = statusOrb(orbSlot, { ring: true });
+const button = buttonLoading(publishButton, { announce: publishStatus });
+publishButton.addEventListener('click', async () => {
+  orb.loading(); button.start('Publishing');
+  await save().then(() => { orb.success(); button.succeed('Published'); }, () => { orb.error(); button.fail('Retry'); });
+});
+```
+
+## 9. Backgrounds
+
+`background(element, { preset })` draws any of the 26 presets from asciify.org/backgrounds under the element's content. Choose by surface:
+
+| Surface | Presets | Notes |
+| --- | --- | --- |
+| Product hero, pricing, docs landing, behind copy | `drift`, `halftone`, or `fieldBackground` `hero` | GPU grounds that clear around `clear`. `halftone` is the calmest; `fieldBackground` `hero` is asciify.org's own hero, with ripples and `pulse()`. |
+| A brand or name moment | `wordField` (id `field`), `fieldBackground` `brand` | Your word in the field; keep copy off its centre. |
+| Art-first hero with little copy | `fluid` | The original Asciify hero, 7px cells at 0.7 opacity. Not behind reading text. |
+| Quiet texture: section bands, footers, empty states, side panels | `caustics`, `contour`, `facet`, `etch`, `moire`, `weave`, `veil`, `dune`, `silk` | Canvas, no cursor, slow. The safest behind text after `halftone`. |
+| An interactive moment the visitor plays with | `wave`, `aurora`, `noise`, `stars`, `pulse`, `voidWell` | They answer the cursor. Keep them away from forms and body copy. |
+| A themed subject the page is about | `rain`, `grid`, `morph`, `fire`, `dna`, `terrain`, `circuit` | Loud. Use only when the subject matches (DNA for a biotech page), with low opacity and copy beside, not over. |
+
+Keep them calm:
+
+- `speed` at or below the preset's default; `cursor: false` near forms and copy.
+- On canvas presets behind text, `opacity` 0.5–0.8; GPU grounds already draw quietly.
+- Always `clear` the copy and add the veil from section 3; on the /backgrounds page the copy also sits on the side the field fades toward.
+- One background per page section, under one `isolation: isolate` host with its own background colour.
+- `setPreset()` cross-fades in place for a picker; do not mount a second background.
+
+```ts
+import { background, contour, caustics } from 'asciify-engine/kit';
+
+const section = background(features, { preset: contour, clear: featuresCopy, opacity: 0.6, cursor: false });
+themePicker.addEventListener('change', () => section.setPreset(caustics)); // keeps clear, opacity and cursor
+```
+
+```ts
+import { background, drift } from 'asciify-engine/kit';
+
+const bg = background(hero, { preset: drift, clear: heroCopy, poster: '/stills/drift-light.webp' });
+signUpButton.addEventListener('click', () => bg.field?.pulse({ element: signUpButton, strength: 1.2 })); // GPU presets expose the field
+```
+
+## 10. Checklist before you finish
+
+- [ ] Every field has a job from section 1; hiding it loses feedback, or it is the page's one ground.
+- [ ] Ink comes from tokens in both themes; colour appears only for outcomes or a requested palette.
+- [ ] Text over a field has `clear` plus the veil; 4.5:1 for body, 3:1 for display, at the busiest frame, light and dark.
+- [ ] Cell size matches the surface; nothing under 6px on a 390px-wide phone.
+- [ ] Every host carries its radius from tokens; nothing draws past a corner or container edge at 200% zoom.
+- [ ] Interface motion ≤ 280ms, decorative ≤ 800ms, on the house ease-out; reduced motion shows settled stills.
+- [ ] No more than about 12 fields per page; first-viewport fields have posters per theme; everything else is lazy.
+- [ ] Canvases are `aria-hidden` unless labelled content; real text is in the DOM; status reaches a live region.
+- [ ] Every handle is destroyed on unmount, and the page still works with WebGL off.

package/skills/asciify-engine/references/components.md

@@ -10,7 +10,7 @@ Every snippet uses `asciify-engine/kit`, one call per component. Start there by
 - falls back without WebGL2 to an inert handle that leaves your HTML working as it was;
 - cleans up on `destroy()`.
 
-Build them in the project's own framework, design tokens and lifecycle; read [design matching](design-matching.md) first. Free names in the snippets, such as `card`, `button` or `deployButton`, are the project's own DOM elements and functions. In React, create the handle in an effect and return its `destroy`:
+Before choosing one, read [applying Asciify](applying-asciify.md): when characters earn a place, ink from theme tokens, the clear zone and frosted veil for text, density, radii, motion limits, the field budget and accessibility. Build them in the project's own framework, design tokens and lifecycle. Free names in the snippets, such as `card`, `button` or `deployButton`, are the project's own DOM elements and functions. In React, create the handle in an effect and return its `destroy`:
 
 ```tsx
 useEffect(() => { const b = beam(ref.current!); return () => b.destroy(); }, []);

package/skills/asciify-engine/references/design-matching.md

@@ -33,14 +33,16 @@ Never introduce a new brand color, a black canvas on a light site, or a second a
 
 ## 3. Pick the tool
 
+For an interface component or a background, use `asciify-engine/kit` and follow [applying-asciify.md](applying-asciify.md); the rows below are for media looks and the lower-level APIs.
+
 | The user wants | Use | Notes |
 | --- | --- | --- |
 | A photo, video or GIF converted on their page, with optional hover | `asciify`, `asciifyVideo`, `asciifyGif` (+ `mountHover` from `/hover`) | Lightest path. Disable core hover and motion when `/hover` owns them. |
 | A full-bleed hero or brand field that must feel smooth under the cursor, their name or word as the characters, an Unseen-style look | `mountGlyphField` from `/field` | WebGL2 on a GPU, 120 fps class. Glyph ramps only. Keep a poster and a fallback. See [glyph-field.md](glyph-field.md). |
-| A calm background for a product page, docs, pricing or SaaS hero, in light or dark | `mountGlyphField` with `mark: 'dot'`, `scene: 'drift'` and `clear` around the copy | The halftone. Muted ink, transparent background, `pulse()` on real events. See [glyph-field.md](glyph-field.md#halftone-for-interfaces-412). |
+| A calm background for a product page, docs, pricing or SaaS hero, in light or dark | Kit `background(el, { preset: halftone, clear })` or `fieldBackground(el, { preset: 'hero', clear })` | Graphite ink, clear zone plus veil. See [applying-asciify.md](applying-asciify.md#9-backgrounds). Raw `mountGlyphField` with `mark: 'dot'` only for a look the kit lacks ([glyph-field.md](glyph-field.md#halftone-for-interfaces-412)). |
 | Art styles (halftone, dither, braille, print, mosaic, LED…), saved looks, backdrops, masks, effects, PNG/MP4/GIF export | `mountStudio` from `/studio` | Studio owns motion, hover and finish. Start from `studioLook(id)` when one of the 12 looks matches the mood. |
 | Several media and text layers in one artwork | `mountStudioProject` from `/studio` | One loop and budget for up to eight layers. See [layered-projects.md](layered-projects.md). |
-| An ambient animated background with no media (rain, stars, waves, aurora…) | A background template from asciify.org/backgrounds | Downloaded files, not npm exports. Or a `/field` generated scene (`flow`, `orb`) for a GPU field. |
+| An ambient animated background with no media (rain, stars, waves, aurora…) | Kit `background(el, { preset })` with one of the 26 presets | Import presets by name from `asciify-engine/kit`. See [applying-asciify.md](applying-asciify.md#9-backgrounds) for which suits which surface. |
 | A text banner or lettering | `asciifyText` / `renderTextToCanvas` | Plain text output works anywhere; canvas for color. |
 | Headline text visible through the art | Layered HTML, see [layered-hero.md](layered-hero.md) | Real text stays in the DOM. |
 
@@ -86,7 +88,7 @@ Autonomous motion that lasts longer than five seconds needs a visible pause cont
 
 ## 5. Derive concrete values from the tokens
 
-- **Ink.** One-ink looks use the accent token. Photo looks keep source color unless the brand is strictly monochrome.
+- **Ink.** Interface fields and grounds use a quiet graphite mapped to the muted text token, never the accent; colour is for outcomes only ([applying-asciify.md](applying-asciify.md#2-ink-quiet-by-default-colour-only-for-meaning)). A one-ink brand or media artwork the user asked for may use the accent. Photo looks keep source color unless the brand is strictly monochrome.
 - **Ground.** Use the page background token exactly, or a transparent canvas over it. On light themes draw dark ink on the light ground: core `invert: true` or `'auto'`, field `background: <page color>` with a dark `ink` and `invert: true`, studio dark `ink` with a light `backdrop.color`.
 - **Backdrop.** `backdrop` puts a blurred copy of the source under the characters. It enriches a photo but reads as a pale photographic wash on light subjects. Leave it at 0 when the user wants pure ASCII, and never use it behind text.
 - **Wake color.** Keep the field's default `highlight: 'auto'`, which brightens each character's own color. Only set a hex highlight when the brand asks for a second color; never default to white on a colored artwork.
@@ -134,11 +136,12 @@ const field = mountGlyphField(canvas, {
 
 For a quieter product page, add `hover: 'lantern'` (a soft light, no distortion) and keep `drift: 0` so the photo stays still until touched. Use `/studio` instead when they also want halftone, dither or an export button.
 
-**"A subtle animated background behind our pricing section."** Download a template (for example Aurora or Silk) from asciify.org/backgrounds and mount it with the page's colors, low opacity and the cursor off:
+**"A subtle animated background behind our pricing section."** Use a quiet kit preset with the page's muted ink, the cursor off and the copy kept clear:
 
-```js
-import { asciiBackground } from './aurora.js';
-const { destroy } = asciiBackground('#pricing', { colorScheme: 'auto', color: tokens.textMuted, opacity: 0.2, fontSize: 12, speed: 0.6 });
+```ts
+import { background, silk } from 'asciify-engine/kit';
+const bg = background(pricing, { preset: silk, ink: '--ascii-ink', opacity: 0.6, cursor: false, clear: pricingCopy });
+// On unmount: bg.destroy();
 ```
 
 **"Retro terminal look for our launch video."**

package/skills/asciify-engine/references/glyph-field.md

@@ -1,5 +1,7 @@
 # GPU glyph fields (4.11)
 
+For interface components and backgrounds, use `asciify-engine/kit` first ([applying-asciify.md](applying-asciify.md), [kit.md](kit.md)); it is built on this field and adds theme ink, posters, lazy mounting, the context budget and fallbacks. Mount the field directly only for a look the kit has no option for.
+
 `asciify-engine/field` draws an image, a video or generated motion as characters entirely on the GPU, with a fluid wake under the cursor. Use it for full-bleed heroes, section backgrounds and brand fields where the frame must stay smooth while people move over it. It is a separate, optional entry; importing the root, `/core`, `/hover` or `/studio` never loads it.
 
 Use `/studio` instead when you need the 24 render styles, dither, print styles, masks, effects or exports. The field draws glyph ramps only: characters, braille, block shading, dots, or your own letters.
@@ -38,6 +40,7 @@ Size the canvas with CSS (for example `position:absolute; inset:0; width:100%; h
 | `clear` | `false` | Keeps the field quiet around content so text stays readable: an element, `{ element, padding, feather, shape }` (followed through layout changes), or a zone in field fractions. (4.12) |
 | `charset` | `' .,:-=+*#%@'` | Ordered from empty to dense. Graphemes, so emoji, braille and block shading each take one cell. Up to 256. |
 | `cellSize`, `cellAspect` | `12`, `1` | Cell height in CSS px; width ÷ height. Monospaced ramps look best near `0.6`. Cells are whole device pixels, and glyphs are sampled texel for texel. |
+| `cellFit` | `'pixel'` | `'pixel'` snaps each cell to whole device pixels, so a fractional `cellSize` rounds and rows drift from a renderer that does not. `'fill'` fits a whole number of cells of at least `cellSize` × `cellAspect` and stretches them to fill the canvas exactly, as the core renderer lays out a frame; each glyph stays texel for texel, centred in its cell. |
 | `font`, `fontWeight`, `glyphScale` | monospace, `500`, `0.8` | Any loaded CSS font. The atlas is redrawn when the font finishes loading. |
 | `color` | `'ink'` | `'ink'` uses `ink`; `'source'` takes each cell's hue from the media. |
 | `ink`, `highlight` | `#f3ba32`, `'auto'` | Hex colors. The wake lifts characters toward `highlight`; `'auto'` brightens each character's own color so the wake keeps the artwork's hue. |