asciify-engine 4.7.0 → 4.9.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: "#E8B900"
-  default_prompt: "Use $asciify-engine to build a layered ASCII hero with readable HTML text, appropriate performance settings, and lifecycle cleanup."
+  brand_color: "#B3ED82"
+  default_prompt: "Use $asciify-engine to build interactive ASCII media or layered compositions, keeping HTML controls readable, rendering budgets explicit, and media lifecycles isolated."
 
 policy:
   allow_implicit_invocation: true

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

@@ -0,0 +1,89 @@
+# Layered projects — 4.8+
+
+Use `asciify-engine/studio` to combine up to eight images, videos, GIFs or FIGlet text sources on one canvas. Each layer has its own Studio settings, placement, opacity and blend mode. This is a local composition API. Keep accessible headlines, links and controls in HTML; raster text layers are artwork or export content.
+
+## Live component
+
+```ts
+import { mountStudioProject, normalizeStudioProject } from 'asciify-engine/studio';
+const project = normalizeStudioProject({
+  width: 1280, height: 720, background: '#0c1711',
+  layers: [
+    { id: 'scene', source: 'photo', name: 'Landscape', settings: {
+      cellSize: 6, ink: '#93b79b',
+      motion: { type: 'parallax', amount: .3, speed: .8 },
+      hover: { effect: 'trail', strength: .55, radius: .45 },
+    } },
+    { id: 'title', source: 'caption', name: 'Caption',
+      placement: { width: .8, height: .25 },
+      settings: { cellSize: 3, ink: '#b3ed82', hover: { effect: 'elastic' } },
+    },
+  ],
+});
+const sources = {
+  photo: '/your-owned-photo.webp', // or a user-selected File
+  caption: { text: 'HELLO', font: 'Small' as const },
+};
+const controller = new AbortController();
+const player = await mountStudioProject(canvas, project, sources, {
+  maxDimension: 1280, maxCells: 24000, maxRasterPixels: 2097152,
+  signal: controller.signal, onError: error => showError(error.message),
+});
+player.updateLayer('scene', { settings: { hover: { effect: 'water' } } });
+player.updateLayer('title', { placement: { y: .65 }, opacity: .8 });
+// On unmount: controller.abort(); player.destroy();
+```
+
+Do not attach `mountHover` or one RAF per layer. This player owns the combined loop, input, visibility/reduced-motion handling and loaded assets. Shared media is sampled once per frame; unchanged child canvases are cached. Ordinary settings edits do not reload assets. See the typed package example `examples/layered-composition.ts`.
+
+## Model and placement
+
+`kind: 'asciify-project'`, `version: 1`; dimensions are 2–4096 pixels per side. Empty projects are valid. Layer arrays run **back to front**. Layer IDs must be unique. IDs/source keys are 1–64 letters, numbers, colons, hyphens or underscores, starting with a letter or number; names are display labels up to 80 characters.
+
+Placement is center-based: `x/y` default `.5` (range −1…2), `width/height` default `1` (range .01…2), relative to the project canvas. Rotation is degrees −180…180; `flipX/flipY` default false. Use the layer's Studio `crop` and `warps` for source framing. Opacity is 0…1; `visible` defaults true; blending uses `BLEND_MODES`. Project background accepts a six-digit hex or `null`. Layers default to transparent backdrops; an explicit opaque layer backdrop covers artwork behind it.
+
+`pointerMode: 'top'` targets the frontmost interactive rectangle; `'all'` targets all rectangles beneath the pointer. Rotation/flips are inverted for input. Picking is rectangular, **not alpha/glyph hit testing**: transparent holes do not pass input through. Off/zero-strength layers are skipped.
+
+Every layer accepts the complete `StudioInput`: all 18 styles, dither, masks, curves, source warps, hover, ambient motion and finishing. Use the published catalogs; source warps, motion and hover are independent.
+
+## Assets and lifecycle
+
+`StudioProjectSources` maps keys to `File`, direct CORS-compatible media URLs or `{text, font?, ink?}`. Text uses `STUDIO_TEXT_FONTS`, defaults to white on transparency and can be recolored by layer settings. YouTube page URLs are not media URLs.
+
+Up to eight bindings are loaded, including unused supplied bindings. Every referenced source, even on a hidden layer, must be supplied. Multiple layers can share one key. To add/replace a binding, destroy the old player and mount the new dictionary. Reordering, visibility, placement and settings use `player.update(project)` or `updateLayer` without media reload. Remove unused bindings when remounting. Files stay local; URLs still make normal media requests.
+
+`mountStudioProjectMedia` accepts a `ReadonlyMap<string, StudioMedia>` and takes ownership on successful setup. It destroys each unique asset once. If setup fails before returning, the caller retains cleanup responsibility for supplied media. `mountStudioProject` cleans up its own failed loads. Never give the same owned media instance to two players or export.
+
+`createStudioProjectRenderer` is the lower-level alternative: no media loading, RAF or events. Supply a `ReadonlyMap<string, StudioSource>` to `render`, and `invalidate(key)` when external code changes pixels in place. Video frame stamps invalidate automatically. `render` returns whether it repainted; `configure` replaces the project. Always destroy it.
+
+The player exposes `pause`, `seek`, `resize(width,height,pixelRatio?)`, `redraw`, `setBudget`, `setAdaptive`, `update`, `updateLayer` and idempotent `destroy`. Read detached `project` and `motionTimes` snapshots and current `time`. New seeks cancel older ones with `AbortError`; custom media `seek` must honor its AbortSignal. Native videos use independent browser playback, not frame-locked live playback. Export seeks each source deterministically.
+
+## Budgets and timing
+
+One cell budget (default 24,000; range 2,048–1,048,576) is divided by layer area, with a 256-cell minimum per visible layer. One **child-output raster** budget (default 4,194,304; range 65,536–16,777,216 pixels) caps combined child output size. It does not cap decoders or all internal surfaces. Hidden, transparent and offscreen layers skip rendering; loaded assets can still occupy memory. Their native videos pause.
+
+`quality` reports per-layer `{id,maxCells,width,height}` allocations, not achieved FPS. Adaptive mode lowers the total cell budget after sustained render cost. `maxDimension` bounds root output; `pixelRatio` describes requested raster scale and preserves logical density through downsampling. Stills stop scheduling when unchanged; motion/hover wakes them. Reduced motion, hidden documents and offscreen canvases pause playback. Multiple optical finishes or dense dither still have real cost; measure target hardware.
+
+Do not promise seamless combined loops unless source lengths and effect periods align. Ambient cycles last 12/speed seconds; temporal grain, dust, glitch, dither and media have separate timing.
+
+## Save and reopen
+
+`serializeStudioProject(player.project)` saves settings/source keys, never files or URLs. `parseStudioProject` validates kind/version, unique IDs and the eight-layer limit, with a 1 MB settings-text limit. Single-source `serializeStudioSettings` JSON is a different format. Maintain a separate asset manifest and ask for missing files; do not substitute artwork silently.
+
+Asciify's layered editor adds optional `textSources` metadata so text is portable. The engine parser ignores app metadata. Integrations must validate/rebind that dictionary themselves or supply their own bindings. Never execute imported fields or fetch arbitrary metadata URLs.
+
+## Export independently
+
+```ts
+import { exportStudioProject } from 'asciify-engine/studio';
+const png = await exportStudioProject(player.project, sources, {
+  format: 'png', width: 1280, height: 720,
+  referenceWidth: canvas.width / player.pixelRatio,
+  maxCells: player.maxCells, time: player.time, motionTimes: player.motionTimes,
+  signal: exportController.signal,
+});
+```
+
+Export freezes the project/bindings/phases and loads independent media. It never seeks, pauses or destroys the preview. Visible shared sources seek once per frame. Failure/cancellation aborts sibling seeks and releases all export resources. PNG/JPEG capture specified time/phases; GIF/MP4/WebM start at zero and do not record pointer paths. Generic Studio export size/codec/GIF limits apply. WebGL-only finishes error if unavailable. Actual GPU appearance and codec playback require browser verification.
+
+Update the runtime and installed agent skill separately: [upgrading.md](upgrading.md).

package/skills/asciify-engine/references/print-styles.md

@@ -0,0 +1,63 @@
+# Print and illustration (4.9)
+
+Six local Canvas renderers live in the optional `asciify-engine/studio` entry. They do not change the default ASCII style or add a server/provider. They share source grading, curves, warps, masks, hover, still-image motion, finishing, saved settings, single-image export and layered projects.
+
+| Style ID | Mechanism | Useful controls |
+| --- | --- | --- |
+| `stipple` | Four spatially jittered dots per sample; tone changes their area | Coverage, weight, texture, seed |
+| `engraving` | Parallel world-anchored cuts with tone-dependent width | Coverage, weight, angle, texture |
+| `crosshatch` | Up to three crossing screens appear across the tonal range | Coverage, weight, angle, texture |
+| `woodblock` | Five tone steps in broad carved bands with correlated irregular edges | Coverage, weight, angle, texture |
+| `risograph` | Two overlapping ink-dot screens; source warmth separates coverage in source-color mode | Second ink, registration offset/direction, texture |
+| `pointillism` | Four small elliptical pigment strokes per sample | Source color, weight, texture, seed |
+
+`STUDIO_PRINT_STYLES` supplies `value`, `label`, and `description` for selectors. `isStudioPrintStyle(style)` identifies this family. The full `STUDIO_STYLES` catalog has 24 styles. Existing `riso` and `print` look IDs remain dither presets; choose `style: 'risograph'` to use the new two-screen renderer. These are print-inspired raster treatments, not physical ink simulation, CMYK separations or vector paths.
+
+## Live still image
+
+```ts
+import { mountStudio } from 'asciify-engine/studio';
+
+const player = await mountStudio(canvas, '/your-image.jpg', {
+  settings: {
+    style: 'engraving', cellSize: 7, colorMode: 'accent', ink: '#becbbe',
+    print: { angle: -35, weight: 1.1, roughness: .3 },
+    backdrop: { color: '#101810' },
+    motion: { type: 'sheen', speed: .5, amount: .4 },
+    hover: { effect: 'water', radius: .4, strength: .5 },
+  },
+  maxDimension: 960, maxCells: 12000,
+  onError: console.error,
+});
+player.update({ print: { angle: 20 } }); // retains the other print settings
+const settings = player.settings;       // detached snapshot for saving/export
+// On unmount:
+player.destroy();
+```
+
+For dark ink on paper, use `print.invert: true`, a dark `ink`, and a light `backdrop.color`. Inversion chooses which source tones receive ink; it does not change the ink or backdrop automatically. Dissolve reduces ink in either polarity. Trail still inverts the local tonal response. The motion engine retains its own `12 / speed` cycle; the print texture has no independent time source.
+
+## Exact settings
+
+`print` is an optional nested group in `StudioInput` and saved version-1 `StudioSettings`. Old files receive compatible defaults. Partial updates merge this group. `normalizeStudioPrint`, `DEFAULT_STUDIO_PRINT`, and `StudioPrintSettings` are exported from `/studio`.
+
+| Field | Range / default | Meaning |
+| --- | --- | --- |
+| `density` | 0–2 / 1 | Tonal coverage; zero draws no print marks |
+| `weight` | .25–2 / 1 | Dot/stroke size; size is bounded within the screen |
+| `angle` | −180–180° / −35 | Line angle for engraving/crosshatch/woodblock; registration direction for risograph |
+| `roughness` | 0–1 / .35 | Spatial texture variation; not random animation |
+| `invert` | boolean / false | False draws highlights; true draws shadows |
+| `secondaryInk` | six-digit hex / `#ec6752` | Second risograph ink only |
+| `registration` | 0–1 / .2 | Risograph offset, up to .38 of one cell |
+| `seed` | integer 0–65535 / 7 | Repeatable spatial texture |
+
+All print styles use square sampling cells. `cellSize` accepts 1–60 in the reference frame; `studioGrid` still reports any effective budget limit. It is independent of `dither.scale`. Source color and gray modes remain available. Only Pointillism's source-color mode separates pigment hues; accent mode retains the chosen ink. Risograph mixes its two screens on transparent artwork with multiply, then composes that artwork over the chosen backdrop.
+
+## Work and quality limits
+
+Compiled screen directions and texture buffers are reused. No per-cell canvas, save/rotate/clip, or new simulation loop is created. A stable still caches the complete composition. Spatial texture uses a deterministic seed and bounded lookup; source tone changes can still change coverage. Woodblock intentionally has stepped tones. Do not label it smooth continuous shading.
+
+Dense live print rendering costs more than the sample count alone: Pointillism draws four strokes per cell, Crosshatch up to three screens, and Woodblock emits carved polygons. Start with 12,000 cells, retain adaptive quality for motion, and measure the real device. High-resolution still exports can use a larger explicit budget. Keep the same reference pixel ratio/grid for preview and export.
+
+The regression suite checks geometry, normalization, scaling, deterministic texture, composition caching and every hover/motion path. CPU geometry timings exclude actual Canvas drawing, decoding, GPU work and browser frame pacing. Visual output, browser export and mobile frame-rate acceptance are still unverified; do not claim competitor parity or guaranteed FPS from these tests.

package/skills/asciify-engine/references/project-integration.md

@@ -7,6 +7,7 @@ A downloaded PNG is one output; it is not a substitute for a live component.
 | --- | --- | --- |
 | Image/video/GIF hero with HTML titles and text cutouts | `/core` media API + optional `/hover` | Disable core hover/motion when `/hover` owns them. |
 | Art-style editor, live still image, saved look, backdrop, masks, PNG/video export | `/studio` → `mountStudio` | Studio owns motion, hover and finishing. Do not stack `mountHover` on it. |
+| Multiple media/text layers with independent styles, placement, blends and exports | `/studio` → `mountStudioProject` (4.8+) | One shared loop and budget; see [layered-projects.md](layered-projects.md). |
 | Application-owned render loop | `/studio` → `createStudioRenderer` | Caller passes time, pointer input, invalidation and cleanup. |
 | ASCII text data | Core frame/text conversion | No animation loop needed unless requested. |
 

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

@@ -25,7 +25,7 @@ await studio.seek(1.5);
 studio.destroy();
 ```
 
-Keep complete settings in application state. Apply edits with `updateStudioSettings(settings, patch)` and pass that state to `studio.update`; the mounted instance does not expose a settings getter. Serialize your application state when saving a look.
+Keep complete settings in application state. Apply edits with `updateStudioSettings(settings, patch)` and pass that state to `studio.update`; from 4.6 the mounted instance also exposes a detached `settings` snapshot. Serialize that snapshot or your application state when saving a look.
 
 In React, create the AbortController inside the effect. On cleanup, abort and destroy the returned instance; if setup resolves after disposal, immediately destroy that instance. Do not remount for slider changes: call `update`. The mount owns its loaded media. `mountStudioMedia` takes ownership of an already loaded `StudioMedia`. Use an independent media instance for export.
 
@@ -190,7 +190,7 @@ Example: `player.update({ motion: { type: 'trace', speed: 1, amount: .7 }, hover
 
 Use `color.gamma` to lift midtones (above 1) or deepen them (below 1), from 0.25 to 4. `color.shadows` and `color.highlights` range from −1 to 1; positive lifts that region, negative darkens it. They form a monotone curve with fixed black, middle and white anchors. This is a bounded tonal curve, not a freely editable per-channel curve graph. It cannot recover clipped source detail.
 
-`color.blackPoint` (0–0.99, default 0) and `color.whitePoint` (default 1) map the input range before gamma. White is normalized to at least 1/255 above black. These controls apply equally to all 18 renderers before dither/character conversion, preserve source alpha, and round-trip in settings. Neutral settings skip the transform. The 256-entry lookup is rebuilt on configuration changes and reused for source frames. Reset with `{ blackPoint: 0, whitePoint: 1, gamma: 1, shadows: 0, highlights: 0 }`.
+`color.blackPoint` (0–0.99, default 0) and `color.whitePoint` (default 1) map the input range before gamma. White is normalized to at least 1/255 above black. These controls apply equally to all Studio renderers before dither/character conversion, preserve source alpha, and round-trip in settings. Neutral settings skip the transform. The 256-entry lookup is rebuilt on configuration changes and reused for source frames. Reset with `{ blackPoint: 0, whitePoint: 1, gamma: 1, shadows: 0, highlights: 0 }`.
 
 `blue-noise` uses a deterministic 64×64 toroidal rank tile generated offline with void-and-cluster relaxation. It suppresses low-frequency clumping; it is not white noise with a different label. A palette-pair projection controls coverage, preserving flat grayscale means for a black/white palette at full strength. Arbitrary color palettes still approximate the source. The original palette uses web-safe channel quantization. The rank tile is 8 KiB in memory, loads only with `/studio`, and has no network request or runtime generator.
 
@@ -243,3 +243,7 @@ const saved = serializeStudioSettings(player.settings);
 ## Ordered source shaping (4.7)
 
 `warps` stores up to eight optional transforms applied in array order before all styles. `warpEdge` selects extended or transparent edges. Read [source shaping](source-shaping.md) for the nine mechanisms, controls, normalization, editor construction and dense-video cost. This is separate from art-style selection, pointer response and autonomous motion. The default stack is empty.
+
+## Print and illustration (4.9)
+
+The catalog adds six print treatments with fine square cells and an optional `print` settings group. See [print-styles.md](print-styles.md) for the mechanisms, controls, polarity, bounded rendering and living-image example. They use the same Studio pipeline, saved settings and exports.

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

@@ -73,3 +73,11 @@ Adds Studio `color.curves` and `color.denoise` with neutral defaults. Curves sup
 ### 4.7 ordered source warps
 
 Adds optional Studio `warps` and `warpEdge` with an empty default stack. Nine transform types are exposed through `STUDIO_WARPS`, plus `MAX_STUDIO_WARPS` and `normalizeStudioWarps` for control builders. Updating `warps` replaces the array. Reuse `player.settings` for save/export. Static shaping does not enable motion; existing motion and hover remain independent. Dither now interpolates alpha with color during motion/hover. Settings version stays 1, root/core/hover behavior remains unchanged, and older packages ignore the new fields. See [source shaping](source-shaping.md); update the runtime and installed skill separately.
+
+### 4.8 layered projects
+
+Adds `mountStudioProject`, `mountStudioProjectMedia`, `createStudioProjectRenderer`, `exportStudioProject` and the typed project model in optional `/studio`. Up to eight independently styled media/text layers share a playback loop and cell/raster budgets. Existing single-source APIs/defaults remain. Layered project JSON uses a distinct `kind` and source keys; it is not interchangeable with single-source settings JSON and does not contain media. See [layered-projects.md](layered-projects.md) for ownership, pointer routing, export consistency and migration choices. Refresh this skill separately from npm; do not migrate simple heroes unnecessarily.
+
+## 4.9 print rendering
+
+Six additional `STUDIO_STYLES` use optional `print` settings. Existing v1 settings remain valid and ASCII defaults stay unchanged. The print group merges on partial updates. Import the shared catalog and read [print-styles.md](print-styles.md); offer print-specific controls only for those styles. Existing `print` and `riso` look IDs retain their dither behavior. Refresh the npm dependency and installed skill separately.