@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/skills/media-use/references/media-treatment-recipes.md

@@ -0,0 +1,929 @@
+# Media treatment recipes
+
+These are optional tested seeds, not the complete capability surface. Read the
+shared policy and choose one relevant section through `media-treatments.md`.
+Agents may modify or combine a seed with compatible canonical controls after
+inspecting the media, or assemble a bespoke payload from
+`hyperframes media-treatment --capabilities --json` when no seed fits.
+
+## Natural Portrait
+
+Use for a talking head, interview, presenter, or people-focused photo whose
+intended result is natural, polished, and restrained.
+
+Do not use when the face is incidental or tiny, the source is intentionally
+neon/monochrome/strongly stylized, or the requested result is beauty retouching.
+This treatment changes the whole frame; it is not a face mask or skin-smoothing
+effect.
+
+Inspect face exposure, highlight retention, shadow detail, white balance, and
+whether the existing look is intentional. Signalstats do not detect faces or
+creative intent.
+
+### Base payload
+
+Start here, then tune only when the sampled frames justify it:
+
+```json
+{ "preset": "skin-soft", "intensity": 0.6 }
+```
+
+`skin-soft` is a global tonal/color preset whose vibrance math is reduced for
+skin-like colors. It does not blur, retouch, segment, or track a face.
+
+### Bounded tuning
+
+Adjustment values are absolute values in the final payload, not deltas added to
+the preset. Keep changes inside these conservative ranges unless the user asks
+for a stylized result:
+
+| Property    | Natural Portrait range |
+| ----------- | ---------------------- |
+| intensity   | 0.45 to 0.75           |
+| exposure    | -0.06 to 0.14          |
+| contrast    | -0.05 to 0.08          |
+| highlights  | -0.18 to -0.04         |
+| shadows     | 0.04 to 0.18           |
+| whites      | -0.10 to 0.04          |
+| blacks      | -0.06 to 0.06          |
+| temperature | -0.05 to 0.10          |
+| tint        | -0.03 to 0.05          |
+| vibrance    | 0 to 0.06              |
+| saturation  | -0.04 to 0.06          |
+
+Leave grain, blur, and pixelate at zero. A vignette is optional at `0` to
+`0.05` only when it improves subject focus without looking like an effect.
+
+Manual controls must stay inside their schema section; they are never
+top-level keys. A tuned Natural Portrait payload looks like this:
+
+```json
+{
+  "preset": "skin-soft",
+  "intensity": 0.58,
+  "adjust": {
+    "highlights": -0.08,
+    "shadows": 0.08,
+    "temperature": 0.02,
+    "vibrance": 0.02
+  },
+  "details": { "vignette": 0.03 }
+}
+```
+
+Use the same nested shape in `grade-compare` candidate files. `adjust` owns
+tonal/color controls, `details` owns vignette/grain, and `effects` owns blur,
+pixelate, chroma bleed, and the advanced treatment primitives below.
+
+During the common comparison, reject any result that makes skin implausible,
+loses highlight detail, flattens or desaturates dark skin, or casts clothing and
+background colors accidentally.
+
+## Product Polish
+
+Use for photographed or filmed physical products when the goal is clean,
+accurate, dimensional presentation. Protect product color, material texture,
+label readability, specular highlights, and intentional lighting.
+
+Do not use this treatment for literal app/site screenshots or screen captures;
+follow UI Fidelity below. Do not neutralize a lifestyle scene's deliberate
+ambient color, and do not infer exact brand-color correction without a neutral
+reference or known product color.
+
+Inspect the product separately from its background. Check white balance, label
+legibility, surface texture, highlight clipping, shadow detail, white point,
+and black point. Statistics cannot identify a white package, metallic
+highlight, amber glass, or intentional warm light.
+
+### Base payload
+
+Compare this restrained correction against the untouched source:
+
+```json
+{
+  "intensity": 0.7,
+  "adjust": {
+    "exposure": 0.01,
+    "contrast": 0.06,
+    "highlights": -0.1,
+    "shadows": 0.04,
+    "whites": 0.02,
+    "blacks": -0.03,
+    "vibrance": 0.03,
+    "saturation": 0.02
+  }
+}
+```
+
+This is a comparison starting point, not an instruction to change an already
+finished source. If the original has accurate color, clean endpoints, and good
+texture, leave the pixels unchanged and polish through framing or motion.
+
+### Bounded tuning
+
+| Property    | Product Polish range |
+| ----------- | -------------------- |
+| intensity   | 0.45 to 0.8          |
+| exposure    | -0.08 to 0.1         |
+| contrast    | 0 to 0.1             |
+| highlights  | -0.16 to 0           |
+| shadows     | 0 to 0.12            |
+| whites      | -0.08 to 0.05        |
+| blacks      | -0.06 to 0.04        |
+| temperature | -0.05 to 0.05        |
+| tint        | -0.03 to 0.03        |
+| vibrance    | 0 to 0.06            |
+| saturation  | -0.04 to 0.05        |
+
+Temperature and tint stay at zero unless the frames show a plausible cast.
+Leave grain, vignette, blur, and pixelate at zero for catalog/e-commerce media.
+For a lifestyle product shot, a vignette up to `0.04` is acceptable only when
+it improves focus without changing the product itself.
+
+During the common comparison, reject any result that clips white packaging,
+muddies black products, shifts a known brand color, hides texture, or makes
+labels harder to read. Report when preserving the original was the deliberate
+decision.
+
+## UI Fidelity
+
+Use for literal app, website, dashboard, terminal, slide, or screen-recording
+pixels whose colors and readability are part of the product being shown.
+
+The default payload is **none**: do not add `data-color-grading`. Global color
+changes affect brand colors, status colors, charts, screenshots, and tiny text
+together, so even a tasteful photographic look can make the demonstration less
+truthful.
+
+Polish UI footage with crop, scale, pacing, cursor emphasis, surrounding DOM
+overlays, or seek-safe motion outside the captured pixels. If the user
+explicitly asks for a stylized UI look, preview it against the original and
+state that exact UI color is no longer preserved. If a camera filmed a screen,
+correct only a demonstrated capture cast or exposure issue and still verify
+text and brand colors across representative frames.
+
+## Film Memory
+
+Use when the story explicitly calls for a warm memory, restrained flashback,
+personal archive, or film-like recollection. This is not the default meaning of
+"cinematic", and it is not scanned-film-stock emulation.
+
+Do not use for literal UI, product catalog media, technical demonstrations, or
+footage whose accurate current-day color is important. Use a separate camcorder
+treatment for VHS/REC language. Do not add dust, scratches, light leaks, film
+burns, or halation unless an owned component is available and the requested
+story actually benefits from it.
+
+Check that the source has enough highlight and shadow detail to tolerate a
+faded treatment, and confirm nostalgia or temporal separation belongs in the
+story. Compare the full moving treatment, not only a still preset card.
+
+### Static pixel base
+
+Start with this owned shader recipe:
+
+```json
+{
+  "preset": "vintage-wash",
+  "intensity": 0.6,
+  "details": {
+    "vignette": 0.12,
+    "grain": 0.12,
+    "grainSize": 0.2,
+    "grainRoughness": 0.6
+  }
+}
+```
+
+Keep the static values inside these ranges:
+
+| Property       | Film Memory range |
+| -------------- | ----------------- |
+| intensity      | 0.5 to 0.75       |
+| vignette       | 0.08 to 0.16      |
+| grain          | 0.08 to 0.16      |
+| grainSize      | 0.16 to 0.24      |
+| grainRoughness | 0.5 to 0.7        |
+
+The stronger end can flatten dark skin, black clothing, or already-faded
+footage. Compare against the source and lower strength when it does.
+
+### Temporal character
+
+Use the existing registered paused GSAP timeline on the same media element:
+
+- author `--hf-color-grading-exposure: 0` in the media element's inline
+  `style`;
+- move it through a finite irregular sequence within `-0.03` to `0.03`, using
+  gentle `sine.inOut` segments around `0.45` to `0.8` seconds;
+- for gate weave, keep `x`/`y` within `0.15%` of the shorter composition edge,
+  rotation within `0.03` degrees, and scale between `1.005` and `1.01` to
+  protect the frame edges;
+- return close to the starting exposure and transform at the treatment end.
+
+Do not use randomness, infinite CSS keyframes, timers, or `onUpdate`. Flicker
+is a gentle exposure pulse, not a flash. Weave is slight mechanical drift, not
+handheld shake.
+
+Also run focused keyframe diagnostics and seek directly to the final-minus-frame
+position. Reject brightness pumping, distracting drift, clipped edges, or
+skin/detail loss. Report the motion ranges and describe this as an HF
+film-memory treatment, not camera-stock emulation. If motion reads as an effect
+before it reads as a memory, reduce or remove it.
+
+## Creator Camcorder
+
+Use when the story explicitly calls for a creator-camera recording, consumer
+camcorder memory, or restrained digital-video character. This treatment is a
+modern camcorder language, not VHS restoration, CRT simulation, surveillance,
+or a promise to reproduce a specific camera model.
+
+Do not apply it to literal UI, product catalog media, tiny media tiles, or
+already compressed footage that has distracting color bleed. Do not add a REC
+HUD merely because the source contains a person talking; the camera-device
+language must support the story or the user's requested style.
+
+Check skin, saturated edges, fine text, source compression, and whether the
+source already has a deliberate camera look. Reject softened chroma that
+damages labels, graphics, or identifying product color. Judge chroma softness
+and grain in motion, not one still.
+
+### Static pixel base
+
+Start with the proven shader payload below, then tune only inside the bounded
+ranges when representative frames justify it:
+
+```json
+{
+  "intensity": 0.72,
+  "adjust": {
+    "contrast": 0.08,
+    "highlights": -0.05,
+    "shadows": 0.02,
+    "whites": 0.03,
+    "blacks": -0.04,
+    "temperature": -0.03,
+    "tint": -0.015,
+    "vibrance": -0.03,
+    "saturation": -0.06
+  },
+  "details": {
+    "vignette": 0.06,
+    "grain": 0.08,
+    "grainSize": 0.18,
+    "grainRoughness": 0.58
+  },
+  "effects": { "chromaBleed": 0.55 }
+}
+```
+
+| Property       | Creator Camcorder range |
+| -------------- | ----------------------- |
+| intensity      | 0.55 to 0.8             |
+| contrast       | 0.03 to 0.1             |
+| highlights     | -0.1 to 0               |
+| shadows        | 0 to 0.06               |
+| whites         | 0 to 0.05               |
+| blacks         | -0.08 to -0.01          |
+| temperature    | -0.06 to 0.04           |
+| tint           | -0.03 to 0.02           |
+| vibrance       | -0.06 to 0.02           |
+| saturation     | -0.12 to -0.02          |
+| vignette       | 0.03 to 0.1             |
+| grain          | 0.04 to 0.12            |
+| grainSize      | 0.14 to 0.24            |
+| grainRoughness | 0.45 to 0.7             |
+| chromaBleed    | 0.35 to 0.7             |
+
+Leave blur and pixelate at zero. Square pixels, scanlines, RGB splitting, and
+tracking noise are different visual languages and are not defaults for this
+treatment.
+
+### Optional camera HUD
+
+When the narrative benefits from explicit recording-device language, install
+the Registry overlay block:
+
+```bash
+npx hyperframes add camcorder-hud --no-clipboard
+```
+
+Insert the printed `data-composition-src` host over the intended media range.
+Edit the displayed date/time/mode/counter in
+`compositions/camcorder-hud.html`. The block's paused GSAP timeline derives
+its counter and REC blink from composition time, so play, scrub, and render
+agree. Keep the HUD finite and scoped to the shot.
+
+The HUD is an optional authored overlay. The pixel payload remains useful
+without it, and the HUD alone is not evidence that the footage was treated.
+
+### Optional source-to-camera reveal
+
+Global grading intensity fades only primary correction and LUT output; it does
+not fade the independent camcorder effects. For a visible source-to-camera
+mode change, use two synchronized media layers and a finite opacity crossfade
+from untreated to treated footage. Fade the HUD in on that same paused GSAP
+timeline. Do not animate shader state with callbacks or an independent clock.
+
+Also verify HUD placement and framing in each aspect ratio the project supports.
+Report whether the HUD was used and describe this as an HF camcorder treatment,
+not camera/VHS emulation. If an effect artifact is more noticeable than the
+subject, reduce chroma bleed/grain or keep the source unchanged.
+
+## VHS Playback
+
+Use when the story explicitly calls for analog home-video tape, a dated archive,
+or a visibly degraded VHS playback. This treatment is not Creator Camcorder,
+generic pixelation, CRT display simulation, or a default retro look.
+
+Do not use for literal UI, product catalog media, small text, clean modern
+creator footage, or any source whose identifying color/detail must remain exact.
+Inspect high-contrast vertical edges, faces, saturated objects, and the bottom
+of the frame in motion. Analog damage must support the story without making the
+subject hard to read.
+
+### Pixel payload
+
+Start with the complete proven combination, not `tapeDamage` alone:
+
+```json
+{
+  "intensity": 1,
+  "adjust": { "contrast": -0.04, "saturation": -0.08 },
+  "details": {
+    "grain": 0.16,
+    "grainSize": 0.12,
+    "grainRoughness": 0.72
+  },
+  "effects": {
+    "tapeDamage": 0.82,
+    "tapeTracking": 0.85,
+    "tapeNoise": 0.3,
+    "tapeSpeed": 0.5,
+    "chromaBleed": 0.5,
+    "chromaticAberration": 0.18,
+    "chromaticAngle": 0,
+    "scanlines": 0.35,
+    "scanlineCount": 0.17,
+    "scanlineSoftness": 1,
+    "digitalGlitch": 0.32,
+    "digitalGlitchColorSplit": 0,
+    "digitalGlitchLineTear": 0.08,
+    "digitalGlitchPixelate": 0,
+    "digitalGlitchBlockAmount": 0,
+    "digitalGlitchBlockDisplacement": 0,
+    "digitalGlitchBlockOpacity": 0,
+    "digitalGlitchSpeed": 0.5
+  }
+}
+```
+
+| Property              | VHS Playback range |
+| --------------------- | ------------------ |
+| intensity             | 0.75 to 1          |
+| contrast              | -0.1 to 0          |
+| saturation            | -0.16 to 0         |
+| grain                 | 0.08 to 0.18       |
+| grainSize             | 0.08 to 0.18       |
+| grainRoughness        | 0.55 to 0.8        |
+| tapeDamage            | 0.65 to 0.9        |
+| tapeTracking          | 0.5 to 0.9         |
+| tapeNoise             | 0.15 to 0.45       |
+| tapeSpeed             | 0.35 to 0.65       |
+| chromaBleed           | 0.35 to 0.65       |
+| chromaticAberration   | 0.08 to 0.22       |
+| scanlines             | 0.2 to 0.4         |
+| scanlineCount         | 0.14 to 0.2        |
+| digitalGlitch         | 0.2 to 0.4         |
+| digitalGlitchLineTear | 0.04 to 0.1        |
+
+`tapeDamage` owns deterministic horizontal line jitter, slow time-base wobble,
+bottom-edge head switching, luma bandwidth loss, restrained ghosting, noise,
+and sparse dropouts. Its subordinate tracking/noise/speed controls add bounded
+moving tape tears and control their signal character without introducing a new
+clock. `chromaBleed` separately reduces horizontal chroma detail. The restrained
+scanline and chromatic settings supply the remaining tape-playback character.
+The digital stage is used only for rare horizontal row tears: keep its color
+split, pixelation, block displacement, block opacity, and corruption values at
+zero. Leave blur, CRT curvature, generic pixelation, and a camera HUD off.
+
+These values are an original HyperFrames recipe calibrated on the same public
+Orange Cat source used for the external visual reference. They are not copied
+shader code or a claim of pixel-identical output from the external reference. The scanline count is
+mapped to the reference's approximately 127-cycle primary line pattern; the HF
+tracking math stays bounded in media pixels and uses the composition clock.
+
+The shader damage evolves from the existing deterministic media time, so it
+needs no CSS loop or private timeline. Global grading intensity does not fade
+tape damage or other independent effects. If the story requires a finite
+source-to-tape reveal, crossfade synchronized untreated and treated media layers
+on the host's paused GSAP timeline. During the common workflow, inspect dense
+consecutive frames and reject hard edge tearing, face
+smearing, frozen noise, square blocks, blank borders, or a bottom disturbance
+that competes with the subject.
+
+## 8mm Home Movie
+
+Use for personal archive, family-memory, childhood, travel-memory, or explicit
+small-gauge home-movie language. This is stronger and more materially film-like
+than Film Memory, but it is still an owned HyperFrames treatment rather than a
+claim to reproduce a named film stock, camera, or laboratory process.
+
+Do not use for literal UI, technical demonstrations, catalog products, clean
+interviews, or footage where dust/scratches would imply false provenance. Check
+skin, highlights, dark clothing, and frame edges before applying it.
+
+### Pixel payload
+
+```json
+{
+  "preset": "vintage-wash",
+  "intensity": 0.72,
+  "details": {
+    "vignette": 0.28,
+    "vignetteMidpoint": 0.54,
+    "vignetteFeather": 0.72,
+    "grain": 0.34,
+    "grainSize": 0.18,
+    "grainRoughness": 0.72
+  },
+  "effects": { "filmArtifacts": 0.62 }
+}
+```
+
+| Property       | 8mm Home Movie range |
+| -------------- | -------------------- |
+| intensity      | 0.6 to 0.8           |
+| vignette       | 0.18 to 0.34         |
+| grain          | 0.22 to 0.42         |
+| grainSize      | 0.12 to 0.24         |
+| grainRoughness | 0.6 to 0.8           |
+| filmArtifacts  | 0.35 to 0.7          |
+
+`filmArtifacts` owns only deterministic sparse dust and short scratches. The
+existing preset/details own color, vignette, and grain; the host's paused GSAP
+timeline owns optional gate weave. Keep weave within `0.15%` of the shorter
+composition edge, rotation within `0.03` degrees, and scale between `1.005` and
+`1.015`. Use finite `sine.inOut` segments around `0.6` to `1` second, return
+near the starting transform, and never use randomness, timers, `onUpdate`, or
+an infinite CSS animation.
+
+Reject a result when dust is constantly visible, scratches persist unnaturally,
+the frame pumps, weave exposes an edge, highlights turn muddy, or the material
+artifacts are more noticeable than the memory. For a subtler nostalgic result,
+use Film Memory instead.
+
+## Editorial Halftone
+
+Use for print/editorial transitions, poster frames, comic/newsprint language,
+stylized product or portrait beats, and graphic sequences where visible ink
+screening is the point. This is a real four-angle CMYK raster treatment, not a
+dotted DOM overlay.
+
+Do not use on literal UI, dense text, tiny labels, footage that must remain
+photorealistic, or a long talking-head segment unless the user explicitly asks
+for strong print stylization. Preserve text/captions as ungraded DOM above the
+media whenever they must stay readable.
+
+### Pixel payload
+
+```json
+{
+  "intensity": 1,
+  "adjust": { "contrast": 0.04, "saturation": 0.04 },
+  "effects": { "halftone": 0.94, "halftoneSize": 0.36 }
+}
+```
+
+| Property     | Editorial Halftone range |
+| ------------ | ------------------------ |
+| intensity    | 0.8 to 1                 |
+| contrast     | -0.02 to 0.08            |
+| saturation   | -0.04 to 0.08            |
+| halftone     | 0.75 to 1                |
+| halftoneSize | 0.15 to 0.55             |
+
+The shader uses fixed C/M/Y/K screen angles of 15/75/0/45 degrees, separate ink
+coverage, a warm paper base, and resolution-aware dot-cell sizing. Keep those
+screen semantics fixed; tune only amount and size unless a future visual proof
+justifies a broader schema. Judge the result at final output resolution because
+browser zoom can misrepresent the screen. Reject unstable moire, unreadable
+subjects, clipped ink detail, excessive dot size, or any treatment that looks
+like a transparent dot texture laid over unchanged footage.
+
+## Two-Ink Editorial Print
+
+Use for poster frames, editorial portraits, music/social cutaways, zine
+graphics, and bold print-led transitions where two visible spot inks are more
+appropriate than photographic color. This is a fixed original HyperFrames
+vermilion/teal treatment, not a claim to emulate a named printer, ink set, or
+commercial print process.
+
+Do not use for literal UI, brand-color-critical products, small labels, natural
+talking heads, or media that must remain photorealistic. Keep captions and
+graphics as normal DOM above the treated media.
+
+### Pixel payload
+
+```json
+{
+  "intensity": 1,
+  "adjust": { "contrast": 0.08, "highlights": -0.06, "shadows": 0.04 },
+  "effects": { "twoInkPrint": 1, "twoInkPrintSize": 0.42 }
+}
+```
+
+| Property        | Two-Ink range |
+| --------------- | ------------- |
+| intensity       | 0.8 to 1      |
+| contrast        | 0.02 to 0.1   |
+| highlights      | -0.1 to 0     |
+| shadows         | 0 to 0.08     |
+| twoInkPrint     | 0.8 to 1      |
+| twoInkPrintSize | 0.18 to 0.55  |
+
+The shader maps warm midtones to vermilion, deep/cool shadows to teal, and
+shared dark coverage to a dark overprint on warm paper. It uses separate
+15/75-degree screens, a subtle fixed registration offset, deterministic paper
+texture, and resolution-aware dot sizing. Do not combine it with `halftone` or
+a duotone LUT: that re-separates the result and defeats the two-ink contract.
+
+Judge it at output resolution and across multiple frames. Reject missing second
+ink, crushed faces, unstable moire, illegible silhouettes, or a result that
+reads as a red tint with dots rather than two screened inks.
+
+## Monochrome Screen Print
+
+Use for graphic portrait beats, posterized social inserts, newspaper-like
+screens, or a finite transition into visible monochrome cells. Keep captions
+and typography as normal DOM above the treated media.
+
+```json
+{
+  "intensity": 1,
+  "effects": {
+    "monoScreen": 1,
+    "monoScreenSize": 0.35,
+    "monoScreenAngle": 0.25,
+    "monoScreenSpread": 0.3,
+    "monoScreenShape": 0,
+    "monoScreenInvert": 0
+  },
+  "palette": ["#111319", "#f2ecdc"]
+}
+```
+
+Use `monoScreenShape` `0..4` for circle, square, diamond, triangle, or line.
+Keep cell size within `0.15..0.55` and spread within `0.15..0.55`. Reject faces
+that lose their silhouette, unstable moire, or cells too small to survive the
+final encoded resolution.
+
+## Engraved Illustration
+
+Use for editorial portraits, historical/technical illustration, title-card
+cutaways, or a source-to-line-art reveal. It is not routine correction and
+should not be applied to literal UI or brand-color-critical product footage.
+
+```json
+{
+  "intensity": 1,
+  "effects": {
+    "engraving": 1,
+    "engravingSpacing": 0.4118,
+    "engravingMinThickness": 0.2,
+    "engravingMaxThickness": 0.4571,
+    "engravingAngle": 0.25,
+    "engravingContrast": 0.4667,
+    "engravingSharpness": 0.59,
+    "engravingWave": 0.2,
+    "engravingWaveFrequency": 0.2222
+  },
+  "palette": ["#101216", "#f3eddf"]
+}
+```
+
+Preserve the calibrated base first. Tune spacing within `0.25..0.6`, contrast
+within `0.3..0.65`, and wave within `0..0.35`. Reject squeezed framing, broken
+contours, noisy flat backgrounds, or lines that flicker across moving frames.
+
+## Crosshatched Sketch
+
+Use for hand-rendered editorial beats, comic/documentary cutaways, and short
+illustrative transformations where multiple line directions should preserve
+the subject contour.
+
+```json
+{
+  "intensity": 1,
+  "effects": {
+    "crosshatch": 1,
+    "crosshatchSpacing": 0.28,
+    "crosshatchThickness": 0.25,
+    "crosshatchAngle": 0.25,
+    "crosshatchContrast": 0.3333,
+    "crosshatchEdges": 0.5,
+    "crosshatchLineWeight": 0,
+    "crosshatchWave": 0.33,
+    "crosshatchWaveFrequency": 0.2222
+  },
+  "palette": ["#101216", "#f3eddf"]
+}
+```
+
+Tune spacing within `0.18..0.5`, edge detail within `0.3..0.7`, and wave within
+`0.1..0.45`. Reject distorted aspect ratio, dense black fill that hides the
+subject, or temporal shimmer stronger than the intended sketch language.
+
+## CRT Display
+
+Use when the media is intentionally shown as an older monitor, terminal, game
+screen, or broadcast display. Curvature alone is geometry, not a complete CRT
+treatment, so pair it with restrained scanlines and only slight channel
+separation.
+
+```json
+{
+  "intensity": 1,
+  "effects": {
+    "crtCurvature": 0.2,
+    "scanlines": 0.35,
+    "scanlineCount": 0.17,
+    "scanlineSoftness": 1,
+    "chromaticAberration": 0.08,
+    "chromaticAngle": 0
+  }
+}
+```
+
+Keep curvature within `0.08..0.28`, scanlines within `0.18..0.45`, and channel
+separation within `0..0.12`. Reject excessive black corners, unreadable UI,
+large color fringes, or applying the display language to ordinary footage when
+the user only asked for correction.
+
+## Procedural ASCII
+
+Use for a deliberate terminal, code, data, surveillance, editorial, or
+source-to-character reveal. This is a real shader-generated 5x7 glyph field,
+not monospace text placed over unchanged footage.
+
+Do not use as routine talking-head polish, on literal UI or dense text, or when
+recognizing a face/product precisely matters. Keep captions and graphics as
+normal DOM above the treated media.
+
+Choose one of these proven starting points:
+
+```json
+{
+  "effects": { "ascii": 1, "asciiSize": 0.08, "asciiInvert": 1 },
+  "palette": ["#020605", "#38ff78"]
+}
+```
+
+The first is **Terminal ASCII**: dark field, bright green glyphs, appropriate
+for code/data/device language. For a warmer print-like **Editorial ASCII**, use:
+
+```json
+{
+  "effects": { "ascii": 1, "asciiSize": 0.066, "asciiInvert": 0 },
+  "palette": ["#0b0d0d", "#eee9db"]
+}
+```
+
+Keep `ascii` between `0.75` and `1` for a fully readable treatment and
+`asciiSize` between `0.04` and `0.15`. A finite reveal may author
+`--hf-color-grading-ascii: 0` inline and tween it to `1` with the registered
+paused GSAP timeline. Reject unstable cells, lost silhouette/face structure,
+unreadable composition, or a palette that conflicts with the project.
+
+## Ordered Palette Dither
+
+Use for posterized social beats, music/editorial cutaways, pixel-art language,
+or a finite source-to-palette reveal. The shader uses a stable 4x4 Bayer
+threshold matrix and an explicit dark-to-light palette. Do not describe it as
+Floyd-Steinberg, Atkinson, or another sequential error-diffusion process.
+
+Do not use on literal UI, brand-color-critical products, tiny labels, or long
+photorealistic sections. Start with one of these original palettes:
+
+```json
+{
+  "effects": { "dither": 1, "ditherSize": 0.25 },
+  "palette": ["#17121a", "#824c50", "#e09873", "#f7ddb1"]
+}
+```
+
+The four-color option is **Warm Print**. For a louder social/music beat, use
+the six-color **Electric Ink** palette:
+
+```json
+{
+  "effects": { "dither": 1, "ditherSize": 0.4 },
+  "palette": ["#080717", "#3c185f", "#7e2278", "#d9339f", "#ff6b66", "#aafae0"]
+}
+```
+
+HyperFrames also owns these named ramps. The name is an authoring shortcut;
+persist the listed colors through the existing `palette` array:
+
+| Group       | Palette ID       | Ordered colors                                                   |
+| ----------- | ---------------- | ---------------------------------------------------------------- |
+| Classic     | `noir`           | `#000000`, `#ffffff`                                             |
+| Classic     | `ink-paper`      | `#1a1a2e`, `#f5f5dc`                                             |
+| Classic     | `terminal`       | `#001100`, `#00ff00`                                             |
+| Classic     | `amber-glow`     | `#1a0f00`, `#ffcc00`                                             |
+| Classic     | `handheld-green` | `#0f380f`, `#306230`, `#8bac0f`, `#9bbc0f`                       |
+| Mood        | `golden-hour`    | `#1a1205`, `#4a3510`, `#8b6914`, `#d4a017`, `#fff8dc`            |
+| Mood        | `deep-sea`       | `#0a1628`, `#1a3a5c`, `#2d6187`, `#5ba4c9`, `#a8dce8`            |
+| Mood        | `arctic-night`   | `#0a0a14`, `#1a2a4a`, `#3a5a8a`, `#6a9aca`, `#cae8ff`            |
+| Mood        | `synthwave`      | `#120458`, `#7b2cbf`, `#e040fb`, `#ff6ec7`, `#fff59d`            |
+| Mood        | `vaporwave`      | `#1a0a2e`, `#3d1a5c`, `#ff71ce`, `#01cdfe`, `#fffb96`            |
+| Mood        | `forest`         | `#1a2e1a`, `#2d4a2d`, `#4a7c4a`, `#7ab37a`, `#c8e6c8`            |
+| Mono        | `sepia`          | `#1a1610`, `#3d3020`, `#6b5a40`, `#a89070`, `#e8dcc8`            |
+| Mono        | `blueprint`      | `#001830`, `#003060`, `#0050a0`, `#0080e0`, `#e0f0ff`            |
+| HyperFrames | `warm-print`     | `#17121a`, `#824c50`, `#e09873`, `#f7ddb1`                       |
+| HyperFrames | `electric-ink`   | `#080717`, `#3c185f`, `#7e2278`, `#d9339f`, `#ff6b66`, `#aafae0` |
+
+Choose by inspected source and project language, not by palette name alone.
+For example, `terminal` fits device/code language, `warm-print` fits editorial
+print, and `synthwave` is an intentional stylization rather than generic polish.
+
+`palette` must contain two to six exact `#RRGGBB` colors in authored order. Use
+dark-to-light order for this treatment; the runtime validates colors but does
+not reorder them, so reversing the array intentionally inverts the mapping.
+Keep `dither` between `0.7` and `1` and `ditherSize` between `0.1` and `0.5`.
+A finite reveal may author `--hf-color-grading-dither: 0` inline and tween it
+to the chosen amount with GSAP. Judge the moving result at output resolution;
+reject shimmer, lost subject structure, accidental muddy intermediate colors,
+or a palette chosen without regard to the project's design language.
+
+## Cached Error Diffusion
+
+Use exact error diffusion for a deliberate 1-bit Macintosh, newspaper/print,
+limited-palette game, or crunchy editorial treatment. It bakes a new image or
+MP4 because every processed block depends on error from earlier blocks; it is
+not a realtime shader setting.
+
+Choose the algorithm by visible intent:
+
+- `floyd-steinberg`: balanced default with organic fine texture.
+- `atkinson`: higher-contrast, more open and distinctly early-Macintosh.
+- `jarvis-judice-ninke`: smoother gradients with a wider 12-neighbor field.
+- `stucki`: smooth, slightly sharper alternative to JJN.
+- `burkes`: compact two-row texture.
+- `sierra`, `sierra-lite`, `two-row-sierra`: progressively different
+  speed/texture tradeoffs; use only after comparing frames.
+
+Run the exact processor and register its output through the existing media
+ledger/cache:
+
+```bash
+node <SKILL_DIR>/scripts/dither.mjs \
+  --input .media/videos/video_001.mp4 \
+  --out .media/generated/video_001.atkinson.mp4 \
+  --algorithm atkinson \
+  --palette '#17121a,#824c50,#e09873,#f7ddb1' \
+  --point-size 3
+
+npx hyperframes media-use resolve \
+  --from .media/generated/video_001.atkinson.mp4 --type video --project .
+```
+
+Use the registered output path on a real `<img>` or `<video>`. Keep text,
+captions, logos, and interface graphics outside the processed media. For a
+finite reveal, overlap the original and processed media with identical framing
+and crossfade or wipe them using the registered paused GSAP timeline. Do not
+label the realtime Bayer shader as Floyd-Steinberg/Atkinson, and do not process
+PQ/HLG footage without an explicit SDR tone-map decision.
+
+## Organic Light Leak
+
+Use for one motivated memory beat, time shift, warm scene handoff, or tactile
+transition. It is a finite deterministic CSS/GSAP overlay, not a looping
+texture, generic flash, or film-stock emulation.
+
+Install the Registry overlay block:
+
+```bash
+npx hyperframes add organic-light-leak-overlay --no-clipboard
+```
+
+Insert the printed `data-composition-src` host at the intended beat and keep
+its duration finite. Its paused timeline owns one rise, peak, and complete
+recovery and scales those phases to the placed duration. Inspect the source
+before, at the brightest frame, and after recovery. Reject clipped faces, an
+unmotivated warm wash, visible black from incorrect blend mode, or a leak that
+conceals the subject longer than the transition needs.
+
+## Freeze-Frame Cutout
+
+Use for a social introduction, speaker emphasis, chapter punctuation, sports
+or creator beat, or a scrapbook/editorial hold. This requires a real alpha
+matte; decoration may not conceal a poor subject edge.
+
+Extract the exact deterministic source frame first, then remove its background:
+
+```bash
+ffmpeg -ss <seconds> -i <source-video> -frames:v 1 -y .media/generated/freeze-source.png
+npx hyperframes remove-background .media/generated/freeze-source.png \
+  -o .media/generated/freeze-cutout.png --json
+npx hyperframes add freeze-frame-dressing --no-clipboard
+```
+
+Add the transparent result as a direct-root timed media layer and insert the
+printed overlay block above the same time range. The block owns the paper,
+tape, and flash; the host timeline only animates the real cutout:
+
+```html
+<img
+  id="hf-freeze-cutout"
+  class="clip"
+  src="./.media/generated/freeze-cutout.png"
+  alt=""
+  data-start="6"
+  data-duration="3"
+  data-track-index="20"
+/>
+```
+
+```js
+tl.fromTo(
+  "#hf-freeze-cutout",
+  { y: 42, scale: 0.86, rotation: -2 },
+  { y: 0, scale: 1, rotation: 0.4, duration: 0.5, ease: "back.out(1.35)" },
+  freezeAt,
+);
+```
+
+Inspect the matte over both light and dark temporary plates before styling it.
+Reject missing hair/fingers, background halos, a cutout that changes identity,
+overly thick outline, exposed frame edges, or a flash that obscures the reveal.
+If the matte is not acceptable, choose another frame or keep the original media.
+
+## Social Flash / Editorial Reveal
+
+Use this treatment for one meaningful high-energy cut, creator reveal, product
+beat, or before/after handoff. It is not a default transition for every scene.
+Avoid it for calm long-form footage, accessibility-sensitive contexts, already
+clipped highlights, literal UI that must remain readable through the cut, or
+any request for repeated strobing.
+
+Inspect representative frames on both sides of the cut first. Grade each media
+layer for its own subject using the appropriate contract above; the flash is
+not a substitute for correction. For people, a restrained `skin-soft` payload
+is a safe starting point. For literal UI, preserve the pixels and use only the
+authored light/motion layers when they do not obscure required information.
+
+Install the Registry overlay block:
+
+```bash
+npx hyperframes add editorial-flash-overlay --no-clipboard
+```
+
+Insert the printed `data-composition-src` host so the block's midpoint lands
+on the cut. Its own paused timeline drives the finite flash. The host timeline
+may coordinate outgoing and incoming media motion without reaching into the
+block:
+
+```js
+tl.to(
+  "#outgoing-media",
+  {
+    scale: 1.035,
+    "--hf-color-grading-exposure": 0.82,
+    duration: 0.12,
+    ease: "power3.in",
+  },
+  cutAt - 0.16,
+);
+tl.fromTo(
+  "#incoming-media",
+  { scale: 1.1 },
+  { scale: 1, duration: 0.42, ease: "power3.out" },
+  cutAt,
+);
+tl.to(
+  "#incoming-media",
+  {
+    "--hf-color-grading-exposure": 0,
+    "--hf-color-grading-intensity": 0.58,
+    duration: 0.24,
+    ease: "power2.out",
+  },
+  cutAt,
+);
+```
+
+When the shader steps are used, author
+`--hf-color-grading-exposure: 0.72` and
+`--hf-color-grading-intensity: 0` inline on the incoming media so a fresh seek
+has the correct start state. Set the final intensity to the source-approved
+value instead of copying `0.58` blindly. Skip the shader intensity step when
+the incoming source should remain ungraded.
+
+Keep the rise between roughly `0.035` and `0.055` seconds and the recovery
+between `0.24` and `0.38` seconds. Default to one neutral/warm flash event,
+never saturated red, never a looping strobe, and never more than one authored
+flash inside a one-second treatment window. Verify frames immediately before,
+at, and after the cut, then inspect moving playback and a rendered draft. The
+peak must hide the cut; the recovery must reveal a correctly framed source with
+no retained prior canvas, clipped face, or unexpected highlight damage.