asciify-engine 4.14.2 → 4.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "4.14.2",
+  "version": "4.15.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: 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, art styles and export, hover and motion, layered typography and rendering performance.
 metadata:
-  tested-engine: "4.14.2"
+  tested-engine: "4.15.0"
   updated: "2026-10-17"
 ---
 
 # Asciify Engine
 
-Use the published `asciify-engine` npm package. Tested against **4.14.2**. 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.15.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 · Backgrounds: https://asciify.org/backgrounds

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

@@ -36,26 +36,25 @@ copyButton.addEventListener('click', () => bg.pulse(copyButton));
 
 ## 2. Ink: quiet by default, colour only for meaning
 
-Inks come from theme tokens, defined for both schemes. The kit re-reads them when `prefers-color-scheme` changes and when `class` or `data-theme` changes on `<html>` or `<body>`, so define the dark values under both selectors. These are the engine's own fallbacks and the site's graphite:
+Inks come from the app's own design tokens, never from hex values you pick. Find the app's text, muted-text, background and status tokens first (CSS variables, a Tailwind theme, a tokens file) and derive the Asciify inks from them, so they follow every theme the app already has:
 
 ```css
 :root {
-  --ascii-ink: #76746e;        /* grounds, rings, quiet strokes */
-  --ascii-ink-strong: #1d1d1b; /* a component that is the focus */
-  --ascii-success: #17844a; --ascii-warning: #9a6700; --ascii-error: #c93636;
+  /* Map to the app's tokens; the names on the right are examples. */
+  --ascii-ink-strong: color-mix(in oklab, var(--foreground) 92%, var(--background)); /* a component that is the focus */
+  --ascii-ink: color-mix(in oklab, var(--foreground) 50%, var(--background));        /* grounds, rings, quiet strokes */
+  --ascii-success: var(--success); --ascii-warning: var(--warning); --ascii-error: var(--destructive);
 }
-@media (prefers-color-scheme: dark) {
-  :root:not([data-theme="light"]) { --ascii-ink: #7a7872; --ascii-ink-strong: #d8d6cf; --ascii-success: #3ccf7e; --ascii-warning: #f5b83d; --ascii-error: #ff6b6b; }
-}
-:root[data-theme="dark"] { --ascii-ink: #7a7872; --ascii-ink-strong: #d8d6cf; --ascii-success: #3ccf7e; --ascii-warning: #f5b83d; --ascii-error: #ff6b6b; }
 ```
 
+Because these derive from tokens the app already switches per theme, they need no dark-mode block of their own. The kit re-reads them when `prefers-color-scheme` changes and when `class` or `data-theme` changes on `<html>` or `<body>`. Left undefined, `--ascii-ink-strong` falls back to the component element's own text colour, and the status inks to the engine's greens, ambers and reds; define them anyway so nothing is guessed. Only when an app truly has no tokens, use the site's graphite: `#1d1d1b` and `#76746e` on light, `#d8d6cf` and `#7a7872` on dark.
+
 Rules:
 
 - **Default to graphite.** Leave `ink` unset: components pick `--ascii-ink` or `--ascii-ink-strong` and background presets use their graphite. On another brand, map these tokens to its muted text colour, never to its accent.
 - **Colour means something.** Green, amber and red are for outcomes only, and come from `--ascii-success`, `--ascii-warning` and `--ascii-error`. The site's phosphor marks live states only and is never a button or text.
 - **Palettes are deliberate.** `beam` `colorful`, `voiceOrb` `aurora` and `fieldBackground` `brand` are chosen palettes for one moment the user asked for, not a page default.
-- **Never a new colour.** No hex that is not a token, no black canvas on a light page, no white glow on a coloured image.
+- **Never a new colour.** No hex that is not a token (map to the app's tokens as above), no black canvas on a light page, no white glow on a coloured image.
 
 ```ts
 import { background, halftone, statusOrb, beam } from 'asciify-engine/kit';

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

@@ -517,8 +517,11 @@ export function asciiField(canvas: HTMLCanvasElement, options: GlyphFieldOptions
 ```
 
 ```css
-:root { --ascii-ink: #76746e; --ascii-ink-strong: #1d1d1b; }
-@media (prefers-color-scheme: dark) { :root { --ascii-ink: #7a7872; --ascii-ink-strong: #d8d6cf; } }
+/* From the app's own tokens (see applying-asciify.md); the names on the right are examples. */
+:root {
+  --ascii-ink: color-mix(in oklab, var(--foreground) 50%, var(--background));
+  --ascii-ink-strong: color-mix(in oklab, var(--foreground) 92%, var(--background));
+}
 ```
 
 In React, wrap it once and reuse it:

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

@@ -98,7 +98,7 @@ await fetchPost();
 await s.resolve();
 ```
 
-Options: `blocks` (selector, default `[data-block]`; `reset()` fades loaded content out under the returning skeleton), `shimmer` (ms per sweep, default 1250), `resolve` (ms per block, default 240), `stagger` (ms between blocks unless `data-delay` is set, default 60), `develop` (ms an image develops, default 560). Methods: `resolve()` (a promise for the last block), `reset()`; getter `loading`. Sets `aria-busy` on the element while loading.
+Options: `blocks` (selector, default `[data-block]`; `reset()` fades loaded content out under the returning skeleton), `shimmer` (ms per pass of a wave that loops without pausing until `resolve()`, default 1400), `resolve` (ms per block, default 420), `stagger` (ms between blocks unless `data-delay` is set, default 60), `develop` (ms an image develops, default 640). Block shapes come from the blocks' own CSS: an image's `border-radius`, and one bar per rendered line of text, as wide as the words and as tall as the font's x-height, so the skeleton follows the design's tokens without settings. Methods: `resolve()` (a promise for the last block), `reset()`; getter `loading`. Sets `aria-busy` on the element while loading.
 
 ## pill
 
@@ -175,7 +175,7 @@ const off = subscribeGlobalLook(look => menu.value = look?.charset ?? '');
 orb.update({ ink: '--brand', look: { cellSize: 6 } });
 ```
 
-`setGlobalLook({ charset })` applies to every glyph field, live or released, except dot marks, fields whose own `charset` holds letters (a word or a brand, such as `wordmark`), and fields created with `globalLook: false` (use it for a locked region). An empty `charset` keeps each field's own. `getGlobalLook()` reads the current look, so `subscribeGlobalLook` pairs with React's `useSyncExternalStore`.
+`setGlobalLook({ charset })` balances the set's weight against classic ASCII: block and solid sets draw smaller glyphs so they keep detail, sets without light glyphs (binary) ease off, and faint sets (minimal, braille, code) draw larger, bolder glyphs; tones are untouched. It applies to every glyph field, live or released, except dot marks, fields whose own `charset` holds letters (a word or a brand, such as `wordmark`), and fields created with `globalLook: false` (use it for a locked region). An empty `charset` keeps each field's own. `getGlobalLook()` reads the current look, so `subscribeGlobalLook` pairs with React's `useSyncExternalStore`.
 
 Each change sweeps: a field that has drawn its first frame holds that frame over itself and wipes it away left to right in 200ms (after a 40ms beat, `cubic-bezier(.23,1,.32,1)`), led by a 2px scan line, as the new characters land under it. The line is `--ascii-sweep` (default amber `#f3ba32`, at 35% with a soft glow); the held frame and the line are an `aria-hidden` canvas and span marked `data-ascii-sweep`, placed exactly over the field (style them alongside the field, for example with the same mask) and removed when the sweep ends. Under reduced motion (the visitor's, or `reducedMotion: true`), and for a field still on its poster, the characters change at once.