asciify-engine 4.23.0 → 4.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "4.23.0",
+  "version": "4.25.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",
@@ -70,10 +70,11 @@
   },
   "files": [
     "dist",
-    "!dist/*.map",
+    "!dist/**/*.map",
     "skills/asciify-engine",
     "README.md",
     "LICENSE",
+    "CHANGELOG.md",
     "examples/media-background.ts",
     "examples/studio-composition.ts",
     "examples/layered-composition.ts",

package/skills/asciify-engine/SKILL.md

@@ -2,13 +2,13 @@
 name: asciify-engine
 description: Apply Asciify the way asciify.org does - ASCII components and backgrounds that belong in a real interface, inked from the theme, clear around text, inside the page's radii and motion. Use for UI components in characters (loading, status, toasts, tabs, AI states, charts, transitions, pages), animated ASCII backgrounds, and also photo, video and GIF conversion, GPU character fields, artwork looks for wallpapers, posters and prints, art styles and export, hover and motion, layered typography and rendering performance.
 metadata:
-  tested-engine: "4.23.0"
+  tested-engine: "4.25.0"
   updated: "2026-10-17"
 ---
 
 # Asciify Engine
 
-Use the published `asciify-engine` npm package. Tested against **4.23.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. Tested against **4.25.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).
 - Components: https://asciify.org/components · Looks: https://asciify.org/looks · Backgrounds: https://asciify.org/backgrounds
@@ -84,7 +84,7 @@ This uses the Vercel Skills CLI to install the repository skill and its linked r
 
 ## Verify before handing off
 
-Run the checklist at the end of [applying-asciify.md](references/applying-asciify.md#10-checklist-before-you-finish) for kit work. For any integration, check the real page: readable subject and text in both themes, no stretching or unintended margins, working pointer and keyboard controls, mobile crop, reduced motion, autoplay failure, WebGL off, and cleanup after navigation. Observe several seconds of motion and a loop boundary. State the measured device and settings with any FPS figure; screenshots alone do not establish performance.
+Run the checklist at the end of [applying-asciify.md](references/applying-asciify.md#10-checklist-before-you-finish) for kit work. For any integration, check the real page: readable subject and text in both themes, no stretching or unintended margins, working pointer and keyboard controls, mobile crop, reduced motion, autoplay failure, WebGL off, and cleanup after navigation. Observe several seconds of motion and a loop boundary. State the measured device and settings with any FPS figure; screenshots alone do not establish performance. What the engine guarantees a host page, and its default budgets, are in [performance.md](references/performance.md).
 
 Do not import nonexistent helpers such as `createRecorder` or `recordAndDownload`.
 

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

@@ -149,7 +149,7 @@ decode(headline, { duration: 800, settle: 'text' }); // decorative, under the 80
 
 ## 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.
+- **Fields share one context.** Every field on the page draws through one WebGL2 context, so the count of fields is bounded by what is animating on screen, not by contexts. Static fields draw once and stop. Sharing still helps: 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.

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

@@ -169,8 +169,8 @@ const s = mountSurface({ host: el, look: () => ({ mark: 'glyph', cellSize: 6 }),
 
 A page can hold every kit component at once. The shared core keeps the GPU cost to what is on screen:
 
-- **Lazy mounting.** A field mounts when its element comes within half a viewport of the screen and is released, freeing its WebGL context, beyond one viewport. Mounts that cost more than about 4 ms in a frame wait for the next one, nearest the screen first. The handle survives release and remount: its methods keep working, `update()` calls made while released apply on the next mount, `pause()` holds, and the component paints its current state when it mounts again. `handle.field` stays the same object throughout. A remount swaps a copy of the canvas, with its attributes and inline styles, into the same place. `lazy: false` mounts at once, anywhere on the page, and is never released by distance.
-- **Context budget.** At most 12 kit fields hold a WebGL context at once, across all components and page helpers (browsers drop the oldest past about 16). Past the budget the live field farthest off screen is released first, and a waiting field mounts as soon as it is nearer than the farthest live one. Change it with `setFieldBudget(n)`; `getFieldBudget()` reads it.
+- **Lazy mounting.** A field mounts when its element comes within half a viewport of the screen and is released, freeing its GPU memory, beyond one viewport. Mounts that cost more than about 4 ms in a frame wait for the next one, nearest the screen first. The handle survives release and remount: its methods keep working, `update()` calls made while released apply on the next mount, `pause()` holds, and the component paints its current state when it mounts again. `handle.field` stays the same object throughout. A remount draws into the same canvas (a field with a context of its own swaps in a copy, with its attributes and inline styles). `lazy: false` mounts at once, anywhere on the page, and is never released by distance.
+- **One context, and a budget for the rest.** Kit fields draw through the page's one shared WebGL2 context and hold none of their own. `setFieldBudget(n)` (default 12) limits fields that fall back to a context of their own (a canvas in another document, or one already holding a WebGL context; browsers drop the oldest past about 16): past it the live one farthest off screen is released first. `getFieldBudget()` reads it.
 - **Posters.** `poster: '/stills/hero.webp'` puts an `<img>` under the canvas (`update({ poster })` points it at another still, such as the other theme's), placed exactly where the field draws. It fades out (280 ms, none under reduced motion) when the first GPU frame lands, shows again while the field is released, and stays as the fallback without WebGL or after the field fails, until `destroy()`. `update({ poster })` swaps the still in place, for a theme change, on every component including the page helpers and `asciiVideo`. `asciiVideo` keeps its own poster.
 - **Pausing.** As before, a field draws nothing while the page is hidden or its element is off screen.
 

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

@@ -0,0 +1,33 @@
+# Performance guarantees
+
+What `asciify-engine` promises a host page, and the default budgets. Measured by `tests/host-cost-browser.mjs` and `scripts/bundle-cost.mjs` in the engine repository, and held by its unit tests.
+
+## Import and bundle
+
+- **No work at import.** Every entry (`asciify-engine`, `/core`, `/field`, `/hover`, `/studio`, `/kit`) only defines code: no DOM, canvas, WebGL, observer, timer, frame or global is touched until you call something. Safe under SSR (Next.js, Remix, Astro) without a `window` guard on the import.
+- **`sideEffects: false`, and the kit is split per component.** A route that imports one kit component downloads that component, the shared kit core (about 20 kB) and the field (about 67 kB), not the whole kit: `fieldBackground` alone costs a code-split host about 90 kB minified (33 kB gzipped), against 285 kB (100 kB) when the kit was one module.
+
+## Main thread
+
+- **Mounting is spread out.** Kit fields mount when they come within half a viewport of the screen, at most one per frame however many a host starts in one task (a route change, a long list). Shader programs link with `KHR_parallel_shader_compile` where the browser has it.
+- **Nothing runs when nothing changes.** A still field stops its frame loop. Fields off screen, in a hidden tab, in a `display: none` host or with zero size do not draw. Reduced motion settles every component on a still.
+- **Ambient motion is capped.** Drift, scenes and self-animating components draw at most 60 frames a second on any screen (30 with two cores or less, 2 GB of memory or less, or Save-Data). The pointer's wake, lantern, trail, pulses and anything under the pointer keep the screen's full rate.
+- **Studio hovers stay responsive.** A live `mountStudio` hover renders at most 60 times a second and never more often than leaves half the main thread free, then ends on its settled frame.
+- **Listeners are passive** where the event allows, and every listener, observer, frame, timer, object URL and context is released by `destroy()`, including after a hundred quick mount and destroy cycles.
+- **No global CSS but scoped fallbacks.** The few components that inject styles use one `<style id="ascii-kit-…">` each, with every rule inside `:where()` (zero specificity). No console output in normal use.
+
+## GPU and memory
+
+- **One context per page.** Every glyph field on the page (kit components, page helpers and `mountGlyphField`) draws through one shared WebGL2 context and one frame loop, and each field's canvas receives its frame with a 2D copy. Programs compile once for the page and glyph atlases are shared per charset, font and size, so mounting a field creates no context and compiles nothing; 150 components on one page hold one context. A context the browser takes back is replaced, and every field draws again. The context is let go three seconds after the page's last field.
+- **GPU memory budget: 256 MB per page.** The shared context counts what every field holds on the GPU: its render targets, its source texture with mipmaps, its wake and trail buffers, its canvas, the shared atlases and the shared drawing buffer. Past 256 MB, kit fields off screen are released to their posters, farthest first, and fields waiting to mount keep their posters until there is room; a field on screen is never released for memory. Atlases are shared per charset, font and size; up to eight that no field uses are kept for a remount and evicted oldest first (all of them while over budget). The shared drawing buffer shrinks when the largest field leaves. Fields mounted directly with `mountGlyphField` count toward the total but are never released by it: destroy them yourself.
+- **Context budget.** `setFieldBudget(n)` (default 12) still limits fields that fall back to a context of their own: a canvas from another document, or one that already holds a WebGL context. Past it the field farthest off screen is released to its `poster`.
+- **Page listeners don't grow.** One pointer listener (capture, on the window), one visibility, motion, colour-scheme and font listener, and one ResizeObserver serve every field, so mounting and releasing fields while scrolling adds and removes none.
+- **Backing store capped.** Pixel ratio is at most 2 by default (`look.maxPixelRatio`), and one field's backing store at most about one 4K screen (8.3 million pixels): a full-bleed field on a 5K or 6K display keeps its cells and draws them at a lower ratio.
+- **Slow frames degrade, not stall.** The shared context times its own frames on the GPU (`EXT_disjoint_timer_query_webgl2`, or the frame loop's gaps where it is missing) and lowers the render scale in steps, down to one device pixel per CSS pixel, before any frame is given up; it climbs back once there is headroom. Past that, about a second of frames slower than 24 fps stops a field's ambient motion; the pointer response keeps working.
+- **Software WebGL counts as unsupported.** SwiftShader and llvmpipe report `isGlyphFieldSupported() === false` (pass `allowSoftware` to override), so components keep their HTML and poster instead of drawing every pixel on the CPU. Without WebGL2 the same fallback applies.
+
+## What a host should still do
+
+- Give heavy components a `poster`, so a released or unsupported field still shows its still.
+- Call `destroy()` on unmount. In React, mount in an effect and destroy in its cleanup; StrictMode's double mount is safe.
+- Keep `lazy` on (the default) for anything below the fold. `lazy: false` mounts at once wherever the element is.