asciify-engine 4.12.0 → 4.13.0

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

@@ -1,460 +1,541 @@
 # Asciify components
 
-Ready-made ASCII components for product interfaces. Each one has the prompt a person gives you and the reference code you should arrive at. Every component runs live at https://asciify.org/components, where an agent cursor demonstrates its interaction, so the person can see the result before asking for it.
+Ready-made ASCII components for product interfaces. Each one has the prompt a person gives you and the code you should arrive at. Every component runs live at https://asciify.org/components, where an agent cursor demonstrates its interaction, so the person can see the result before asking for it.
 
-Build them in the project's own framework, design tokens and lifecycle. Read [design matching](design-matching.md) first. The shared rules:
+Every snippet uses `asciify-engine/kit`, one call per component. Start there by default: [the kit reference](kit.md) lists every option and method. Each kit function:
 
-- Keep text and controls in HTML. The field is a decorative canvas behind or inside them, with `aria-hidden` on the canvas.
-- Give the field a transparent background and an ink from the project's tokens, for each theme.
-- Check `isGlyphFieldSupported()`, and keep the static design (or a poster image of the field) as the fallback.
-- Honor reduced motion. Fields draw one still frame and skip pulses by default.
-- Call `destroy()` on unmount. Mount fields that start off screen lazily, when they come near the viewport.
-- GPU fields need asciify-engine 4.12 or later for `mark`, `clear` and `pulse()`.
+- mounts its own `aria-hidden` field over or inside your element, following its size and border radius, and keeps your text and controls in HTML;
+- inks the field from your theme (`ink` takes a colour or a custom property such as `'--brand'`) and follows light and dark;
+- honours `prefers-reduced-motion` by drawing each state settled, and pauses off screen;
+- falls back without WebGL2 to an inert handle that leaves your HTML working as it was;
+- cleans up on `destroy()`.
 
-## The shared helper
+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`:
 
-Every component below uses this helper. It mounts a field that takes its ink from a CSS custom property, follows light and dark, and cleans up after itself. Put it in the project once.
+```tsx
+useEffect(() => { const b = beam(ref.current!); return () => b.destroy(); }, []);
+```
+
+For a look the kit doesn't offer, drop down to the raw field: see [Advanced: raw field](#advanced-raw-field) at the end of this file.
+
+## voice-field: Voice orb
+Category: AI
+
+Prompt:
+“Add a voice orb to [our assistant]: an Asciify sphere of characters that swells with loudness through Listening, Thinking and Done, in Mono, Aurora or Brand, its gradient shifting as it gets louder. Ask for the microphone only on click.”
 
 ```ts
-import { isGlyphFieldSupported, mountGlyphField, type GlyphField, type GlyphFieldOptions } from 'asciify-engine/field';
+import { voiceOrb } from 'asciify-engine/kit';
 
-/** A field inked from a CSS variable that follows the theme. Returns null when the GPU field isn't available. */
-export function asciiField(canvas: HTMLCanvasElement, options: GlyphFieldOptions = {}, inkVar = '--ascii-ink') {
-  if (!isGlyphFieldSupported()) return null;
-  const ink = () => getComputedStyle(canvas).getPropertyValue(inkVar).trim() || '#8f8d86';
-  const field: GlyphField = mountGlyphField(canvas, { color: 'ink', background: 'transparent', ...options, ink: ink() });
-  const scheme = matchMedia('(prefers-color-scheme: dark)');
-  const retint = () => field.update({ ink: ink() });
-  scheme.addEventListener('change', retint);
-  return { field, destroy() { scheme.removeEventListener('change', retint); field.destroy(); } };
-}
+const orb = voiceOrb(orbButton, { palette: 'aurora' }); // or 'mono', 'brand', or your own hex stops
+tintPicker.onchange = () => orb.update({ palette: tintPicker.value as 'mono' | 'aurora' | 'brand' });
+orbButton.onclick = async () => { if (!(await orb.mic())) note.textContent = 'Microphone unavailable'; }; // asks only now
+recognizer.onend = () => orb.think();
+reply.then(() => orb.done());
 ```
 
-```css
-:root { --ascii-ink: #76746e; --ascii-ink-strong: #1d1d1b; }
-@media (prefers-color-scheme: dark) { :root { --ascii-ink: #7a7872; --ascii-ink-strong: #d8d6cf; } }
+## command-palette: Command palette
+Category: AI
+
+Prompt:
+“Make a ⌘K command palette for [our app] with Asciify: it opens by condensing out of characters at the trigger, filters as you type, and a glyph column glides beside the selected row. Enter runs the action with a pulse.”
+
+```ts
+import { commandPalette } from 'asciify-engine/kit';
+
+// ⌘K or the trigger opens it; arrows, Enter and Escape are wired; rows are [role="option"] with an id
+commandPalette(palettePanel, { trigger: paletteTrigger, onRun: (i, row) => commands[row.dataset.id!].run() });
+searchInput.oninput = () => renderRows(searchInput.value); // the kit re-selects the first row
 ```
 
-In React, wrap it once and reuse it:
+## button-loading: Button loading
+Category: Components
 
-```tsx
-import { useEffect, useRef } from 'react';
-import type { GlyphField, GlyphFieldOptions } from 'asciify-engine/field';
+Prompt:
+“Make [our Deploy button] show loading with Asciify: while the request runs, a wave cycles each letter of ‘Deploying’ through .:-=+*#%@, then resolves to ‘Deployed’ with a check, or ‘Retry’ with a short shake. Its width never changes.”
 
-export function AsciiField({ options, onField, className }: { options: GlyphFieldOptions; onField?: (field: GlyphField | null) => void; className?: string }) {
-  const canvas = useRef<HTMLCanvasElement>(null);
-  useEffect(() => {
-    const mounted = canvas.current ? asciiField(canvas.current, options) : null;
-    onField?.(mounted?.field ?? null);
-    return () => { onField?.(null); mounted?.destroy(); };
-  }, []); // mount once; call field.update() for later changes
-  return <canvas ref={canvas} className={className} aria-hidden="true" />;
-}
+```ts
+import { buttonLoading } from 'asciify-engine/kit';
+
+const b = buttonLoading(deployButton, { announce: statusLine }); // the width never changes
+deployButton.onclick = async () => {
+  b.start('Deploying');
+  await deploy().then(() => b.succeed('Deployed'), () => b.fail('Retry')); // a check, or a short shake
+};
 ```
 
-## image-card: ASCII image card
+## ascii-pill: Badges and pills
 Category: Components
 
 Prompt:
-“Make a card whose image is drawn in characters with Asciify. Use [image]. Characters trail behind the cursor, the title, details and a save button stay as HTML under the image, and the ink follows our light and dark theme.”
+“Make [our status badges] Asciify pills: tinted pills whose live state is a three-character indicator that breathes, a New pill with a gradient glyph sheen on hover, and a count that rolls through glyphs. Clip every character inside its pill.”
 
 ```ts
-const image = asciiField(canvas, {
-  source: '/images/statue.jpg', fit: 'cover', focus: { x: 0.5, y: 0.35 },
-  charset: ' .:-=+*#%@', cellSize: 6, contrast: 1.25,
-  hover: 'trail', label: 'A marble statue drawn in characters',
-}, '--ascii-ink-strong');
+import { pill } from 'asciify-engine/kit';
+
+// <span class="pill" data-tone="green" data-live><span data-dot></span>Live</span>, data-tone="new", data-count
+const pills = pill(document.querySelectorAll<HTMLElement>('.pill'));
+statusPill.dataset.tone = 'amber';
+pills.refresh(); // tone changes ease over 240ms
+pills.count(14); // only the changed digits roll
 ```
 
-## hero-background: Hero background
-Category: Backgrounds
+## ascii-tabs: Character tabs
+Category: Components
 
 Prompt:
-“Put a calm ASCII background behind our hero with Asciify. Characters drift slowly, clear around the headline and buttons so they stay readable, and follow our light and dark theme.”
+“Make [our segmented tabs] Asciify tabs: the active indicator is a pill of characters that streams across as a glyph trail and condenses under the new tab within 280ms. Panels crossfade; arrow keys, Home and End switch tabs.”
 
 ```ts
-const hero = asciiField(canvas, {
-  mark: 'glyph', scene: 'drift', charset: ' .:+*#', cellSize: 12,
-  clear: { element: heroText, padding: 24, feather: 0.32, shape: 'ellipse' },
-  hover: 'trail',
-});
+import { tabs } from 'asciify-engine/kit';
+
+// role="tab" buttons with aria-controls; panels crossfade on [data-active] in your CSS
+const t = tabs(tablist, { duration: 280, panels: 'attribute' });
+t.select(2);
 ```
 
-## cli-banner: CLI banner
-Category: Text
+## slide-to-confirm: Slide to confirm
+Category: Components
 
 Prompt:
-“Greet people in ASCII when our CLI starts, using asciifyText from Asciify with [word].”
+“Add a slide to confirm to [our checkout]: ‘Slide to pay [$48]’. Asciify characters fill behind the thumb, drain when it springs back, then condense into a green check in a ring as the label becomes ‘Paid · [$48.00]’.”
 
 ```ts
-import { asciifyText } from 'asciify-engine';
+import { slideToConfirm } from 'asciify-engine/kit';
 
-console.log(asciifyText('Hey', { char: '#' }));
+// track: a [role="slider"] thumb, [data-label] "Slide to pay $48", and "Paid · $48.00" shown on [data-confirmed]
+const pay = slideToConfirm(payTrack, { mark: doneIcon, onConfirm: () => void charge().catch(() => pay.reset()) });
 ```
 
-## cursor-field: Cursor field
-Category: Backgrounds
+## like-burst: Like burst
+Category: Components
 
 Prompt:
-“Add a halftone dot field to [section] with Asciify that drifts, clears around the content, and answers the cursor with [trail, fluid or lantern].”
+“Make [our Like button] burst in Asciify characters: on press a heart pops to about 1.6× the icon with a few glyph sparks and settles into the icon within 600ms while the count rolls. Unlike crumbles; rest is empty.”
 
 ```ts
-const dots = asciiField(canvas, {
-  mark: 'dot', scene: 'drift', dotScale: 0.72, cellSize: 8,
-  clear: { element: content, padding: 40, shape: 'rect' },
-  hover: 'fluid',
-});
+import { likeBurst, odometer } from 'asciify-engine/kit';
+
+const likes = odometer(likeCount);
+likeBurst(likeButton, { kind: 'heart', limit: postBody, onChange: on => likes.set(likes.value + (on ? 1 : -1)) });
 ```
 
-## wordmark: Brand wordmark
+## loading-states: Status orb
+Category: Components
+
+Prompt:
+“Give [our Publish button] an Asciify status orb: characters orbit while it runs, then the ring closes around a check, ‘!’ or X, tinting characters and label green, amber or red. Offer bare-mark and neutral options. Keep the label live.”
+
+```ts
+import { statusOrb } from 'asciify-engine/kit';
+
+const orb = statusOrb(orbSlot, { ring: true, colourByState: true }); // ring: false for the bare mark, colourByState: false for neutral
+const labels = { success: 'Published', warning: 'Published with warnings. Review?', error: 'Couldn’t publish. Retry?' };
+publishButton.onclick = async () => {
+  orb.loading(); statusLine.textContent = 'Publishing…';
+  await save().then(r => (r.warnings ? orb.warning() : orb.success()), () => orb.error());
+  statusLine.textContent = labels[orb.state as keyof typeof labels];
+};
+```
+
+## text-decode: Decode headline
 Category: Text
 
 Prompt:
-“Draw our name, [name], in moving characters with Asciify for [the footer or a hero]. The word stays crisp, characters trail under the cursor, and the real name stays in HTML for screen readers.”
+“Make [our hero headline] condense out of a drifting Asciify field: a soft cloud of characters drifts, then the words resolve left to right through a flickering band, with nothing left behind. Keep the real headline in the HTML.”
 
 ```ts
-const word = document.createElement('canvas');
-word.width = 1800; word.height = 480;
-const ctx = word.getContext('2d')!;
-ctx.fillStyle = '#000'; ctx.fillRect(0, 0, word.width, word.height);
-ctx.fillStyle = '#fff'; ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
-ctx.font = '600 400px Georgia, serif';
-ctx.fillText('asciify', word.width / 2, word.height / 2 + 20);
+import { decode } from 'asciify-engine/kit';
 
-const wordmark = asciiField(canvas, {
-  source: word, fit: 'contain', charset: ' .:-=+*#%@', cellSize: 9,
-  hover: 'trail', label: 'asciify, drawn in characters',
-}, '--ascii-ink-strong');
+const d = decode(headline, { duration: 900, settle: 'text' }); // plays when it comes into view; the real text stays in the DOM
+replayButton.onclick = () => d.replay();
 ```
 
-## video: Video in characters
-Category: Media
+## ascii-chart: Block chart
+Category: Components
 
 Prompt:
-“Play [video] in characters with Asciify as [a section background or a card]. Muted, looping, paused off screen, with a play and pause control, and the poster for reduced motion.”
+“Build [our visitors analytics card] with bars drawn in Asciify characters: they grow in left to right, grow again on a 7d/30d toggle, and brighten under a hover readout.”
 
 ```ts
-const video = asciiField(canvas, {
-  source: '/media/magnolia.mp4', fit: 'cover', charset: ' .:-=+*#%@', cellSize: 7,
-  contrast: 1.2, hover: 'trail', label: 'A magnolia opening, drawn in characters',
-}, '--ascii-ink-strong');
+import { blockChart } from 'asciify-engine/kit';
 
-let paused = false;
-playButton.addEventListener('click', () => {
-  paused = !paused;
-  if (paused) video?.field.pause(); else video?.field.play();
+const chart = blockChart(plot, {
+  values: visits['7d'], labels: days['7d'],
+  onHover: (i, v, day) => { readout.textContent = i === null ? '' : `${day} · ${v!.toLocaleString()}`; },
 });
+rangeToggle.onchange = () => chart.set(visits[rangeToggle.value], days[rangeToggle.value]);
 ```
 
-## not-found: 404 page
-Category: Pages
+## route-transition: Page transition
+Category: Transitions
 
 Prompt:
-“Make our 404 page with Asciify: a calm field of characters that clears around the message, trails under the cursor, and pulses when someone presses Go home.”
+“When someone switches [tabs] in [our app], break the view into its own Asciify characters from the clicked tab, swap it, and condense the next view out of characters in about 400ms. At rest, keep [its chart] in characters.”
 
 ```ts
-const lost = asciiField(canvas, {
-  mark: 'glyph', scene: 'drift', charset: ' .:+*#', cellSize: 12, hover: 'trail',
-  clear: { element: message, padding: 28, feather: 0.3, shape: 'ellipse' },
-});
+import { pageDissolve, blockChart } from 'asciify-engine/kit';
 
-homeLink.addEventListener('click', () => lost?.field.pulse({ element: homeLink }));
+const page = pageDissolve(view, { dissolve: 180, condense: 220 }); // about 400ms, from the clicked tab
+const chart = blockChart(chartSlot, { values: series.overview }); // at rest the chart stays in characters
+for (const tab of navTabs) tab.onclick = () => page.swap(() => { renderView(tab.dataset.page!); chart.set(series[tab.dataset.page!]); }, tab);
 ```
 
-## avatar: ASCII avatar
+## swipe-card: Swipe cards
 Category: Components
 
 Prompt:
-“Draw [person]'s avatar in characters with Asciify, inside our round avatar frame. Characters trail under the cursor, and the name, role and follow button stay as HTML.”
+“Make a swipeable card stack for [our stays] with Asciify: each [photo] drawn in characters. A swiped card dissolves into characters along the swipe while the next resolves; Pass and Save buttons and arrow keys do the same.”
 
 ```ts
-const avatar = asciiField(canvas, {
-  source: '/images/portrait.jpg', fit: 'cover',
-  charset: ' .:-=+*#%@', cellSize: 5, contrast: 1.1,
-  hover: 'trail', label: 'Portrait of Elias Varga',
-}, '--ascii-ink-strong');
+import { swipeDeck } from 'asciify-engine/kit';
+
+// stack: [data-card] children, each with an <img>; put captions outside the deck. Arrow keys are wired.
+const deck = swipeDeck(stack, { threshold: 0.4, onSwipe: (dir, i) => (dir > 0 ? saveStay(stays[i]) : passStay(stays[i])) });
+saveButton.onclick = () => deck.next(1);
+passButton.onclick = () => deck.next(-1);
 ```
 
-## empty-state: Empty state
+## otp-input: Verification code
 Category: Components
 
 Prompt:
-“Give our empty state a quiet ASCII field with Asciify. Keep the icon, message and primary action readable, and send a pulse through the field from the button when it is pressed.”
+“Make a 6-digit verification code input with Asciify: each digit resolves out of characters as it is typed, a wrong code shakes and crumbles back, and the right one condenses into a check. Support paste and one-time-code autofill.”
 
 ```ts
-const empty = asciiField(canvas, {
-  scene: 'flow', charset: ' .:-=+*#', cellSize: 11, hover: 'none',
-  clear: { element: emptyMessage, padding: 24, shape: 'rect' },
-});
+import { codeInput } from 'asciify-engine/kit';
 
-primaryButton.addEventListener('click', () => empty?.field.pulse({ element: primaryButton }));
+// paste and autocomplete="one-time-code" are built in; a wrong code shakes, a right one draws a check
+const code = codeInput(codeRow, { length: 6, onComplete: async c => code.verify(await api.checkCode(c)) });
 ```
 
-## loading: Loading state
+## toast-stack: Toast stack
 Category: Components
 
 Prompt:
-“Show [upload or sync] progress with Asciify: a small character field above the file name and progress bar that sends a soft pulse each second while it runs, and stops when it settles.”
+“Make [our toasts] with Asciify: each one gathers out of characters and stacks with depth, hover fans the stack out, and dismissing breaks a toast back into drifting glyphs. Include Undo.”
 
 ```ts
-const loading = asciiField(canvas, { mark: 'glyph', scene: 'drift', charset: ' .:+*#', cellSize: 9, hover: 'none' });
-const beat = setInterval(() => loading?.field.pulse({ strength: 0.8 }), 1000);
-request.finally(() => clearInterval(beat));
+import { toastStack } from 'asciify-engine/kit';
+
+const toasts = toastStack(toastCorner, { max: 3, duration: 6000 }); // a positioned box, such as fixed bottom-right, 360px wide
+toasts.push({ title: 'Thread archived', body: 'Q3 planning · Ana', action: { label: 'Undo', onClick: restoreThread } });
+clearButton.onclick = () => toasts.clear(); // each toast breaks back into drifting glyphs
 ```
 
-## copy-pulse: Copy feedback
+## skeleton-loader: Skeleton loader
 Category: Components
 
 Prompt:
-“When someone copies [the coupon code], answer with Asciify: a pulse travels through a halftone field from the copy button.”
+“Make a skeleton loader for [our post card] with Asciify: the placeholder blocks are drawn in characters with a shimmer sweeping across, then each block resolves into its real content and the image develops into the photo.”
 
 ```ts
-const ground = asciiField(canvas, { mark: 'dot', scene: 'drift', cellSize: 7, dotScale: 0.8, hover: 'none' });
+import { skeleton } from 'asciify-engine/kit';
 
-copyButton.addEventListener('click', async () => {
-  await navigator.clipboard.writeText(code);
-  ground?.field.pulse({ element: copyButton });
-});
+// blocks: [data-block="text" | "photo" | "avatar"] inside the card
+const s = skeleton(postCard, { shimmer: 1250, stagger: 60 });
+renderPost(await fetchPost());
+await s.resolve(); // text wipes in, the photo develops in characters
+reloadButton.onclick = async () => { s.reset(); renderPost(await fetchPost()); await s.resolve(); };
 ```
 
-## brand-field: Brand color field
-Category: Backgrounds
+## thinking: Thinking state
+Category: AI
 
 Prompt:
-“Make an ASCII field in our brand color with Asciify, drifting slower than the default, for [section].”
+“Show [our assistant]'s thinking state with Asciify: dot lines shimmer where the answer will appear under a Thinking… label, then the answer streams in word by word and the dots settle into a dotted rule beneath it.”
 
 ```ts
-const brand = asciiField(canvas, {
-  mark: 'glyph', scene: 'drift', charset: ' .:+*#', cellSize: 10,
-  speed: 0.5, hover: 'none',
-}, '--brand');
+import { thinking } from 'asciify-engine/kit';
+
+const reply = thinking(answer, { label: statusLabel, lines: 3 }); // "Thinking…", then "Thought for 2s"
+await reply.stream(await ask(question)); // or an async iterable of chunks
+regenerate.onclick = async () => { reply.think(); await reply.stream(await ask(question)); };
 ```
 
-## coming-soon: Coming soon page
-Category: Pages
+## stream-text: Streamed reply
+Category: AI
 
 Prompt:
-“Make a coming-soon page for [product] with Asciify: our mark and name, one headline, and an email field with a Join waitlist button. A drifting field of characters clears around the form, and pulses from the button when someone joins.”
+“Stream [our assistant]’s reply with an Asciify write head: an aria-hidden field over the text draws the caret and each token’s unresolved characters as flickering glyphs that settle into letters. Show reasoning lines, Stop and Regenerate.”
 
 ```ts
-const waitlist = asciiField(canvas, {
-  mark: 'glyph', scene: 'drift', charset: ' .:+*#', cellSize: 10, hover: 'trail',
-  clear: { element: form, padding: 14, feather: 0.24, shape: 'ellipse' },
-});
+import { streamText } from 'asciify-engine/kit';
+
+const out = streamText(answerText, { caret: true, settle: 60, stagger: 18, reasoningLines: 2 });
+async function run() {
+  out.reset();
+  for await (const part of llm.stream(question)) {
+    if (out.state === 'stopped') break;
+    if (part.reasoning) out.reasoning(part.reasoning); else if (part.text) out.write(part.text); // the reasoning tail collapses on done()
+  }
+  await out.done();
+}
+stopButton.onclick = () => out.stop();
+regenerate.onclick = () => void run();
+void run();
+```
 
-form.addEventListener('submit', event => {
-  event.preventDefault();
-  waitlist?.field.pulse({ element: joinButton });
-  form.dataset.state = 'joined';
+## image-generation: Image generation
+Category: AI
+
+Prompt:
+“While [our image API] generates [prompt], keep an Asciify field drifting with an elapsed clock, develop each streamed preview into it a step sharper, then the final image, and crossfade to the photo. Failures offer Retry; Regenerate dissolves back first.”
+
+```ts
+import { imageGenerate } from 'asciify-engine/kit';
+
+// imageStream(prompt) wraps your provider as an async iterable of { preview?, final? }, each a Blob or URL
+const gen = imageGenerate(imageFrame, { elapsed: clock, onState: s => { generateButton.textContent = s === 'failed' ? 'Retry' : 'Regenerate'; } });
+generateButton.onclick = () => void gen.run(() => imageStream(promptInput.value)); // a finished image dissolves back first
+```
+
+## ascii-compare: Before and after
+Category: Media
+
+Prompt:
+“Add a before and after slider to [our gallery]: [photo] on one side, the same photo drawn in its own colors in Asciify characters on the other. Drag the handle, or use the arrow keys in 5% steps.”
+
+```ts
+import { compare } from 'asciify-engine/kit';
+
+// compareFrame: a dark 3:2 box; drag, or arrow keys in 5% steps on the handle
+const c = compare(compareFrame, { image: '/images/kingfisher.jpg', position: 50, label: 'Photo and characters' });
+resetButton.onclick = () => c.set(50, true);
+```
+
+## image-accordion: Image accordion
+Category: Media
+
+Prompt:
+“Build an image accordion for [our prints]: [five photos] as panels drawn in Asciify characters. The hovered or focused panel widens and its characters give way to the full photo in 280ms, with a caption.”
+
+```ts
+import { accordion } from 'asciify-engine/kit';
+
+// give the strip a height; panels open on hover, press or focus
+accordion(printStrip, {
+  images: [{ src: '/prints/stairwell.webp', title: 'Stairwell', meta: 'Silver print · $120' }, '/prints/shell.webp', '/prints/fern.webp', '/prints/dune.webp', '/prints/pier.webp'],
+  duration: 280,
 });
 ```
 
+## ascii-dropzone: Image dropzone
+Category: Media
+
+Prompt:
+“Make an image dropzone with Asciify: a quiet ring of characters frames the drop area and breathes on drag-over. A dropped image develops in characters, with Replace and Download PNG.”
+
+```ts
+import { dropzone } from 'asciify-engine/kit';
+
+// buttons inside with data-dropzone="pick" (Replace) and "download" (Download PNG) are wired for you
+const zone = dropzone(dropArea, { onImage: ({ file }) => { if (file) void upload(file); }, onError: message => showError(message) });
+sampleButton.onclick = () => void zone.setImage('/images/sample.webp');
+```
+
+## ascii-disintegrate: Delete into characters
+Category: Transitions
+
+Prompt:
+“When someone deletes a [file or notification] row in [our list], turn it into Asciify characters that thin out and drift up in about 620ms while the rows below close the gap in 260ms. Show an Undo toast.”
+
+```ts
+import { disintegrate, toastStack } from 'asciify-engine/kit';
+
+const toasts = toastStack(toastCorner);
+async function removeRow(row: HTMLElement, id: string) {
+  toasts.push({ title: 'Moved to trash', action: { label: 'Undo', onClick: () => restoreItem(id) } });
+  await disintegrate(row, { duration: 620 }); // the rows below close the gap
+  deleteItem(id);
+}
+```
+
+## pull-refresh: Pull to refresh
+Category: Components
+
+Prompt:
+“Add pull to refresh to [our feed]: pulling reveals an Asciify character orb that densifies with distance. Past the threshold it spins while refreshing, condenses into a check, and new [posts] resolve in from characters. Include a Refresh button.”
+
+```ts
+import { pullRefresh } from 'asciify-engine/kit';
+
+// feedScreen: overflow auto, content in its first child; the ring spins until onRefresh resolves, then draws a check
+// rows marked data-new resolve in from characters as the content springs back
+const pull = pullRefresh(feedScreen, { threshold: 88, reveal: '[data-new]', onRefresh: () => loadNewPosts() });
+refreshButton.onclick = () => void pull.refresh();
+```
+
+## border-beam: Border beam
+Category: Components
+
+Prompt:
+“Give [our card] an Asciify border beam: rainbow halftone dots inside its rounded border. Rotate or pulse; on deploy, a progress ring that flashes then fades green on success, or cracks red on error. Static under reduced motion.”
+
+```ts
+import { beam } from 'asciify-engine/kit';
+
+const b = beam(card, { palette: 'colorful', mode: 'progress', grain: 'dots' }); // or mode 'rotate' or 'pulse'
+deployButton.onclick = async () => {
+  b.progress(0);
+  await deploy(p => b.progress(p)).then(() => b.success(), () => b.error()); // flash then green, or cracks red
+};
+```
+
+## glyph-odometer: Glyph odometer
+Category: Text
+
+Prompt:
+“Show [our monthly revenue figure] as normal text, an Asciify odometer: on [Refresh] only changed digits hand over to the field, roll through glyphs leftmost first in under 600ms, and land back on the crisp digit. Keep an aria-live value.”
+
+```ts
+import { odometer } from 'asciify-engine/kit';
+
+const mrr = odometer(revenueFigure, { value: 48290, format: n => `$${n.toLocaleString('en-US')}` }); // adds an aria-live copy
+refreshButton.onclick = async () => mrr.set(await fetchMrr());
+```
+
 ## sign-in: Sign-in page
 Category: Pages
 
 Prompt:
-“Make a split sign-in page with Asciify: [image] in characters on the left, trailing under the cursor, and an email field, Continue and a quiet Continue with GitHub on the right. Continue shows a loading state and pulses the art.”
+“Make a split sign-in page with Asciify: [image] in characters on the left that trail under the cursor, and an email field, Continue and Continue with GitHub on the right. Continue pulses the art while the link sends.”
 
 ```ts
-const art = asciiField(artCanvas, {
-  source: '/images/wing.jpg', fit: 'cover', focus: { x: 0.5, y: 0.4 },
-  charset: ' .:-=+*#%@', cellSize: 6, contrast: 1.3,
-  hover: 'trail', label: 'A carved wing drawn in characters',
-}, '--ascii-ink-strong');
+import { artPanel } from 'asciify-engine/kit';
 
-signInForm.addEventListener('submit', event => {
+const art = artPanel(artSide, { image: '/images/wing.jpg', clear: brandMark, focus: { x: 0.5, y: 0.4 } });
+signInForm.onsubmit = async event => {
   event.preventDefault();
-  continueButton.setAttribute('aria-busy', 'true');
-  art?.field.pulse({ element: continueButton });
-});
+  art.pulse(continueButton, 1.8);
+  art.shimmer(true);
+  await sendLink(emailInput.value).finally(() => art.shimmer(false));
+};
+```
+
+```css
+.sign-in { display: grid; grid-template-columns: 41% 1fr; padding: 14px; }
+.sign-in-art { position: relative; border-radius: 18px; overflow: hidden; background: var(--surface); }
 ```
 
 ## pricing: Pricing highlight
 Category: Pages
 
 Prompt:
-“Make a two-plan pricing section with a monthly and yearly toggle, using Asciify. The recommended plan, [plan], gets a halftone field that lights up under the cursor and pulses from its button.”
+“Make a two-plan pricing section with Asciify: the recommended plan, [plan], has a soft halftone light that sweeps when the period toggles, shows the yearly saving in dots, and pulses from its button.”
 
 ```ts
-const featured = asciiField(canvas, {
-  mark: 'dot', scene: 'drift', cellSize: 7, dotScale: 0.86, speed: 0.7,
-  interactionTarget: featuredCard, hover: 'lantern',
-  lantern: { radius: 0.3, strength: 0.75 },
-});
+import { pricingGlow } from 'asciify-engine/kit';
 
-trialButton.addEventListener('click', () => featured?.field.pulse({ element: trialButton }));
+const glow = pricingGlow(featuredCard, { price: '.price' });
+billingToggle.onchange = () => void glow.saving(billingToggle.value === 'yearly' ? '−25%' : null); // sweeps old out, new in
+trialButton.onclick = () => glow.pulse(trialButton);
 ```
 
-## text-decode: Decode headline
-Category: Text
+## not-found: 404 page
+Category: Pages
 
 Prompt:
-“Make [our hero headline] decode into place through ASCII characters when it scrolls into view and on hover, left to right in about 900ms, without moving the layout. Screen readers get the real words, and reduced motion shows them at once.”
-
-```ts
-const words = headline.textContent ?? '', ramp = '.:-=+*#%@abcdefghijklmnopqrstuvwxyz', cells = [...words].map(ch => Object.assign(document.createElement('span'), { textContent: ch }));
-const layer = Object.assign(document.createElement('span'), { ariaHidden: 'true', style: 'position:absolute;inset:0;pointer-events:none;color:var(--ink-3)' });
-headline.setAttribute('aria-label', words);
-headline.replaceChildren(layer, ...cells); // the headline is position: relative
-
-function decode(duration = 900, hold = 380) {
-  if (matchMedia('(prefers-reduced-motion: reduce)').matches || layer.childElementCount) return;
-  const stagger = (duration - hold) / Math.max(1, cells.length - 1), start = performance.now();
-  const glyphs = cells.map(({ offsetLeft: x, offsetTop: y, offsetWidth: w }) => layer.appendChild(Object.assign(document.createElement('span'), { style: `position:absolute;left:${x}px;top:${y}px;width:${w}px;display:flex;justify-content:center;line-height:normal` })));
-  requestAnimationFrame(function frame(now) {
-    cells.forEach((cell, i) => {
-      const t = (now - start - i * stagger) / hold, busy = t >= 0 && t < 1 && words[i] !== ' ';
-      cell.style.color = busy ? 'transparent' : '';
-      if (!busy || Math.random() < 0.4) glyphs[i].textContent = busy ? ramp[Math.floor(Math.random() * (t < 0.56 ? 9 : ramp.length))] : '';
-    });
-    if (now - start < duration) requestAnimationFrame(frame); else layer.replaceChildren();
-  });
-}
-new IntersectionObserver(([entry]) => { if (entry.isIntersecting) decode(); }, { threshold: 0.5 }).observe(headline);
-headline.addEventListener('pointerenter', () => decode());
+“Make our 404 page with Asciify: draw 404 large in characters that scatter under the cursor and, on Go home, break apart and re-form. Keep the message and button in HTML.”
+
+```ts
+import { fieldBackground } from 'asciify-engine/kit';
+
+const lost = fieldBackground(lostArt, { preset: 'notFound', text: '404' });
+homeLink.onclick = async event => { event.preventDefault(); await lost.scatter(homeLink); location.href = '/'; };
 ```
 
-## image-reveal: Photo from characters
-Category: Transitions
+## wordmark: Brand wordmark
+Category: Text
 
 Prompt:
-“Show [photo] drawn in characters with Asciify. On hover or focus the real photo grows out of the characters in a soft circle from the cursor, and on leave it closes back with a pulse where the pointer left.”
-
-```ts
-const art = asciiField(canvas, {
-  source: '/images/egret.jpg', fit: 'cover', charset: ' .:-=+*#%@', cellSize: 6,
-  contrast: 1.3, hover: 'trail', label: 'A great egret, drawn in characters',
-}, '--ascii-ink-strong');
-
-// The photo lies over the canvas, masked by radial-gradient(circle at var(--x) var(--y), #000 calc(var(--r) - 56px), transparent var(--r)),
-// with --r registered as a <length> through @property so it can transition.
-function reveal(open: boolean, x = frame.clientWidth / 2, y = frame.clientHeight / 2) {
-  const ms = matchMedia('(prefers-reduced-motion: reduce)').matches ? 0 : open ? 520 : 440;
-  if (open) photo.style.cssText += `--x:${x}px;--y:${y}px`;
-  else art?.field.pulse({ x, y });
-  photo.style.transition = `--r ${ms}ms cubic-bezier(.16, 1, .3, 1)`;
-  photo.style.setProperty('--r', open ? `${Math.hypot(frame.clientWidth, frame.clientHeight) + 56}px` : '0px');
-}
-frame.addEventListener('pointerenter', event => reveal(true, event.offsetX, event.offsetY));
-frame.addEventListener('pointerleave', event => reveal(false, event.offsetX, event.offsetY));
-frame.addEventListener('focus', () => reveal(true));
-frame.addEventListener('blur', () => reveal(false));
+“Draw our name, [name], in moving characters with Asciify for [the footer or a hero]. The word stays crisp, characters trail under the cursor, and the real name stays in HTML for screen readers.”
+
+```ts
+import { wordmark } from 'asciify-engine/kit';
+
+// draws the element's own text, which stays in the DOM for screen readers
+const mark = wordmark(brandName, { font: 'Georgia, "Times New Roman", serif', fontWeight: 600 });
+nameInput.oninput = () => mark.setText(nameInput.value);
 ```
 
-## route-transition: Page transition
-Category: Transitions
+## video: Video in characters
+Category: Media
 
 Prompt:
-“When someone switches [tabs or pages] in [our app], sweep a dense Asciify character field out from the clicked tab, swap the page underneath, and sweep it away, all in about half a second. Swap instantly under reduced motion.”
+“Play [video] in characters with Asciify as [a section background or a card]. Muted, looping, paused off screen, with a play and pause control, and the poster for reduced motion.”
 
 ```ts
-const veil = asciiField(canvas, {
-  mark: 'glyph', scene: 'flow', charset: ' .:-=+*#%@', cellSize: 10, scale: 2.4,
-  speed: 1.6, contrast: 1.4, brightness: 0.34, hover: 'none',
-});
-veil?.field.pause();
-
-// cover holds the canvas on background: var(--surface), visibility: hidden at rest, masked by radial-gradient(circle at var(--x) var(--y),
-// transparent var(--hole), #000 calc(var(--hole) + 36px), #000 var(--front), transparent calc(var(--front) + 36px)); --hole and --front are @property lengths.
-async function navigate(tab: HTMLElement, swap: () => void) {
-  if (matchMedia('(prefers-reduced-motion: reduce)').matches) return swap();
-  const box = cover.getBoundingClientRect(), t = tab.getBoundingClientRect(), ease = 'cubic-bezier(.16, 1, .3, 1)';
-  const x = t.left + t.width / 2 - box.left, y = t.top + t.height / 2 - box.top, reach = `${Math.hypot(box.width, box.height) + 36}px`;
-  cover.style.cssText += `--x:${x}px;--y:${y}px;visibility:visible`;
-  veil?.field.play();
-  veil?.field.pulse({ x, y });
-  await cover.animate({ '--hole': ['-72px', '-72px'], '--front': ['-36px', reach] }, { duration: 180, easing: ease, fill: 'forwards' }).finished;
-  swap();
-  await cover.animate({ '--hole': ['-72px', reach], '--front': [reach, reach] }, { duration: 320, easing: ease }).finished;
-  cover.style.visibility = 'hidden';
-  veil?.field.pause();
-}
+import { asciiVideo } from 'asciify-engine/kit';
+
+// muted and looping, paused off screen; the poster shows first and under reduced motion
+const v = asciiVideo(player, { src: '/media/magnolia.mp4', poster: '/media/magnolia.jpg', label: 'A magnolia opening, drawn in characters' });
+playButton.onclick = () => playButton.setAttribute('aria-label', v.toggle() ? 'Pause' : 'Play');
 ```
 
-## scramble-button: Scramble button
-Category: Transitions
+## hero-background: Hero background
+Category: Backgrounds
 
 Prompt:
-“Make [our primary button]'s label scramble through ASCII characters on hover and focus without changing width, with a small Asciify dot halo behind it that follows the cursor and pulses on press.”
+“Put a calm ASCII background behind our hero with Asciify. Characters drift toward the headline and soften under a frosted veil, ripple under the cursor, and pulse when someone presses the main button.”
 
 ```ts
-const halo = asciiField(canvas, {
-  mark: 'dot', scene: 'drift', cellSize: 6, dotScale: 0.8, scale: 2.2, hover: 'lantern',
-  clear: { element: button, padding: 4, feather: 0.12, shape: 'rect' },
-});
-button.addEventListener('click', () => halo?.field.pulse({ element: button }));
-
-const text = label.textContent ?? '', ramp = '.:-=+*#%@abcdefghijklmnopqrstuvwxyz';
-const live = Object.assign(document.createElement('span'), { ariaHidden: 'true', textContent: text, style: 'position:absolute;inset:0;white-space:nowrap' });
-button.setAttribute('aria-label', text);
-label.replaceChildren(Object.assign(document.createElement('span'), { textContent: text, style: 'visibility:hidden;white-space:nowrap' }), live); // label is position: relative; the hidden copy holds the width
-function scramble() {
-  if (matchMedia('(prefers-reduced-motion: reduce)').matches) return;
-  const start = performance.now();
-  requestAnimationFrame(function frame(now) {
-    const settled = Math.floor((now - start - 120) / 28);
-    live.textContent = [...text].map((ch, i) => (i < settled || ch === ' ' ? ch : ramp[Math.floor(Math.random() * ramp.length)])).join('');
-    if (settled < text.length) requestAnimationFrame(frame);
-  });
+import { fieldBackground } from 'asciify-engine/kit';
+
+const bg = fieldBackground(heroSection, { preset: 'hero', clear: heroText, ripple: true });
+subscribeButton.onclick = () => bg.pulse(subscribeButton, 1.4);
+```
+
+```css
+/* The veil: characters blur and fade toward the words instead of stopping at a box edge. */
+.hero-text { position: relative; isolation: isolate; }
+.hero-text::before {
+  content: ""; position: absolute; z-index: -1; inset: -24px -40px; pointer-events: none;
+  background: color-mix(in oklab, var(--bg) 58%, transparent);
+  backdrop-filter: blur(9px);
+  mask-image: radial-gradient(closest-side, #000 52%, rgb(0 0 0 / .6) 74%, transparent);
 }
-button.addEventListener('pointerenter', scramble);
-button.addEventListener('focus', () => { if (button.matches(':focus-visible')) scramble(); });
 ```
 
-## thinking: Thinking state
-Category: AI
+## Advanced: raw field
 
-Prompt:
-“Show [our assistant]'s thinking state with Asciify: dot lines shimmer where the answer will appear under a Thinking… label, then the answer streams in word by word as the dots fade. Regenerate runs it again.”
-
-```ts
-import { play } from 'cuelume';
-
-const dots = asciiField(canvas, { mark: 'dot', scene: 'drift', cellSize: 5, dotScale: 0.86, scale: 3, speed: 2.4, hover: 'none' });
-
-// The canvas fills the answer area under line-shaped mask bands; CSS fades it out, and each .word in 38ms apart, once data-phase leaves "thinking".
-async function regenerate(ask: () => Promise<string>) {
-  play('loading', { emphasis: 'subtle' });
-  reply.dataset.phase = 'thinking';
-  dots?.field.play();
-  const beat = setInterval(() => dots?.field.pulse({ x: Math.random() * canvas.clientWidth, y: canvas.clientHeight / 2, strength: 0.7 }), 640);
-  const answer = await ask().finally(() => clearInterval(beat));
-  answerText.replaceChildren(...answer.split(' ').map((word, i) => {
-    const span = Object.assign(document.createElement('span'), { className: 'word', textContent: `${word} ` });
-    span.style.setProperty('--i', String(i));
-    return span;
-  }));
-  reply.dataset.phase = 'done';
-  setTimeout(() => dots?.field.pause(), 420);
-  play('ready', { emphasis: 'subtle' });
+The kit is built on `mountGlyphField` from `asciify-engine/field`. When a component needs a look the kit has no option for, mount the field yourself. This helper needs no kit: it mounts a field that takes its ink from a CSS custom property, follows light and dark, and cleans up after itself. Without the kit you own the rest: check `isGlyphFieldSupported()` and keep the static design as the fallback, honour reduced motion, mount off-screen fields lazily and call `destroy()` on unmount. GPU fields need asciify-engine 4.12 or later for `mark`, `clear` and `pulse()`.
+
+```ts
+import { isGlyphFieldSupported, mountGlyphField, type GlyphField, type GlyphFieldOptions } from 'asciify-engine/field';
+
+/** A field inked from a CSS variable that follows the theme. Returns null when the GPU field isn't available. */
+export function asciiField(canvas: HTMLCanvasElement, options: GlyphFieldOptions = {}, inkVar = '--ascii-ink') {
+  if (!isGlyphFieldSupported()) return null;
+  const ink = () => getComputedStyle(canvas).getPropertyValue(inkVar).trim() || '#8f8d86';
+  const field: GlyphField = mountGlyphField(canvas, { color: 'ink', background: 'transparent', ...options, ink: ink() });
+  const scheme = matchMedia('(prefers-color-scheme: dark)');
+  const retint = () => field.update({ ink: ink() });
+  scheme.addEventListener('change', retint);
+  return { field, destroy() { scheme.removeEventListener('change', retint); field.destroy(); } };
 }
 ```
 
-## image-generation: Image generation
-Category: AI
+```css
+:root { --ascii-ink: #76746e; --ascii-ink-strong: #1d1d1b; }
+@media (prefers-color-scheme: dark) { :root { --ascii-ink: #7a7872; --ascii-ink-strong: #d8d6cf; } }
+```
 
-Prompt:
-“While [our image model] generates [prompt], fill the frame with drifting Asciify characters that pulse beside a progress label. When the image arrives, develop it in characters, then fade to the photo from blur to sharp.”
+In React, wrap it once and reuse it:
 
-```ts
-const art = asciiField(canvas, {
-  mark: 'glyph', scene: 'flow', charset: ' .:-=+*#%@', cellSize: 7, scale: 2.6, speed: 1.4, contrast: 1.3, hover: 'trail',
-}, '--ascii-ink-strong');
-const ease = (ms: number, step: (k: number) => void) => new Promise<void>(done => {
-  const start = performance.now(), still = matchMedia('(prefers-reduced-motion: reduce)').matches;
-  requestAnimationFrame(function frame(now) { const t = still ? 1 : Math.min(1, (now - start) / ms); step(1 - (1 - t) ** 4); if (t < 1) requestAnimationFrame(frame); else done(); });
-});
+```tsx
+import { useEffect, useRef } from 'react';
+import type { GlyphField, GlyphFieldOptions } from 'asciify-engine/field';
 
-generate.addEventListener('click', async () => {
-  const field = art?.field;
-  if (!field) return;
-  const beat = setInterval(() => field.pulse({ strength: 0.8 }), 640);
-  const url = await createImage(promptInput.value).finally(() => clearInterval(beat));
-  await ease(200, k => field.update({ brightness: -k }));
-  await field.setSource(url);
-  field.pulse();
-  await ease(900, k => field.update({ brightness: k - 1 }));
-  photo.src = url;
-  imageFrame.dataset.done = ''; // CSS fades the photo in from opacity 0 and blur(14px), 760ms on cubic-bezier(.16, 1, .3, 1)
-});
+export function AsciiField({ options, onField, className }: { options: GlyphFieldOptions; onField?: (field: GlyphField | null) => void; className?: string }) {
+  const canvas = useRef<HTMLCanvasElement>(null);
+  useEffect(() => {
+    const mounted = canvas.current ? asciiField(canvas.current, options) : null;
+    onField?.(mounted?.field ?? null);
+    return () => { onField?.(null); mounted?.destroy(); };
+  }, []); // mount once; call field.update() for later changes
+  return <canvas ref={canvas} className={className} aria-hidden="true" />;
+}
 ```
+
+A raw field draws whatever source you give it: paint white on black into an offscreen canvas (white is the densest glyph) and pass it to `field.setSource()` each frame, or use `scene`, `pulse()` and `update()` directly. To build your own component on the kit's plumbing instead (theme ink, reduced motion, fallback and cleanup included), use `mountSurface` from the kit; see [the kit reference](kit.md#your-own-components).