better-dsh 0.2.4 → 0.2.5-a

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

@@ -0,0 +1,158 @@
+---
+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

@@ -0,0 +1,234 @@
+---
+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

@@ -0,0 +1,238 @@
+---
+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.