better-dsh 0.2.5 → 0.3.0-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/creative/creative-mono-color.md

@@ -1,158 +0,0 @@
----
-title: "Mono Color — Generate one- or two-ink editorial print poster images"
-sidebar_label: "Mono Color"
-description: "Generate one- or two-ink editorial print poster images"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Mono Color
-
-Generate one- or two-ink editorial print poster images.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/creative/mono-color` |
-| Path | `optional-skills/creative/mono-color` |
-| Version | `1.0.0` |
-| Author | Yan Liu (adapted by Nous Research) |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `design`, `poster`, `print`, `duotone`, `risograph`, `editorial`, `image-generation` |
-| Related skills | [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation), [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Mono-Color Editorial Print Skill
-
-Turn any user theme, sentence, or reference photo into an original printed editorial artifact with one stable visual language: adaptive neutral substrate + one or two inks + mechanically reproduced image + typographic tension + concise human voice.
-
-This skill designs and generates the image; it does not imitate any one reference, copy a source composition, wording, logo, or artwork, and it never uses more than two printing inks.
-
-## When to Use
-
-The user asks for a monochrome editorial poster, duotone print, risograph/zine poster, halftone photo treatment, one-ink or two-ink cover, or names the mono-color style. Chinese trigger vocabulary includes 单色海报、双色印刷、单色调视觉、蓝色/绿色孔版印刷、网点照片、复古或当代编辑排版. Do not trigger merely because a request mentions a color.
-
-## Prerequisites
-
-- The Hermes `image_generate` tool (search/describe it via the deferred-tool catalog if not loaded). If image generation is unavailable, deliver prompt-only and say so.
-- The `design-system/` catalogs bundled with this skill (see Quick Reference).
-
-## Quick Reference
-
-Print modes:
-
-| Mode | When |
-|---|---|
-| Pure one-ink | User explicitly requests one ink, monochrome, or one named ink without a second color |
-| Chromatic ink + black | Quiet, observational, natural, architectural, long-form subjects; chromatic plate carries the image, carbon/charcoal carries text |
-| Complementary duotone | General default; dominant plate 70–85%, accent 15–30% with a specific role; fallback pair Cobalt + Terracotta `#2148B8` + `#C65F38` |
-| Overprint duotone | Two plates deliberately overlap; the darker mixed zone is not a third ink |
-
-Catalogs (source of truth — **when an exact value differs, the catalog wins over any prose**; read only the catalog relevant to the current decision):
-
-| File | Provides |
-|---|---|
-| `design-system/colors.json` | Substrate IDs + exact hex, one-ink palette, approved two-ink pairs |
-| `design-system/compositions.json` | Layout-family IDs and geometry |
-| `design-system/typography.json` | Type-hierarchy role IDs |
-| `design-system/rhythm.json` | Visual tension profiles, focal events, unresolved edges |
-| `design-system/imperfections.json` | Controlled print-imperfection effect IDs and ranges |
-| `design-system/carriers.json` | Carrier signals (poster, journal page, cover, etc.) |
-
-References:
-
-- `references/visual-language.md` — full color/space/image-treatment/typography/tone rules
-- `references/composition.md` — layout decision flow, layout families, composition grammar, rhythm
-- `references/quality-gate.md` — originality firewall, hard avoids, inspection checklist
-
-## Procedure
-
-1. **Read the input.** Extract five things:
-   - **Subject:** the one person, object, scene, or idea that must remain recognizable.
-   - **Intent:** poetic observation, announcement, field note, personal statement, cultural poster, or specimen page.
-   - **Words:** preserve exact supplied text verbatim in its original language — never translate or rewrite it. If no text is supplied, invent one English display phrase of 2–8 words and keep it stable across retries. Omit text only on explicit request.
-   - **Image role:** hero photograph, isolated specimen, cropped fragment, texture source, or none.
-   - **Representation:** faithful reproduction (default) or abstract symbol extraction (when the user asks for abstract, artistic, loose, experimental, less realistic, or less photographic treatment).
-
-   For a complex topic, pick one concrete visual metaphor; do not illustrate every point. If the user supplies an image, preserve its identity and factual content — crop/isolate/halftone it, never replace the subject or invent branded details.
-
-2. **Resolve the recipe manifest.** Fill every field; do not skip any and do not expose the manifest unless the user asks for process details. Look up IDs and exact values in `design-system/`.
-
-   ````yaml
-   subject: <one recognizable subject>
-   intent: <one intent from Input Reading>
-   exact_text: <user text, generated 2-8 word phrase, or none>
-   text_language: <language of supplied text, otherwise English>
-   representation: <faithful reproduction or abstract symbol extraction>
-   ratio: <explicit ratio or 3:4>
-   carrier: <one carrier ID from design-system/carriers.json or none>
-   substrate: <one substrate ID and exact hex from design-system/colors.json>
-   mode: <pure one-ink, chromatic + black, complementary duotone, or overprint duotone>
-   palette: <one palette ID from design-system/colors.json>
-   inks: <the palette's named ink or approved pair with exact hex values>
-   plate_roles: <one explicit role per ink plate>
-   layout: <one composition ID from design-system/compositions.json>
-   empty_paper: <explicit percentage>
-   visual_tension: <relaxed, balanced, or assertive from design-system/rhythm.json>
-   focal_event: <one strong visual event from design-system/rhythm.json>
-   release_zone: <one deliberately quiet region that gives the focal event room>
-   unresolved_edge: <one optional edge behavior from design-system/rhythm.json or none>
-   image_treatment: <one mechanical reproduction process>
-   type_hierarchy: <one role ID from design-system/typography.json>
-   disruption: <one deliberate disruption>
-   imperfection_seed: <stable hash derived from the resolved recipe>
-   imperfections: <0-2 restrained effect IDs for contemporary work, or 2-3 for tactile/vintage work>
-   ````
-
-   Defaults when the user hasn't chosen: ratio `3:4`; substrate Neutral White `#FAFAF7` (Cool Gray `#E9E9E5` for architecture/tech/restrained; Pale Beige `#F5F1E8` only for tactile/archival/nostalgic subjects — never assume beige merely because the work uses halftone or risograph language); mode complementary duotone with Cobalt + Terracotta; empty paper `35%`; tension `relaxed` for reflective/leisure/unspecified cultural subjects, `balanced` for editorial information, `assertive` only for forceful declarations; disruption = one off-center image crop, or one oversized word when there is no image. Explicit user choices override defaults unless they violate the two-ink limit or the originality firewall. Identical inputs must resolve to the identical manifest — never vary palette, layout, percentages, or process for novelty.
-
-   Resolve generic color words consistently: blue→Cobalt, green→Botanical Green, orange→Terracotta Orange, red→Signal Red, purple→Aubergine, black→Charcoal; green+black→Mint Green + Charcoal; blue+orange→Cobalt + Terracotta. Exact named inks always take precedence.
-
-3. **Choose the layout.** Walk the decision flow in `references/composition.md` top to bottom and take the first match (events→ruled information poster; botanical→archival plate; repeated object→object field; crossing layers→overprint collage; supplied photo→image field or editorial cover; isolated objects→specimen annotation; phrase-as-subject→type-led declaration; essay-like→editorial journal; otherwise editorial cover).
-
-4. **Compile the prompt** in five compact paragraphs, in order:
-   1. **Canvas and ink:** ratio, exact substrate hex and reason, exact one/two-ink palette hexes, print mode, plate roles, flat front-facing page (no mockup, frame, desk, or shadow).
-   2. **Original composition:** layout family, tension profile, one focal event, one release zone, margins (5–9%), empty-paper percentage (25–55%), grid, dominant object scale (45–80% of page) and edge crop, optional unresolved edge, one manual gesture.
-   3. **Subject:** what appears; for faithful reproduction, preservation/crop/halftone/paper exposure; for abstract extraction, the 2–4 identity anchors, dominant mass, structural contour, repeated rhythm, and where exposed paper cuts through.
-   4. **Typography and words:** hierarchy, type voices, exact short display text, and the explicit overlap/crossing/split/tight alignment between headline and dominant object.
-   5. **Material and avoids:** dots, fibers, bleed, misregistration, plus the hard negative constraints from `references/quality-gate.md`.
-
-   Describe only visible outcomes. Never mention reference artists, studios, sample posters, or "in the style of."
-
-5. **Generate and inspect.** Call `image_generate` with the compiled prompt. Inspect at full and thumbnail size against the checklist in `references/quality-gate.md`; regenerate once on failure (extra ink, missing plate roles, empty paper outside 25–55%, unrecognizable subject, no ≥5x type scale jump, garbled text, composition copying a reference, no identifiable focal event). If exact text still renders wrong after one retry, generate a text-light base image and state that typography should be overlaid in a layout tool — never pretend distorted text is correct.
-
-6. **Deliver.** Save outputs under `./mono-color-output/` in the user's working directory (create it if needed), or another location the user names. Present:
-   1. the generated image (path or rendered);
-   2. the final prompt in a fenced `text` block;
-   3. a short recipe note: Mode, Ink (exact hexes), Layout, Type (editorial + utility voice), Process, and one Originality sentence naming the structural departures from any supplied reference.
-
-   Stop at prompt-only only when the user explicitly asks or image generation is unavailable.
-
-## Pitfalls
-
-- **Never more than two printing inks.** The substrate is not an ink; overprint mixing and density variation are not extra inks. Gradients, rainbow accents, and full-color photography are always out.
-- **Catalog wins over prose.** When a hex, ID, range, or geometry in `design-system/` differs from any prose description, use the catalog value.
-- **Preserve supplied text verbatim** — original language, exact wording, no translation unless asked. Never distort microcopy or factual text with imperfection effects.
-- **Never copy a source composition, wording, logo, or artwork.** Change at least four structural features from any supplied reference (see the originality firewall). No fake signatures, mastheads, sponsors, URLs, or invented branding.
-- **Contemporary by default.** Do not add yellowed paper, sepia, distressed borders, or retro props merely because the work uses halftone or limited inks — only when the user asks for vintage/archival mood.
-- **One focal event, one release zone.** Never center everything, never distribute elements evenly like a template, never fill the quiet zone with decoration.
-
-## Verification
-
-- Manifest fully resolved, all IDs present in the `design-system/` catalogs.
-- Result uses one intentional white/gray/pale-beige substrate and ≤2 inks with clear plate roles.
-- 25–55% visibly empty paper; one dominant object at 45–80%; headline visibly crosses or locks to it.
-- Type hierarchy shows a 5–12x scale jump with ≤3 type voices.
-- Supplied subject and text preserved exactly; ≥4 structural features differ from every supplied reference.
-- An image was generated (unless prompt-only was requested) and saved under the output directory, and the recipe note was delivered.
-
-## Notice
-
-Upstream example artwork is not included: `examples/` in the source repo is all-rights-reserved (see upstream ASSET-LICENSE.md); only MIT-licensed text and design-system catalogs are vendored here. Code and text are MIT (see `LICENSE.txt`).

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/creative/creative-pixel-art.md

@@ -1,234 +0,0 @@
----
-title: "Pixel Art — Pixel art w/ era palettes (NES, Game Boy, PICO-8)"
-sidebar_label: "Pixel Art"
-description: "Pixel art w/ era palettes (NES, Game Boy, PICO-8)"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Pixel Art
-
-Pixel art w/ era palettes (NES, Game Boy, PICO-8).
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/creative/pixel-art` |
-| Path | `optional-skills/creative\pixel-art` |
-| Version | `2.0.0` |
-| Author | dodo-reach |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `creative`, `pixel-art`, `arcade`, `snes`, `nes`, `gameboy`, `retro`, `image`, `video` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Pixel Art
-
-Convert any image into retro pixel art, then optionally animate it into a short
-MP4 or GIF with era-appropriate effects (rain, fireflies, snow, embers).
-
-Two scripts ship with this skill:
-
-- `scripts/pixel_art.py` — photo → pixel-art PNG (Floyd-Steinberg dithering)
-- `scripts/pixel_art_video.py` — pixel-art PNG → animated MP4 (+ optional GIF)
-
-Each is importable or runnable directly. Presets snap to hardware palettes
-when you want era-accurate colors (NES, Game Boy, PICO-8, etc.), or use
-adaptive N-color quantization for arcade/SNES-style looks.
-
-## When to Use
-
-- User wants retro pixel art from a source image
-- User asks for NES / Game Boy / PICO-8 / C64 / arcade / SNES styling
-- User wants a short looping animation (rain scene, night sky, snow, etc.)
-- Posters, album covers, social posts, sprites, characters, avatars
-
-## Workflow
-
-Before generating, confirm the style with the user. Different presets produce
-very different outputs and regenerating is costly.
-
-### Step 1 — Offer a style
-
-Call `clarify` with 4 representative presets. Pick the set based on what the
-user asked for — don't just dump all 14.
-
-Default menu when the user's intent is unclear:
-
-```python
-clarify(
-    question="Which pixel-art style do you want?",
-    choices=[
-        "arcade — bold, chunky 80s cabinet feel (16 colors, 8px)",
-        "nes — Nintendo 8-bit hardware palette (54 colors, 8px)",
-        "gameboy — 4-shade green Game Boy DMG",
-        "snes — cleaner 16-bit look (32 colors, 4px)",
-    ],
-)
-```
-
-When the user already named an era (e.g. "80s arcade", "Gameboy"), skip
-`clarify` and use the matching preset directly.
-
-### Step 2 — Offer animation (optional)
-
-If the user asked for a video/GIF, or the output might benefit from motion,
-ask which scene:
-
-```python
-clarify(
-    question="Want to animate it? Pick a scene or skip.",
-    choices=[
-        "night — stars + fireflies + leaves",
-        "urban — rain + neon pulse",
-        "snow — falling snowflakes",
-        "skip — just the image",
-    ],
-)
-```
-
-Do NOT call `clarify` more than twice in a row. One for style, one for scene if
-animation is on the table. If the user explicitly asked for a specific style
-and scene in their message, skip `clarify` entirely.
-
-### Step 3 — Generate
-
-Run `pixel_art()` first; if animation was requested, chain into
-`pixel_art_video()` on the result.
-
-## Preset Catalog
-
-| Preset | Era | Palette | Block | Best for |
-|--------|-----|---------|-------|----------|
-| `arcade` | 80s arcade | adaptive 16 | 8px | Bold posters, hero art |
-| `snes` | 16-bit | adaptive 32 | 4px | Characters, detailed scenes |
-| `nes` | 8-bit | NES (54) | 8px | True NES look |
-| `gameboy` | DMG handheld | 4 green shades | 8px | Monochrome Game Boy |
-| `gameboy_pocket` | Pocket handheld | 4 grey shades | 8px | Mono GB Pocket |
-| `pico8` | PICO-8 | 16 fixed | 6px | Fantasy-console look |
-| `c64` | Commodore 64 | 16 fixed | 8px | 8-bit home computer |
-| `apple2` | Apple II hi-res | 6 fixed | 10px | Extreme retro, 6 colors |
-| `teletext` | BBC Teletext | 8 pure | 10px | Chunky primary colors |
-| `mspaint` | Windows MS Paint | 24 fixed | 8px | Nostalgic desktop |
-| `mono_green` | CRT phosphor | 2 green | 6px | Terminal/CRT aesthetic |
-| `mono_amber` | CRT amber | 2 amber | 6px | Amber monitor look |
-| `neon` | Cyberpunk | 10 neons | 6px | Vaporwave/cyber |
-| `pastel` | Soft pastel | 10 pastels | 6px | Kawaii / gentle |
-
-Named palettes live in `scripts/palettes.py` (see `references/palettes.md` for
-the complete list — 28 named palettes total). Any preset can be overridden:
-
-```python
-pixel_art("in.png", "out.png", preset="snes", palette="PICO_8", block=6)
-```
-
-## Scene Catalog (for video)
-
-| Scene | Effects |
-|-------|---------|
-| `night` | Twinkling stars + fireflies + drifting leaves |
-| `dusk` | Fireflies + sparkles |
-| `tavern` | Dust motes + warm sparkles |
-| `indoor` | Dust motes |
-| `urban` | Rain + neon pulse |
-| `nature` | Leaves + fireflies |
-| `magic` | Sparkles + fireflies |
-| `storm` | Rain + lightning |
-| `underwater` | Bubbles + light sparkles |
-| `fire` | Embers + sparkles |
-| `snow` | Snowflakes + sparkles |
-| `desert` | Heat shimmer + dust |
-
-## Invocation Patterns
-
-### Python (import)
-
-```python
-import sys
-import os
-sys.path.insert(0, os.path.expanduser("~/.hermes/skills/creative/pixel-art/scripts"))
-from pixel_art import pixel_art
-from pixel_art_video import pixel_art_video
-
-# 1. Convert to pixel art
-pixel_art("/path/to/photo.jpg", "/tmp/pixel.png", preset="nes")
-
-# 2. Animate (optional)
-pixel_art_video(
-    "/tmp/pixel.png",
-    "/tmp/pixel.mp4",
-    scene="night",
-    duration=6,
-    fps=15,
-    seed=42,
-    export_gif=True,
-)
-```
-
-### CLI
-
-```bash
-cd ~/.hermes/skills/creative/pixel-art/scripts
-
-python pixel_art.py in.jpg out.png --preset gameboy
-python pixel_art.py in.jpg out.png --preset snes --palette PICO_8 --block 6
-
-python pixel_art_video.py out.png out.mp4 --scene night --duration 6 --gif
-```
-
-## Pipeline Rationale
-
-**Pixel conversion:**
-1. Boost contrast/color/sharpness (stronger for smaller palettes)
-2. Posterize to simplify tonal regions before quantization
-3. Downscale by `block` with `Image.NEAREST` (hard pixels, no interpolation)
-4. Quantize with Floyd-Steinberg dithering — against either an adaptive
-   N-color palette OR a named hardware palette
-5. Upscale back with `Image.NEAREST`
-
-Quantizing AFTER downscale keeps dithering aligned with the final pixel grid.
-Quantizing before would waste error-diffusion on detail that disappears.
-
-**Video overlay:**
-- Copies the base frame each tick (static background)
-- Overlays stateless-per-frame particle draws (one function per effect)
-- Encodes via ffmpeg `libx264 -pix_fmt yuv420p -crf 18`
-- Optional GIF via `palettegen` + `paletteuse`
-
-## Dependencies
-
-- Python 3.9+
-- Pillow (`pip install Pillow`)
-- ffmpeg on PATH (only needed for video — Hermes installs package this)
-
-## Pitfalls
-
-- Pallet keys are case-sensitive (`"NES"`, `"PICO_8"`, `"GAMEBOY_ORIGINAL"`).
-- Very small sources (<100px wide) collapse under 8-10px blocks. Upscale the
-  source first if it's tiny.
-- Fractional `block` or `palette` will break quantization — keep them positive ints.
-- Animation particle counts are tuned for ~640x480 canvases. On very large
-  images you may want a second pass with a different seed for density.
-- `mono_green` / `mono_amber` force `color=0.0` (desaturate). If you override
-  and keep chroma, the 2-color palette can produce stripes on smooth regions.
-- `clarify` loop: call it at most twice per turn (style, then scene). Don't
-  pepper the user with more picks.
-
-## Verification
-
-- PNG is created at the output path
-- Clear square pixel blocks visible at the preset's block size
-- Color count matches preset (eyeball the image or run `Image.open(p).getcolors()`)
-- Video is a valid MP4 (`ffprobe` can open it) with non-zero size
-
-## Attribution
-
-Named hardware palettes and the procedural animation loops in `pixel_art_video.py`
-are ported from [pixel-art-studio](https://github.com/Synero/pixel-art-studio)
-(MIT). See `ATTRIBUTION.md` in this skill directory for details.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/creative/creative-pretext.md

@@ -1,238 +0,0 @@
----
-title: "Pretext — Build creative browser demos with DOM-free text layout"
-sidebar_label: "Pretext"
-description: "Build creative browser demos with DOM-free text layout"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Pretext
-
-Build creative browser demos with DOM-free text layout.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/creative/pretext` |
-| Path | `optional-skills/creative\pretext` |
-| Version | `1.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `creative-coding`, `typography`, `pretext`, `ascii-art`, `canvas`, `generative`, `text-layout`, `kinetic-typography` |
-| Related skills | [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Pretext Creative Demos
-
-## Overview
-
-[`@chenglou/pretext`](https://github.com/chenglou/pretext) is a 15KB zero-dependency TypeScript library by Cheng Lou (React core, ReasonML, Midjourney) for **DOM-free multiline text measurement and layout**. It does one thing: given `(text, font, width)`, return the line breaks, per-line widths, per-grapheme positions, and total height — all via canvas measurement, no reflow.
-
-That sounds like plumbing. It is not. Because it is fast and geometric, it is a **creative primitive**: you can reflow paragraphs around a moving sprite at 60fps, build games whose level geometry is made of real words, drive ASCII logos through prose, shatter text into particles with exact per-grapheme starting positions, or pack shrink-wrapped multiline UI without any `getBoundingClientRect` thrash.
-
-This skill exists so Hermes can make **cool demos** with it — the kind people post to X. See `pretext.cool` and `chenglou.me/pretext` for the community demo corpus.
-
-## When to Use
-
-Use when the user asks for:
-- A "pretext demo" / "cool pretext thing" / "text-as-X"
-- Text flowing around a moving shape (hero sections, editorial layouts, animated long-form pages)
-- ASCII-art effects using **real words or prose**, not monospace rasters
-- Games where the playfield / obstacles / bricks are made of text (Tetris-from-letters, Breakout-of-prose)
-- Kinetic typography with per-glyph physics (shatter, scatter, flock, flow)
-- Typographic generative art, especially with non-Latin scripts or mixed scripts
-- Multiline "shrink-wrap" UI (smallest container width that still fits the text)
-- Anything that would require knowing line breaks *before* rendering
-
-Don't use for:
-- Static SVG/HTML pages where CSS already solves layout — just use CSS
-- Rich text editors, general inline formatting engines (pretext is intentionally narrow)
-- Image → text (use `ascii-art` / `ascii-video` skills)
-- Pure canvas generative art with no text role — use `p5js`
-
-## Creative Standard
-
-This is visual art rendered in a browser. Pretext returns numbers; **you** draw the thing.
-
-- **Don't ship a "hello world" demo.** The `hello-orb-flow.html` template is the *starting* point. Every delivered demo must add intentional color, motion, composition, and one visual detail the user didn't ask for but will appreciate.
-- **Dark backgrounds, warm cores, considered palette.** Classic amber-on-black (CRT / terminal) works, but so do cold-white-on-charcoal (editorial) and desaturated pastels (risograph). Pick one and commit.
-- **Proportional fonts are the point.** Pretext's whole vibe is "not monospaced" — lean into it. Use Iowan Old Style, Inter, JetBrains Mono, Helvetica Neue, or a variable font. Never default sans.
-- **Real source/text, not lorem ipsum.** The corpus should mean something. Short manifestos, poetry, real source code, a found text, the library's own README — never `lorem ipsum`.
-- **First-paint excellence.** No loading states, no blank frames. The demo must look shippable the instant it opens.
-
-## Stack
-
-Single self-contained HTML file per demo. No build step.
-
-| Layer | Tool | Purpose |
-|-------|------|---------|
-| Core | `@chenglou/pretext` via `esm.sh` CDN | Text measurement + line layout |
-| Render | HTML5 Canvas 2D | Glyph rendering, per-frame composition |
-| Segmentation | `Intl.Segmenter` (built-in) | Grapheme splitting for emoji / CJK / combining marks |
-| Interaction | Raw DOM events | Mouse / touch / wheel — no framework |
-
-```html
-<script type="module">
-import {
-  prepare, layout,                   // use-case 1: simple height
-  prepareWithSegments, layoutWithLines,  // use-case 2a: fixed-width lines
-  layoutNextLineRange, materializeLineRange, // use-case 2b: streaming / variable width
-  measureLineStats, walkLineRanges,  // stats without string allocation
-} from "https://esm.sh/@chenglou/pretext@0.0.6";
-</script>
-```
-
-Pin the version. `@0.0.6` at time of writing — check [npm](https://www.npmjs.com/package/@chenglou/pretext) for the latest if demo behavior is off.
-
-## The Two Use Cases
-
-Almost everything reduces to one of these two shapes. Learn both.
-
-### Use-case 1 — measure, then render with CSS/DOM
-
-```js
-const prepared = prepare(text, "16px Inter");
-const { height, lineCount } = layout(prepared, 320, 20);
-```
-
-You still let the browser draw the text. Pretext just tells you how tall the box will be at a given width, **without** a DOM read. Use for:
-- Virtualized lists where rows contain wrapping text
-- Masonry with precise card heights
-- "Does this label fit?" dev-time checks
-- Preventing layout shift when remote text loads
-
-**Keep `font` and `letterSpacing` exactly in sync with your CSS.** The canvas `ctx.font` format (e.g. `"16px Inter"`, `"500 17px 'JetBrains Mono'"`) must match the rendered CSS, or measurements drift.
-
-### Use-case 2 — measure *and* render yourself
-
-```js
-const prepared = prepareWithSegments(text, FONT);
-const { lines } = layoutWithLines(prepared, 320, 26);
-for (let i = 0; i < lines.length; i++) {
-  ctx.fillText(lines[i].text, 0, i * 26);
-}
-```
-
-This is where the creative work lives. You own the drawing, so you can:
-- Render to canvas, SVG, WebGL, or any coordinate system
-- Substitute per-glyph transforms (rotation, jitter, scale, opacity)
-- Use line metadata (width, grapheme positions) as geometry
-
-For **variable-width-per-line** flow (text around a shape, text in a donut band, text in a non-rectangular column):
-
-```js
-let cursor = { segmentIndex: 0, graphemeIndex: 0 };
-let y = 0;
-while (true) {
-  const lineWidth = widthAtY(y);  // your function: how wide is the corridor at this y?
-  const range = layoutNextLineRange(prepared, cursor, lineWidth);
-  if (!range) break;
-  const line = materializeLineRange(prepared, range);
-  ctx.fillText(line.text, leftEdgeAtY(y), y);
-  cursor = range.end;
-  y += lineHeight;
-}
-```
-
-This is the most important pattern in the whole library. It's what unlocks "text flowing around a dragged sprite" — the demo that went viral on X.
-
-### Helpers worth knowing
-
-- `measureLineStats(prepared, maxWidth)` → `{ lineCount, maxLineWidth }` — the widest line, i.e. multiline shrink-wrap width.
-- `walkLineRanges(prepared, maxWidth, callback)` — iterate lines without allocating strings. Use for stats/physics over graphemes when you don't need the characters.
-- `@chenglou/pretext/rich-inline` — the same system but for paragraphs mixing fonts / chips / mentions. Import from the subpath.
-
-## Demo Recipe Patterns
-
-The community corpus (see `references/patterns.md`) clusters into a handful of strong patterns. Pick one and riff — don't invent a new category unless asked.
-
-| Pattern | Key API | Example idea |
-|---|---|---|
-| **Reflow around obstacle** | `layoutNextLineRange` + per-row width function | Editorial paragraph that parts around a dragged cursor sprite |
-| **Text-as-geometry game** | `layoutWithLines` + per-line collision rects | Breakout where each brick is a measured word |
-| **Shatter / particles** | `walkLineRanges` → per-grapheme (x,y) → physics | Sentence that explodes into letters on click |
-| **ASCII obstacle typography** | `layoutNextLineRange` + measured per-row obstacle spans | Bitmap ASCII logo, shape morphs, and draggable wire objects that make text open around their actual geometry |
-| **Editorial multi-column** | `layoutNextLineRange` per column + shared cursor | Animated magazine spread with pull quotes |
-| **Kinetic type** | `layoutWithLines` + per-line transform over time | Star Wars crawl, wave, bounce, glitch |
-| **Multiline shrink-wrap** | `measureLineStats` | Quote card that auto-sizes to its tightest container |
-
-See `templates/donut-orbit.html` and `templates/hello-orb-flow.html` for working single-file starters.
-
-## Workflow
-
-1. **Pick a pattern** from the table above based on the user's brief.
-2. **Start from a template**:
-   - `templates/hello-orb-flow.html` — text reflowing around a moving orb (reflow-around-obstacle pattern)
-   - `templates/donut-orbit.html` — advanced example: measured ASCII logo obstacles, draggable wire sphere/cube, morphing shape fields, selectable DOM text, and dev-only controls
-   - `write_file` to a new `.html` in `/tmp/` or the user's workspace.
-3. **Swap the corpus** for something intentional to the brief. Real prose, 10-100 sentences, no lorem.
-4. **Tune the aesthetic** — font, palette, composition, interaction. This is the work; don't skip it.
-5. **Verify locally**:
-   ```sh
-   cd <dir-with-html> && python -m http.server 8765
-   # then open http://localhost:8765/<file>.html
-   ```
-6. **Check the console** — pretext will throw if `prepareWithSegments` is called with a bad font string; `Intl.Segmenter` is available in every modern browser.
-7. **Show the user the file path**, not just the code — they want to open it.
-
-## Performance Notes
-
-- `prepare()` / `prepareWithSegments()` is the expensive call. Do it **once** per text+font pair. Cache the handle.
-- On resize, only rerun `layout()` / `layoutWithLines()` — never re-prepare.
-- For per-frame animations where text doesn't change but geometry does, `layoutNextLineRange` in a tight loop is cheap enough to do every frame at 60fps for normal-length paragraphs.
-- When rendering ASCII masks per frame, keep a cell buffer (`Uint8Array`/typed arrays), derive measured per-row obstacle spans from the cells or projected geometry, merge spans, then feed those spans into `layoutNextLineRange` before drawing text.
-- Keep visual animation and layout animation coupled. If a sphere morphs into a cube, tween both the rendered cell buffer and the obstacle spans with the same value; otherwise the demo looks painted-on instead of physically reflowed.
-- For fades, prefer layer opacity over changing glyph intensity or obstacle scale. Put transient ASCII sprites on their own canvas and fade the canvas with CSS/GSAP opacity so geometry does not appear to shrink.
-- Canvas `ctx.font` setting is surprisingly slow; set it **once** per frame if font doesn't vary, not per `fillText` call.
-
-## Common Pitfalls
-
-1. **Drifting CSS/canvas font strings.** `ctx.font = "16px Inter"` measured, but CSS says `font-family: Inter, sans-serif; font-size: 16px`. Fine *if* Inter loads. If Inter 404s, CSS falls back to sans-serif and measurements drift by 5-20%. Always `preload` the font or use a web-safe family.
-
-2. **Re-preparing inside the animation loop.** Only `layout*` is cheap. Re-calling `prepare` every frame will tank perf. Keep the prepared handle in module scope.
-
-3. **Forgetting `Intl.Segmenter` for grapheme splits.** Emoji, combining marks, CJK — `"é".split("")` gives you two chars. Use `new Intl.Segmenter(undefined, { granularity: "grapheme" })` when sampling individual visible glyphs.
-
-4. **`break: 'never'` chips without `extraWidth`.** In `rich-inline`, if you use `break: 'never'` for an atomic chip/mention, you must also supply `extraWidth` for the pill padding — otherwise chip chrome overflows the container.
-
-5. **Using `@chenglou/pretext` from `unpkg` with TypeScript-only entry.** Use `esm.sh` — it compiles the TS exports to browser-ready ESM automatically. `unpkg` will 404 or serve raw TS.
-
-6. **Monospace fallbacks silently erasing the whole point.** Users seeing monospace-looking output often have a CSS `font-family` that fell through to `monospace`. Verify the actual rendered font via DevTools.
-
-7. **Skipping rows vs adjusting width** when flowing around a shape. If the corridor on this row is too narrow to fit a line, *skip the row* (`y += lineHeight; continue;`) rather than passing a tiny maxWidth to `layoutNextLineRange` — pretext will return one-grapheme lines that look broken.
-
-8. **Shipping a cold demo.** The default first-paint looks tutorial-grade. Add: vignette, subtle scanline, idle auto-motion, one carefully chosen interactive response (drag, hover, scroll, click). Without these, "cool pretext demo" lands as "intern repro of the README."
-
-## Verification Checklist
-
-- [ ] Demo is a single self-contained `.html` file — opens by double-click or `python -m http.server`
-- [ ] `@chenglou/pretext` imported via `esm.sh` with pinned version
-- [ ] Corpus is real prose, not lorem ipsum, and matches the demo's concept
-- [ ] Font string passed to `prepare` matches the CSS font exactly
-- [ ] `prepare()` / `prepareWithSegments()` called once, not per frame
-- [ ] Dark background + considered palette — not the default white canvas
-- [ ] At least one interactive response (drag / hover / scroll / click) or idle auto-motion
-- [ ] Tested locally with `python -m http.server` and confirmed no console errors
-- [ ] 60fps on a mid-tier laptop (or graceful degradation documented)
-- [ ] One "extra mile" detail the user didn't ask for
-
-## Reference: Community Demos
-
-Clone these for inspiration / patterns (all MIT-ish, linked from [pretext.cool](https://www.pretext.cool/)):
-
-- **Pretext Breaker** — breakout with word-bricks — `github.com/rinesh/pretext-breaker`
-- **Tetris × Pretext** — `github.com/shinichimochizuki/tetris-pretext`
-- **Dragon animation** — `github.com/qtakmalay/PreTextExperiments`
-- **Somnai editorial engine** — `github.com/somnai-dreams/pretext-demos`
-- **Bad Apple!! ASCII** — `github.com/frmlinn/bad-apple-pretext`
-- **Drag-sprite reflow** — `github.com/dokobot/pretext-demo`
-- **Alarmy editorial clock** — `github.com/SmisLee/alarmy-pretext-demo`
-
-Official playground: [chenglou.me/pretext](https://chenglou.me/pretext/) — accordion, bubbles, dynamic-layout, editorial-engine, justification-comparison, masonry, markdown-chat, rich-note.