asciify-engine 4.23.0 → 4.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "4.23.0",
+  "version": "4.24.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,7 +70,7 @@
   },
   "files": [
     "dist",
-    "!dist/*.map",
+    "!dist/**/*.map",
     "skills/asciify-engine",
     "README.md",
     "LICENSE",

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.24.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.24.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/performance.md

@@ -0,0 +1,30 @@
+# 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
+
+- **Context budget: 12.** At most 12 kit fields hold a WebGL context at once (`setFieldBudget(n)` changes it); past it the field farthest off screen is released to its `poster`. A context the browser takes back is remounted on a fresh canvas. 150 components on one page keep 12 contexts and lose 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.** About a second of frames slower than 24 fps drops the field to 1× pixels, then to no 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.