asciify-engine 4.11.0 → 4.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "4.11.0",
+  "version": "4.12.0",
   "description": "Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII art rendered on canvas, or run full-bleed GPU character fields with a fluid cursor wake.",
   "type": "module",
   "main": "./dist/index.cjs",

package/skills/asciify-engine/SKILL.md

@@ -2,13 +2,13 @@
 name: asciify-engine
 description: Build and tune browser ASCII art with asciify-engine so it fits the user's request, preferences and the project's design. Use for photo, video and GIF conversion, interactive heroes, GPU character fields with the user's own words, ambient backgrounds, text banners, art styles and export, hover and motion choices, layered HTML typography, and rendering performance.
 metadata:
-  tested-engine: "4.11.0"
-  updated: "2026-10-09"
+  tested-engine: "4.12.0"
+  updated: "2026-10-14"
 ---
 
 # Asciify Engine
 
-Use the published `asciify-engine` npm package for browser canvas rendering. Tested against **4.11.0**. Check the application's installed version and its public types before using newer options; a local checkout can contain unpublished changes.
+Use the published `asciify-engine` npm package for browser canvas rendering. Tested against **4.12.0**. Check the application's installed version and its public types before using newer options; a local checkout can contain unpublished changes.
 
 - Agent entry: https://asciify.org/skill (redirects to this Markdown document).
 - Playground: https://asciify.org/editor
@@ -31,12 +31,15 @@ Most requests are a feeling ("make the hero feel alive", "retro", "subtle behind
 4. **Decide living or still.** A still photo can be made to feel alive (field `drift`, studio `motion`), but some users want it still. Follow their words; keep art behind text, in grids and in data views still; reduced motion always gets a still. See [living or still](references/design-matching.md#living-or-still).
 5. **Say what you chose in one line** and offer one alternative. Ask only when the media is missing or motion would be new to a site that has none.
 
+[references/components.md](references/components.md) has 21 ready-made components with a shared theme-aware helper: interface pieces (image card, avatar, empty state, loading state, copy feedback), backgrounds (hero, cursor field, brand field), text (CLI banner, wordmark, decode headline), transitions (photo from characters, page transition, scramble button), pages (404, coming soon, sign-in, pricing), AI states (thinking, image generation) and video in characters, each with the prompt a person gives and the reference code. Start there when the request matches one.
+
 [references/design-matching.md](references/design-matching.md) maps mood words to settings, explains light themes, contrast and fonts, and gives tested recipes for the common requests. Read it whenever the user describes a look rather than an option.
 
 | The user wants | Use |
 | --- | --- |
 | Their photo, video or GIF as ASCII on the page, optionally answering the cursor | `asciify` / `asciifyVideo` / `asciifyGif`, plus `mountHover` from `/hover` for the website hovers |
 | A full-bleed hero or brand field that stays smooth under the cursor, or their own word as the characters | `mountGlyphField` from `/field` ([glyph-field.md](references/glyph-field.md)); `hover: 'trail'` for the classic Asciify Trail on pure characters, `'fluid'` for bold and liquid, `'lantern'` for a subtle light |
+| A calm background behind product content (SaaS hero, pricing, docs), light or dark | `mountGlyphField` with `mark: 'dot'`, `scene: 'drift'`, `clear` around the copy, and `pulse()` on events (4.12) |
 | Art styles, saved looks, backdrops, masks, effects, PNG/MP4/GIF export | `mountStudio` from `/studio` ([studio-workspace.md](references/studio-workspace.md)) |
 | Several media and text layers in one artwork | `mountStudioProject` from `/studio` ([layered-projects.md](references/layered-projects.md)) |
 | An ambient background with no media | A template from asciify.org/backgrounds, or a `/field` generated scene |
@@ -196,3 +199,7 @@ From 4.9, optional Studio adds Stipple, Engraving, Crosshatch, Woodblock, Risogr
 ### GPU glyph fields (4.11)
 
 `asciify-engine/field` adds `mountGlyphField`, `isGlyphFieldSupported` and `glyphFieldTier`. Older installs do not have this entry; upgrade before using it.
+
+## Scenario prompts
+
+Use [scenario-prompts.md](references/scenario-prompts.md) for copyable briefs covering images, heroes, characters, all styles, dither, backgrounds, video/GIF, scroll, layers, text, export, frameworks, procedural trails, reference matching, troubleshooting, upgrades, saved looks and accessibility. Adapt the prompt to the user’s intent; do not add unrelated features. Use the published renderer’s native Trail; do not add a separate tonal ribbon overlay.

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

@@ -0,0 +1,460 @@
+# 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.
+
+Build them in the project's own framework, design tokens and lifecycle. Read [design matching](design-matching.md) first. The shared rules:
+
+- 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()`.
+
+## The shared helper
+
+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.
+
+```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(); } };
+}
+```
+
+```css
+:root { --ascii-ink: #76746e; --ascii-ink-strong: #1d1d1b; }
+@media (prefers-color-scheme: dark) { :root { --ascii-ink: #7a7872; --ascii-ink-strong: #d8d6cf; } }
+```
+
+In React, wrap it once and reuse it:
+
+```tsx
+import { useEffect, useRef } from 'react';
+import type { GlyphField, GlyphFieldOptions } from 'asciify-engine/field';
+
+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" />;
+}
+```
+
+## image-card: ASCII image card
+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.”
+
+```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');
+```
+
+## hero-background: Hero background
+Category: Backgrounds
+
+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.”
+
+```ts
+const hero = asciiField(canvas, {
+  mark: 'glyph', scene: 'drift', charset: ' .:+*#', cellSize: 12,
+  clear: { element: heroText, padding: 24, feather: 0.32, shape: 'ellipse' },
+  hover: 'trail',
+});
+```
+
+## cli-banner: CLI banner
+Category: Text
+
+Prompt:
+“Greet people in ASCII when our CLI starts, using asciifyText from Asciify with [word].”
+
+```ts
+import { asciifyText } from 'asciify-engine';
+
+console.log(asciifyText('Hey', { char: '#' }));
+```
+
+## cursor-field: Cursor field
+Category: Backgrounds
+
+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].”
+
+```ts
+const dots = asciiField(canvas, {
+  mark: 'dot', scene: 'drift', dotScale: 0.72, cellSize: 8,
+  clear: { element: content, padding: 40, shape: 'rect' },
+  hover: 'fluid',
+});
+```
+
+## wordmark: Brand wordmark
+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.”
+
+```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);
+
+const wordmark = asciiField(canvas, {
+  source: word, fit: 'contain', charset: ' .:-=+*#%@', cellSize: 9,
+  hover: 'trail', label: 'asciify, drawn in characters',
+}, '--ascii-ink-strong');
+```
+
+## video: Video in characters
+Category: Media
+
+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.”
+
+```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');
+
+let paused = false;
+playButton.addEventListener('click', () => {
+  paused = !paused;
+  if (paused) video?.field.pause(); else video?.field.play();
+});
+```
+
+## not-found: 404 page
+Category: Pages
+
+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.”
+
+```ts
+const lost = asciiField(canvas, {
+  mark: 'glyph', scene: 'drift', charset: ' .:+*#', cellSize: 12, hover: 'trail',
+  clear: { element: message, padding: 28, feather: 0.3, shape: 'ellipse' },
+});
+
+homeLink.addEventListener('click', () => lost?.field.pulse({ element: homeLink }));
+```
+
+## avatar: ASCII avatar
+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.”
+
+```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');
+```
+
+## empty-state: Empty state
+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.”
+
+```ts
+const empty = asciiField(canvas, {
+  scene: 'flow', charset: ' .:-=+*#', cellSize: 11, hover: 'none',
+  clear: { element: emptyMessage, padding: 24, shape: 'rect' },
+});
+
+primaryButton.addEventListener('click', () => empty?.field.pulse({ element: primaryButton }));
+```
+
+## loading: Loading state
+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.”
+
+```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));
+```
+
+## copy-pulse: Copy feedback
+Category: Components
+
+Prompt:
+“When someone copies [the coupon code], answer with Asciify: a pulse travels through a halftone field from the copy button.”
+
+```ts
+const ground = asciiField(canvas, { mark: 'dot', scene: 'drift', cellSize: 7, dotScale: 0.8, hover: 'none' });
+
+copyButton.addEventListener('click', async () => {
+  await navigator.clipboard.writeText(code);
+  ground?.field.pulse({ element: copyButton });
+});
+```
+
+## brand-field: Brand color field
+Category: Backgrounds
+
+Prompt:
+“Make an ASCII field in our brand color with Asciify, drifting slower than the default, for [section].”
+
+```ts
+const brand = asciiField(canvas, {
+  mark: 'glyph', scene: 'drift', charset: ' .:+*#', cellSize: 10,
+  speed: 0.5, hover: 'none',
+}, '--brand');
+```
+
+## coming-soon: Coming soon page
+Category: Pages
+
+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.”
+
+```ts
+const waitlist = asciiField(canvas, {
+  mark: 'glyph', scene: 'drift', charset: ' .:+*#', cellSize: 10, hover: 'trail',
+  clear: { element: form, padding: 14, feather: 0.24, shape: 'ellipse' },
+});
+
+form.addEventListener('submit', event => {
+  event.preventDefault();
+  waitlist?.field.pulse({ element: joinButton });
+  form.dataset.state = 'joined';
+});
+```
+
+## 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.”
+
+```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');
+
+signInForm.addEventListener('submit', event => {
+  event.preventDefault();
+  continueButton.setAttribute('aria-busy', 'true');
+  art?.field.pulse({ element: continueButton });
+});
+```
+
+## 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.”
+
+```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 },
+});
+
+trialButton.addEventListener('click', () => featured?.field.pulse({ element: trialButton }));
+```
+
+## text-decode: Decode headline
+Category: Text
+
+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());
+```
+
+## image-reveal: Photo from characters
+Category: Transitions
+
+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));
+```
+
+## route-transition: Page transition
+Category: Transitions
+
+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.”
+
+```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();
+}
+```
+
+## scramble-button: Scramble button
+Category: Transitions
+
+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.”
+
+```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);
+  });
+}
+button.addEventListener('pointerenter', scramble);
+button.addEventListener('focus', () => { if (button.matches(':focus-visible')) scramble(); });
+```
+
+## thinking: Thinking state
+Category: AI
+
+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' });
+}
+```
+
+## image-generation: Image generation
+Category: AI
+
+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.”
+
+```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(); });
+});
+
+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)
+});
+```

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

@@ -37,6 +37,7 @@ Never introduce a new brand color, a black canvas on a light site, or a second a
 | --- | --- | --- |
 | 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). |
 | 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. |
@@ -54,6 +55,7 @@ Never introduce a new brand color, a black canvas on a light site, or a second a
 | Techy, data, futuristic | Braille, blocks, dots, LED, hex | Source color with saturation 1.1–1.3, or a cool brand ink | 5–9px | Silk, Contour, Lens; field with `orb` or `flow` |
 | Playful | Emoji or custom glyphs, mosaic, bricks, voxels | Source color | 9–14px | Elastic, Scatter, Ripple rings |
 | Brand, identity, "our name in the art" | The brand word after a quiet ramp: `' .,:-+' + WORD` | One ink (`color: 'ink'`, `shade: 1`) so density and brightness carry the image | 10–14px; `cellAspect` 0.75–0.85 for display fonts | Field `hover: 'fluid'` (Unseen-like) or `'lantern'` (quieter); video or generated scene underneath |
+| Product UI, SaaS, docs | Halftone dots (`mark: 'dot'`) | Muted text token, never the accent; light and dark both | 12–16px dot spacing, `dotScale` ~0.6, `clear` around the copy | Lantern or none; `pulse()` on saves and messages |
 | Behind body text | Light ramp, no dense glyphs | Ink at low contrast against the background; opacity 0.15–0.35 | 10–14px | Ambient only, or none; never strong refraction behind reading text |
 
 Hover choice by intent:

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

@@ -32,7 +32,10 @@ Size the canvas with CSS (for example `position:absolute; inset:0; width:100%; h
 | Option | Default | Notes |
 | --- | --- | --- |
 | `source` | none | URL (`.mp4`, `.webm`, `.mov` load as muted, looping, inline video), `HTMLImageElement`, `HTMLVideoElement`, `HTMLCanvasElement` or `ImageBitmap`. Cross-origin media needs CORS. |
-| `scene` | `'flow'` | Generated motion when there is no source: `'flow'` (domain-warped noise), `'orb'` (lit sphere) or `'none'` (blank, wake only). |
+| `scene` | `'flow'` | Generated motion when there is no source: `'flow'` (domain-warped noise), `'drift'` (a few broad lobes, made for halftone, 4.12), `'orb'` (lit sphere) or `'none'` (blank, wake only). |
+| `mark`, `dotScale` | `'glyph'`, `0.9` | `'dot'` draws a halftone: one circle per cell whose area follows tone, antialiased at any pixel ratio. `dotScale` is the largest dot as a fraction of the cell; about 0.6 keeps a calm, open grid. (4.12) |
+| `scale` | `1` | Feature size of generated scenes; higher is finer. Use about 1.8 on phones, where the field is tall. (4.12) |
+| `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. |
 | `font`, `fontWeight`, `glyphScale` | monospace, `500`, `0.8` | Any loaded CSS font. The atlas is redrawn when the font finishes loading. |
@@ -56,6 +59,26 @@ Size the canvas with CSS (for example `position:absolute; inset:0; width:100%; h
 
 `update(options)` merges and rebuilds only what changed (the atlas for type changes, the simulation for resolution changes). `setSource(source)` swaps media. `pointer(x, y)` moves the wake in CSS pixels relative to the canvas (`pointer(null)` lifts it), which is useful for an intro stroke. `redraw()` draws immediately, so you can copy the canvas with `drawImage` in the same task, for example to cross-fade between looks.
 
+## Halftone for interfaces (4.12)
+
+Product pages, docs, pricing and SaaS heroes want a background that is calm, works in light and dark themes, and never fights the copy. Use dots, the drift scene, a clear zone around the content, and `pulse()` for interface events:
+
+```ts
+const field = mountGlyphField(heroCanvas, {
+  mark: 'dot', scene: 'drift', cellSize: 14, dotScale: 0.64,
+  color: 'ink', ink: tokens.textMuted, background: 'transparent',
+  clear: { element: heroCopy, padding: 40, feather: 0.18 },
+  hover: 'lantern',
+});
+saveButton.addEventListener('click', () => field.pulse({ element: saveButton }));
+```
+
+- Ink: the muted text token, not the accent. On light grounds a mid grey such as `#9a988f`; on dark about `#5f5e58`.
+- Clear zone: always set one when text sits over the field. Measure contrast at the busiest frame anyway.
+- Pulse: one ring per meaningful event (saved, sent, connected), not on every click. It is skipped under reduced motion.
+- `pulse({ x, y })` takes CSS pixels relative to the canvas; `pulse({ element })` starts at the element's centre; no argument starts at the centre.
+
+
 ## Living or still
 
 A photo with `drift: 0`, no video and a pointer that has left draws once and stops. Add `drift` (0.15–0.35) to let it breathe, use a video, or use a generated `scene` for continuous motion. Choose by the user's words and the context; [design-matching.md](design-matching.md#living-or-still) has the rules. Reduced motion stops drift and generated scenes; Lantern follows instantly and stops flickering.

package/skills/asciify-engine/references/scenario-prompts.md

@@ -0,0 +1,83 @@
+# Asciify scenario prompts
+
+Copy a prompt, replace bracketed inputs, and keep your own visual direction. These are starting points for common supported workflows, not a claim to cover every possible project. Read [project integration](project-integration.md) first. Inspect the installed package's types; never guess exports or option IDs.
+
+## Shared acceptance criteria
+
+Preserve the existing framework, design and chosen media. Use one renderer owner per composition. Keep navigation and readable copy in HTML. Include loading/error states, responsive crop, reduced motion, offscreen/hidden pause and unmount cleanup. Test live motion, not only a screenshot. Report tested package version and remaining limitations. Do not publish, deploy or upgrade unrelated dependencies unless asked.
+
+## 1. Convert a photo
+
+“Use Asciify to render [image] in [style] in this component. Preserve [subject/crop/colors]. Choose /core for simple ASCII or /studio for art styles. Include a still fallback and PNG export using supported APIs. Compare the output with the source at mobile and desktop sizes.”
+
+## 2. Interactive website hero
+
+“Add a live Asciify hero using [image] with [Trail/desired interaction]. Keep [headline/CTA] as accessible HTML and respect our design. Use one /studio player, or /field if a GPU glyph field meets the brief. Keep input and render loops bounded; honor reduced motion. Do not stack /hover over /studio.”
+
+## 3. Custom words and characters
+
+“Render [image] with [brand word/custom Unicode/block characters]. Distinguish a density ramp from repeated text. Offer the engine character catalog plus custom input, keep a leading space for shading when appropriate, and check the actual font can display each glyph. Preserve the subject and colors.”
+
+## 4. All styles and looks
+
+“Create a selector from STUDIO_STYLES and the installed Studio preset catalog. Expose every supported style without a handwritten subset. Keep render style, character ramp, color look, dither algorithm, motion and hover as separate controls. Explain which controls apply to the active style.”
+
+## 5. Dither and print
+
+“Render [source] as [dither/engraving/woodblock/risograph/etc.]. Use the genuine Studio style. For dither, use the installed algorithm catalog, compare blue noise and ordered patterns, and avoid shimmer on animation. Preserve readable midtones; compare light and dark backgrounds.”
+
+## 6. Ambient background
+
+“Build [pattern] behind [content] using a template from asciify.org/backgrounds. Templates are local downloads, not npm exports. For any Studio style, use the downloaded studio-background.js helper and its STUDIO.md instructions. Keep HTML readable, preserve the chosen look, pause offscreen and destroy on unmount.”
+
+The website's Studio background helper renders a continuous procedural source through /studio; it supports the site's 24 styles and 12 looks. Its original template mode uses its own character/dither controls. Never imply every control applies to every renderer.
+
+## 7. Video or GIF
+
+“Convert [direct permitted media file] into [style]. Start with a bounded processing resolution and 24–30 fps, then measure. Include a poster, muted inline playback, autoplay-failure UI, pause offscreen and cleanup. Do not use a YouTube watch URL as a canvas source.”
+
+## 8. Scroll-controlled footage
+
+“Connect [video] progress to [scroll region] using the installed media APIs. Keep seeking bounded, avoid duplicate playback clocks, handle metadata loading, and show a still for reduced motion. Keep page scrolling native and keyboard access intact.”
+
+## 9. Layered composition
+
+“Compose [sources and placements] with mountStudioProject when supported. Keep one project clock and shared budgets, save source keys separately from media, and keep UI text in HTML. Export with exportStudioProject independently from the live preview.”
+
+## 10. Text artwork
+
+“Turn [text] into decorative Asciify art with [font/style]. Keep an accessible HTML equivalent, wait for fonts before rasterizing, handle resize, and preserve readable surrounding content. Use Studio text settings supported by the installed version.”
+
+## 11. Export an animation
+
+“Export [composition] as [GIF/MP4] at [dimensions/duration]. Inspect the installed export API, preserve settings and source framing, and keep export progress/cancellation separate from live playback. If recording canvas instead, negotiate a supported MediaRecorder MIME type and stop every track.”
+
+## 12. Framework integration
+
+“Integrate this Asciify composition into [React/Vue/Svelte/plain JS]. Own the renderer in one lifecycle scope, update settings in place, handle async setup that resolves after unmount, and remove observers/listeners/media resources on cleanup. Test repeated mount/unmount.”
+
+## 13. Improve a trail
+
+“Improve the wake on [component] with restrained follow-through and smooth reversals. Keep the glyph grid stable and input responsive. If adding a procedural pointer chain, bound distance, curvature and work per frame; reset on exit/teleport, stop when settled and honor reduced motion. Test fast turns, slow movement, re-entry, 30/60/120 Hz and touch scrolling. Do not invent an engine proceduralTrail option.”
+
+The website uses the published renderer's native Trail. A chain-shaped tonal overlay was evaluated and removed because it obscured the artwork. Do not add it as part of a standard integration; procedural-chain experiments should be opt-in and visually verified.
+
+## 14. Match a reference
+
+“Match the visual character of [reference] using [our source]. Identify crop, density, palette, negative space and motion before selecting settings. Preserve our branding. Preview at real sizes and explain any limitation instead of claiming an exact match.”
+
+## 15. Diagnose performance or a blank canvas
+
+“Diagnose [symptom] before changing the look. Check source loading/CORS, canvas dimensions, installed API, GPU fallback, visibility and lifecycle. Measure on [device]. Reduce processing size/cell count before source FPS; do not claim FPS from screenshots. Keep HTML and poster visible on failure.”
+
+## 16. Upgrade an existing project
+
+“Update only Asciify and its installed skill as needed for [feature]. Inspect current version, public exports and migration guidance; preserve the user's settings and dependency manager. Remove obsolete catalog imports, verify preview/export parity and report the tested version. Do not deploy or publish a package automatically.”
+
+## 17. Save and restore a look
+
+“Save the active Studio settings as JSON and restore them through the installed normalizer. Store media references separately, keep defaults compatible with the installed version, and test malformed/older settings without losing the user's current work.”
+
+## 18. Accessible interaction
+
+“Audit this Asciify component for keyboard access, touch scrolling, contrast, reduced motion and error states. Keep decorative canvases out of the reading order, provide text alternatives for meaningful artwork, and keep every CTA usable when rendering fails.”