asciify-engine 1.0.118 → 1.2.0

package/skills/asciify-engine/agents/openai.yaml

@@ -1,8 +1,8 @@
 interface:
   display_name: "Asciify Engine"
   short_description: "Build fast ASCII media effects"
-  brand_color: "#D4FF00"
-  default_prompt: "Use $asciify-engine to build a smooth ASCII video hero with good performance settings."
+  brand_color: "#E8B900"
+  default_prompt: "Use $asciify-engine to build a layered ASCII hero with readable HTML text, appropriate performance settings, and lifecycle cleanup."
 
 policy:
   allow_implicit_invocation: true

package/skills/asciify-engine/examples/layered-hero.css

@@ -0,0 +1,30 @@
+:root { color-scheme: dark; font-family: system-ui, sans-serif; background: #080808; color: #e0e0e0; }
+* { box-sizing: border-box; }
+body { margin: 0; }
+.ascii-hero {
+  position: relative; isolation: isolate; overflow: hidden;
+  min-height: 44rem; height: 100svh; background: #080808;
+  display: grid; grid-template-columns: 1.6fr 1fr; align-items: end;
+  gap: 8%; padding: 6rem 5% 5rem;
+}
+/* These are siblings: no shared content wrapper traps the CTA under the canvas. */
+.hero-title { position: relative; z-index: 0; margin: 0; font-size: clamp(4rem, 9vw, 9rem); line-height: .95; letter-spacing: -.055em; color: #e8b900; }
+.hero-art { position: absolute; inset: 0; z-index: 1; width: 100%; height: 100%; object-fit: cover; pointer-events: none; background: transparent; opacity: .65; }
+.hero-entry { position: relative; z-index: 2; max-width: 24rem; line-height: 1.7; }
+.hero-entry p { text-shadow: 0 1px 4px #000, 0 0 10px #000, 0 0 24px #000; }
+.hero-entry a, .hero-controls button { display: inline-flex; align-items: center; justify-content: center; min-height: 44px; padding: .8rem 1.2rem; border: 1px solid #e8b900; border-radius: .75rem; font: inherit; text-decoration: none; cursor: pointer; }
+.hero-entry a { background: #e8b900; color: #111; }
+.hero-controls { position: absolute; z-index: 3; top: 1.5rem; right: 5%; display: flex; gap: .75rem; align-items: center; font-size: .8rem; }
+.hero-controls button { background: #101010; color: #e0e0e0; border-color: #555; }
+.hero-controls button:disabled { cursor: default; opacity: .7; }
+.hero-controls [data-status] { max-width: 15rem; background: #080808; }
+:is(a, button):focus-visible { outline: 3px solid #fff; outline-offset: 5px; }
+/* Optional conventional hierarchy: all text above the artwork. */
+.ascii-hero.text-in-front .hero-title { z-index: 2; }
+#start { min-height: 40vh; padding: 3rem 5%; }
+@media (max-width: 650px) {
+  .ascii-hero { grid-template-columns: 1fr; align-content: end; height: auto; min-height: 100svh; padding: 20rem 6% 3rem; gap: 2rem; }
+  .hero-title { font-size: clamp(3.5rem, 15vw, 6rem); }
+  .hero-entry { max-width: 26rem; }
+  .hero-controls { right: 6%; left: 6%; flex-wrap: wrap; }
+}

package/skills/asciify-engine/examples/layered-hero.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Layered ASCII hero</title>
+  <link rel="stylesheet" href="./layered-hero.css">
+</head>
+<body>
+  <!-- Replace these two URLs with your own optimized media. -->
+  <section class="ascii-hero" data-video="/hero.mp4" data-poster="/hero-poster.jpg" data-render-limit="720" aria-labelledby="hero-title">
+    <h1 id="hero-title" class="hero-title">More than<br>characters.</h1>
+    <canvas class="hero-art" aria-hidden="true"></canvas>
+    <div class="hero-entry">
+      <p>Turn your images and motion into living characters.</p>
+      <a href="#start">Start creating</a>
+    </div>
+    <div class="hero-controls">
+      <button type="button" data-motion disabled>Loading artwork…</button>
+      <span data-status role="status"></span>
+    </div>
+  </section>
+  <main id="start" tabindex="-1"><h2>Your next section</h2></main>
+  <script type="module">
+    import { mountLayeredHero } from './layered-hero.js';
+    const destroy = mountLayeredHero(document.querySelector('.ascii-hero'));
+    // In an SPA, call destroy() when this view unmounts.
+    if (import.meta.hot) import.meta.hot.dispose(destroy);
+  </script>
+</body>
+</html>

package/skills/asciify-engine/examples/layered-hero.js

@@ -0,0 +1,78 @@
+import { asciify, asciifyVideo } from 'asciify-engine';
+
+/** Client-side example. Supply data-video and data-poster on the hero element.
+ * @param {HTMLElement} hero
+ */
+export function mountLayeredHero(hero) {
+  const canvas = hero.querySelector('canvas');
+  const button = hero.querySelector('button[data-motion]');
+  const status = hero.querySelector('[data-status]');
+  if (!(button instanceof HTMLButtonElement) || !canvas || !status) throw new Error('Layered hero requires its canvas, motion button, and status element.');
+  const reduced = matchMedia('(prefers-reduced-motion: reduce)');
+  /** @type {Partial<import('asciify-engine').AsciiOptions>} */
+  const mediaOptions = { charset: ' .:-=+*#%@', colorMode: 'fullcolor', normalize: false, animationStyle: 'none', hoverStrength: 0 };
+  let disposed = false, stop, video, visible = false, userPaused = false;
+  let loading = false, started = false, failed = false, revision = 0;
+
+  const wantsMotion = () => !disposed && visible && !document.hidden && !reduced.matches && !userPaused;
+  const label = () => {
+    button.disabled = reduced.matches || failed || !video;
+    button.textContent = reduced.matches ? 'Motion off' : failed ? 'Still preview' : !video ? 'Loading artwork…' : userPaused || video.paused ? 'Play motion' : 'Pause motion';
+  };
+  const release = () => { stop?.(); stop = undefined; video?.pause(); video = undefined; };
+
+  async function start() {
+    if (loading || started || failed || !wantsMotion()) return;
+    loading = true; started = true;
+    const version = ++revision;
+    try {
+      const cleanup = await asciifyVideo(hero.dataset.video, canvas, {
+        fitTo: hero, objectFit: 'cover', objectPosition: 'center',
+        fontSize: 7, fps: 24, maxRenderDimension: Number(hero.dataset.renderLimit) || 720, options: mediaOptions,
+        onReady: readyVideo => {
+          if (disposed || version !== revision) { readyVideo.pause(); return; }
+          video = readyVideo;
+          if (!wantsMotion()) video.pause();
+          label();
+        },
+      });
+      if (disposed || version !== revision) cleanup();
+      else { stop = cleanup; if (!wantsMotion()) video?.pause(); }
+    } catch {
+      if (!disposed && version === revision) { failed = true; status.textContent = 'Motion unavailable. The artwork remains a still preview.'; }
+    } finally {
+      if (version === revision) { loading = false; label(); }
+    }
+  }
+  async function sync() {
+    if (disposed) return;
+    if (!wantsMotion()) video?.pause();
+    else if (video) {
+      try { await video.play(); }
+      catch { if (!disposed) { userPaused = true; status.textContent = 'Press Play motion to start.'; } }
+    } else await start();
+    if (!disposed) label();
+  }
+  // Keep explicit user pause separate from temporary offscreen/tab suspension.
+  const onClick = () => { userPaused = video ? !video.paused : false; status.textContent = ''; void sync(); };
+  button.addEventListener('click', onClick);
+  document.addEventListener('visibilitychange', sync);
+  reduced.addEventListener('change', sync);
+  const observer = new IntersectionObserver(([entry]) => { visible = entry.isIntersecting; void sync(); }, { threshold: .05 });
+
+  // Paint a small still first. Reduced motion does not request the video URL.
+  void asciify(hero.dataset.poster, canvas, { fontSize: 7, options: mediaOptions }).then(cleanup => {
+    if (disposed) { if (typeof cleanup === 'function') cleanup(); return; }
+    if (typeof cleanup === 'function') cleanup(); // This example uses a static poster.
+    observer.observe(hero); label();
+  }).catch(() => {
+    if (!disposed) { status.textContent = 'Still preview unavailable.'; observer.observe(hero); label(); }
+  });
+
+  return () => {
+    disposed = true; revision++; release(); observer.disconnect();
+    button.removeEventListener('click', onClick);
+    document.removeEventListener('visibilitychange', sync);
+    reduced.removeEventListener('change', sync);
+  };
+}

package/skills/asciify-engine/references/layered-hero.md

@@ -0,0 +1,45 @@
+# Layer HTML text through ASCII artwork
+
+Use the companion [HTML](../examples/layered-hero.html), [CSS](../examples/layered-hero.css), and [JavaScript](../examples/layered-hero.js) in a browser app with `asciify-engine@1.2.0` installed. Rename the HTML to `index.html` in a Vite project, and provide `/hero.mp4` plus `/hero-poster.jpg` or change its data attributes. The example starts with `data-render-limit="720"`; set this no larger than the source video's longer dimension. No Asciify site footage or fonts are included.
+
+The script renders a poster before requesting video, respects initial reduced motion, pauses offscreen/hidden video, provides a keyboard-operable Play/Pause button, and returns cleanup synchronously while guarding asynchronous setup. Call it on mount and call its returned function on unmount. It uses the public package without the site's patched renderer or private hero sampler.
+
+## The layer order
+
+```html
+<section class="ascii-hero">
+  <h1 class="hero-title">Your headline</h1>
+  <canvas class="hero-art" aria-hidden="true"></canvas>
+  <div class="hero-entry">Description and real links</div>
+  <div class="hero-controls">Real buttons</div>
+</section>
+```
+
+```css
+.ascii-hero { position: relative; isolation: isolate; overflow: hidden; }
+.hero-title { position: relative; z-index: 0; }
+.hero-art { position: absolute; z-index: 1; pointer-events: none; background: transparent; }
+.hero-entry { position: relative; z-index: 2; }
+.hero-controls { position: absolute; z-index: 3; }
+```
+
+The transparent gaps between glyphs reveal the headline below. The description and controls stay above the artwork. This is the cover relationship on Asciify; it does not rasterize the headline or make its wording part of the charset.
+
+Do not wrap the headline and CTA together in a parent with `transform`, `filter`, `opacity < 1`, `isolation`, or a positioned `z-index`. That creates a separate stacking context: a high `z-index` on the CTA cannot escape its parent's lower layer. Keep the three semantic layers as siblings, or explicitly split their wrappers into those levels.
+
+Do not paint a solid rectangle behind the ASCII glyphs. A black stage/canvas at z-index 1 would cover the lower headline completely. The section owns the background color; the drawing surface stays transparent. If building a custom renderer, clear the full drawing surface before each frame rather than fading old frames, which can leave unwanted trails.
+
+## Readability and input
+
+- Keep the headline as an `h1` with real text. Decorative canvases use `aria-hidden="true"`.
+- Keep descriptions and buttons above the ASCII. Use localized text shadow or a restrained scrim where required; do not depend on one favorable video frame for contrast.
+- Choose the headline color independently from `options.colorMode`—a yellow HTML title can coexist with full-color or gray ASCII.
+- `pointer-events: none` lets users select text and click controls through the decoration. For optional studio hover, listen on the hero host, not the decorative canvas; the module ignores interactive control targets.
+- If the headline becomes hard to read, reduce artwork opacity or add the example's `text-in-front` class to put the title at z-index 2. Keep this choice driven by the content and the user's design.
+- The media remains a cover crop on narrow screens. Check the subject's position there; moving HTML layers does not fix source framing.
+
+## Performance boundary
+
+This example shows portable layering and lifecycle with the published package. It does not claim the exact GPU performance or custom interactions of the Asciify production hero. Match the website's enhanced hover behavior only by intentionally adding the [optional studio module](studio-effects.md). That module adds a canvas and must occupy the same artwork layer, not cover the controls.
+
+For additional custom text in the artwork, change `options.charset` while retaining its tonal symbols. Keep the headline itself in HTML so it remains readable, searchable, selectable, and accessible.

package/skills/asciify-engine/references/media-api.md

@@ -0,0 +1,109 @@
+# Media API notes — published 1.2.0
+
+Use installed package types as the authority for exact signatures. Import from `asciify-engine`.
+
+## Crop and layout
+
+`options.sourceCrop` chooses the source pixels before conversion. Side insets use fractions from 0 to 1 by default:
+
+```js
+options: { sourceCrop: { top: 0.08, right: 0.1, bottom: 0.16, left: 0.1 } }
+```
+
+Side insets define a new crop aspect. A single `width` or `height` crop derives the other dimension with `preserveAspect` by default. Use `{ unit: 'pixel', x, y, width, height }` for exact source coordinates.
+
+`fitTo`, `objectFit`, `objectPosition`, `width`, `height`, `scale`, and `bleed` position the rendered canvas. Prefer `objectFit: 'cover'` for a full hero and `contain` for a complete subject. Keep the source aspect intact; `fill` can distort it. A small `bleed: { x: '1vw' }` can cover glyph side-bearing gaps, but do not use large oversizing to compensate for inappropriate footage.
+
+Chroma key is optional. Use it only on footage with a removable background:
+
+```js
+options: {
+  chromaKey: true,
+  chromaKeyTolerance: 60,
+  chromaKeyTrimMode: 'range',
+  chromaKeyTrimPadding: 0.002,
+}
+```
+
+`range` keeps framing stable over video. `frame` remeasures the foreground each frame and can visibly change scale; choose it intentionally for edge-tight scrubbing. Test key tolerance and trim thresholds on the actual subject. Keying is not a solution for a dark, underlit subject.
+
+## Static image and compact frames
+
+```js
+import { asciify } from 'asciify-engine';
+const cleanup = await asciify('/photo.jpg', canvas, {
+  fontSize: 7,
+  options: { colorMode: 'fullcolor', charset: ' .:-=+*#%@' },
+});
+// On unmount:
+if (typeof cleanup === 'function') cleanup();
+```
+
+For custom loops, convert and render with the **same options**:
+
+```js
+import { DEFAULT_OPTIONS, imageToAsciiTextFrame, renderTextFrameToCanvas } from 'asciify-engine';
+const options = { ...DEFAULT_OPTIONS, fontSize: 7, colorMode: 'fullcolor' };
+const frame = imageToAsciiTextFrame(image, options, 960, 540);
+renderTextFrameToCanvas(context, frame, options, 960, 540);
+```
+
+`AsciiTextFrame` uses row strings, dimensions, and an optional packed color buffer; do not substitute it for the object-cell `AsciiFrame` expected by `renderFrameToCanvas`.
+
+## React and Next.js
+
+Initialize browser APIs in an effect; use `'use client'` where needed. Keep settings stable. This pattern handles a late initialization after unmount:
+
+```jsx
+useEffect(() => {
+  let disposed = false;
+  let stop;
+  asciifyVideo(src, canvasRef.current, {
+    fitTo: heroRef.current,
+    objectFit: 'cover',
+    fontSize: 7,
+    fps: 24,
+    maxRenderDimension: 960,
+    options: { colorMode: 'fullcolor', hoverStrength: 0, animationStyle: 'none' },
+  }).then(cleanup => {
+    if (disposed) cleanup();
+    else stop = cleanup;
+  }).catch(error => {
+    if (!disposed) setError(error.message);
+  });
+  return () => { disposed = true; stop?.(); };
+}, [src]);
+```
+
+This is lifecycle wiring, not a complete accessibility implementation. For visibility, reduced motion, a still fallback, and text layers, adapt the companion layered-hero example. Do not expose server credentials in client components.
+
+## Scroll-synced video
+
+Use the API's scroll mapping rather than racing it with a second `currentTime` loop:
+
+```js
+const stop = await asciifyVideo('/hero.mp4', canvas, {
+  fitTo: hero,
+  objectFit: 'cover',
+  fontSize: 7,
+  maxRenderDimension: 960,
+  trim: { start: 1, end: 5 },
+  scroll: { trigger: hero, from: 1, to: 5 },
+  options: { animationStyle: 'none', hoverStrength: 0 },
+});
+```
+
+For GSAP, pass your installed `gsap` and `ScrollTrigger` instances through `scroll`, alongside `trigger`, `start`, `end`, and `scrub`. `scroll.speed` changes progress mapping, not the source frame rate. `maxCachedFrames` bounds the lazy frame cache. Test rapid direction changes and actual memory use before raising it.
+
+## Procedural backgrounds
+
+```js
+import { asciiBackground } from 'asciify-engine';
+const background = asciiBackground(host, {
+  type: 'aurora', fontSize: 14, speed: 0.8, density: 0.55,
+});
+// On unmount:
+background.destroy();
+```
+
+The published background types are wave, rain, stars, pulse, noise, grid, aurora, silk, void, morph, fire, dna, terrain, and circuit. The website's fluid scene is separate application code; it is not a `type: 'fluid'` option in this package version.

package/skills/asciify-engine/references/studio-effects.md

@@ -0,0 +1,57 @@
+# Optional studio surface effects
+
+Use this only when the requested behavior should match the Asciify website's enhanced interactions or living-image treatments. It ships with `asciify-engine@1.2.0` and later as an optional entry point. Root and `/core` imports do not load its code.
+
+Install `npm install asciify-engine`, then import from `asciify-engine/hover`. No extra package or file download is required. For a project without a bundler, the standalone ES module remains available at https://asciify.org/background-sources/studio-hover.js; save it locally and import `mountHover` from that file. Prefer npm for versioned updates and TypeScript types.
+
+After the engine has rendered the source canvas:
+
+```js
+import { mountHover } from 'asciify-engine/hover';
+const surface = mountHover(host, canvas, {
+  effect: 'trail',
+  strength: 0.55,
+  radius: 0.2,
+  animated: true, // false for a still; true for video or GIF
+  fps: 24,
+  fontSize: 7,
+  charAspect: 0.58,
+  charset: ' .:-=+*#%@',
+});
+// After replacing a still: surface.invalidate();
+// Pause surface updates together with the backing video:
+// surface.update({ paused: true });
+// On unmount: surface.destroy(); then stop the engine renderer.
+```
+
+Keep engine `options.hoverStrength: 0` and `animationStyle: 'none'`. Pass the same charset, font size, aspect, charSpacing, dots mode, and custom text used to draw the backing canvas. `animated: true` refreshes the rendered source; it does not play the video itself.
+
+The positioned host must fit the displayed source canvas. The surface appends a visible overlay canvas and keeps the source for sampling. If using the layered hero, assign the overlay the same artwork stacking level as the source. Do not put the description or links inside a lower stacking context. When a `cover` canvas extends beyond its host, crop it with `overflow: hidden` and check pointer alignment at both edges.
+
+## Hover choices
+
+| Module `effect` | Behavior |
+| --- | --- |
+| `trail` | Density wake with a fading tail; glyph grid remains fixed. |
+| `water` | Local refraction with aligned outer boundaries. |
+| `contour` | Expanding ring echoes along the pointer path. |
+| `dissolve` | Fading/reforming density trace with a lingering tail. |
+| `silk` | Directional folds following the stroke. |
+| `vortex` | Local rotational wake. |
+| `none` | No hover effect. |
+
+These are `/hover` module `effect` IDs, not the root engine’s legacy `HoverEffect` values. For example, passing `hoverEffect: 'water'` to the published engine is invalid.
+
+## Still-image motion and dither
+
+The module's `motion` IDs are `none`, `print` (Living Print), `current` (Slow Current), and `reform` (Reveal & Reform). Keep source-video motion alone unless the user intentionally wants another animation layered onto it. For a still, select one motion and a restrained `motionSpeed`, rather than stacking effects.
+
+For the website's fine-dither treatment, use the module's `fineDither: true` and `ditherStrength` after matching the backing canvas's character settings. This is separate from the core renderer’s built-in dither behavior. Check a still and a moving scene for flicker before choosing the default.
+
+The module observes reduced motion and visibility. Coordinate explicit pause with the underlying media; destroy both on unmount. Verify performance on the actual target device, especially with full-screen dense color video.
+
+## Updates and cleanup
+
+`surface.update({ effect: 'water' })` replaces the effect and clears the previous wake. `surface.invalidate()` uploads a newly drawn still. `surface.canvas` is the visible overlay, useful for layering or snapshots; the supplied canvas remains the source. `surface.destroy()` removes the overlay, listeners and observers and restores the source visibility. Stop the source renderer separately. Reduced motion disables hover and ambient motion; offscreen and hidden surfaces stop scheduling frames. Canvas 2D fallback preserves artwork when WebGL is unavailable, with simpler spatial refraction.
+
+When using the low-level object-frame API, pass `getFrame: () => currentFrame` to preserve exact glyph identities and colors. With canvas-only integrations the module estimates density from sampled ink coverage.