better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/creative/creative-popular-web-designs.md

@@ -0,0 +1,223 @@
+---
+title: "Popular Web Designs — 54 real design systems (Stripe, Linear, Vercel) as HTML/CSS"
+sidebar_label: "Popular Web Designs"
+description: "54 real design systems (Stripe, Linear, Vercel) as HTML/CSS"
+---
+
+{/* 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. */}
+
+# Popular Web Designs
+
+54 real design systems (Stripe, Linear, Vercel) as HTML/CSS.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/creative\popular-web-designs` |
+| Version | `1.0.0` |
+| Author | Hermes Agent + Teknium (design systems sourced from VoltAgent/awesome-design-md) |
+| License | MIT |
+| Platforms | linux, macos, windows |
+
+## 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.
+:::
+
+# Popular Web Designs
+
+54 real-world design systems ready for use when generating HTML/CSS. Each template captures a
+site's complete visual language: color palette, typography hierarchy, component styles, spacing
+system, shadows, responsive behavior, and practical agent prompts with exact CSS values.
+
+## Related design skills
+
+- **`claude-design`** — use for the design *process and taste* (scoping a brief,
+  producing variants, verifying a local HTML artifact, avoiding AI-design slop).
+  Pair it with this skill when the user wants a thoughtfully-designed page styled
+  after a known brand: `claude-design` drives the workflow, this skill supplies
+  the visual vocabulary.
+- **`design-md`** — use when the deliverable is a formal DESIGN.md token spec
+  file, not a rendered artifact.
+
+## How to Use
+
+1. Pick a design from the catalog below
+2. Load it: `skill_view(name="popular-web-designs", file_path="templates/<site>.md")`
+3. Use the design tokens and component specs when generating HTML
+4. Pair with the `generative-widgets` skill to serve the result via cloudflared tunnel
+
+Each template includes a **Hermes Implementation Notes** block at the top with:
+- CDN font substitute and Google Fonts `<link>` tag (ready to paste)
+- CSS font-family stacks for primary and monospace
+- Reminders to use `write_file` for HTML creation and `browser_vision` for verification
+
+## HTML Generation Pattern
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Page Title</title>
+  <!-- Paste the Google Fonts <link> from the template's Hermes notes -->
+  <link href="https://fonts.googleapis.com/css2?family=..." rel="stylesheet">
+  <style>
+    /* Apply the template's color palette as CSS custom properties */
+    :root {
+      --color-bg: #ffffff;
+      --color-text: #171717;
+      --color-accent: #533afd;
+      /* ... more from template Section 2 */
+    }
+    /* Apply typography from template Section 3 */
+    body {
+      font-family: 'Inter', system-ui, sans-serif;
+      color: var(--color-text);
+      background: var(--color-bg);
+    }
+    /* Apply component styles from template Section 4 */
+    /* Apply layout from template Section 5 */
+    /* Apply shadows from template Section 6 */
+  </style>
+</head>
+<body>
+  <!-- Build using component specs from the template -->
+</body>
+</html>
+```
+
+Write the file with `write_file`, serve with the `generative-widgets` workflow (cloudflared tunnel),
+and verify the result with `browser_vision` to confirm visual accuracy.
+
+## Font Substitution Reference
+
+Most sites use proprietary fonts unavailable via CDN. Each template maps to a Google Fonts
+substitute that preserves the design's character. Common mappings:
+
+| Proprietary Font | CDN Substitute | Character |
+|---|---|---|
+| Geist / Geist Sans | Geist (on Google Fonts) | Geometric, compressed tracking |
+| Geist Mono | Geist Mono (on Google Fonts) | Clean monospace, ligatures |
+| sohne-var (Stripe) | Source Sans 3 | Light weight elegance |
+| Berkeley Mono | JetBrains Mono | Technical monospace |
+| Airbnb Cereal VF | DM Sans | Rounded, friendly geometric |
+| Circular (Spotify) | DM Sans | Geometric, warm |
+| figmaSans | Inter | Clean humanist |
+| Pin Sans (Pinterest) | DM Sans | Friendly, rounded |
+| NVIDIA-EMEA | Inter (or Arial system) | Industrial, clean |
+| CoinbaseDisplay/Sans | DM Sans | Geometric, trustworthy |
+| UberMove | DM Sans | Bold, tight |
+| HashiCorp Sans | Inter | Enterprise, neutral |
+| waldenburgNormal (Sanity) | Space Grotesk | Geometric, slightly condensed |
+| IBM Plex Sans/Mono | IBM Plex Sans/Mono | Available on Google Fonts |
+| Rubik (Sentry) | Rubik | Available on Google Fonts |
+
+When a template's CDN font matches the original (Inter, IBM Plex, Rubik, Geist), no
+substitution loss occurs. When a substitute is used (DM Sans for Circular, Source Sans 3
+for sohne-var), follow the template's weight, size, and letter-spacing values closely —
+those carry more visual identity than the specific font face.
+
+## Design Catalog
+
+### AI & Machine Learning
+
+| Template | Site | Style |
+|---|---|---|
+| `claude.md` | Anthropic Claude | Warm terracotta accent, clean editorial layout |
+| `cohere.md` | Cohere | Vibrant gradients, data-rich dashboard aesthetic |
+| `elevenlabs.md` | ElevenLabs | Dark cinematic UI, audio-waveform aesthetics |
+| `minimax.md` | Minimax | Bold dark interface with neon accents |
+| `mistral.ai.md` | Mistral AI | French-engineered minimalism, purple-toned |
+| `ollama.md` | Ollama | Terminal-first, monochrome simplicity |
+| `opencode.ai.md` | OpenCode AI | Developer-centric dark theme, full monospace |
+| `replicate.md` | Replicate | Clean white canvas, code-forward |
+| `runwayml.md` | RunwayML | Cinematic dark UI, media-rich layout |
+| `together.ai.md` | Together AI | Technical, blueprint-style design |
+| `voltagent.md` | VoltAgent | Void-black canvas, emerald accent, terminal-native |
+| `x.ai.md` | xAI | Stark monochrome, futuristic minimalism, full monospace |
+
+### Developer Tools & Platforms
+
+| Template | Site | Style |
+|---|---|---|
+| `cursor.md` | Cursor | Sleek dark interface, gradient accents |
+| `expo.md` | Expo | Dark theme, tight letter-spacing, code-centric |
+| `linear.app.md` | Linear | Ultra-minimal dark-mode, precise, purple accent |
+| `lovable.md` | Lovable | Playful gradients, friendly dev aesthetic |
+| `mintlify.md` | Mintlify | Clean, green-accented, reading-optimized |
+| `posthog.md` | PostHog | Playful branding, developer-friendly dark UI |
+| `raycast.md` | Raycast | Sleek dark chrome, vibrant gradient accents |
+| `resend.md` | Resend | Minimal dark theme, monospace accents |
+| `sentry.md` | Sentry | Dark dashboard, data-dense, pink-purple accent |
+| `supabase.md` | Supabase | Dark emerald theme, code-first developer tool |
+| `superhuman.md` | Superhuman | Premium dark UI, keyboard-first, purple glow |
+| `vercel.md` | Vercel | Black and white precision, Geist font system |
+| `warp.md` | Warp | Dark IDE-like interface, block-based command UI |
+| `zapier.md` | Zapier | Warm orange, friendly illustration-driven |
+
+### Infrastructure & Cloud
+
+| Template | Site | Style |
+|---|---|---|
+| `clickhouse.md` | ClickHouse | Yellow-accented, technical documentation style |
+| `composio.md` | Composio | Modern dark with colorful integration icons |
+| `hashicorp.md` | HashiCorp | Enterprise-clean, black and white |
+| `mongodb.md` | MongoDB | Green leaf branding, developer documentation focus |
+| `sanity.md` | Sanity | Red accent, content-first editorial layout |
+| `stripe.md` | Stripe | Signature purple gradients, weight-300 elegance |
+
+### Design & Productivity
+
+| Template | Site | Style |
+|---|---|---|
+| `airtable.md` | Airtable | Colorful, friendly, structured data aesthetic |
+| `cal.md` | Cal.com | Clean neutral UI, developer-oriented simplicity |
+| `clay.md` | Clay | Organic shapes, soft gradients, art-directed layout |
+| `figma.md` | Figma | Vibrant multi-color, playful yet professional |
+| `framer.md` | Framer | Bold black and blue, motion-first, design-forward |
+| `intercom.md` | Intercom | Friendly blue palette, conversational UI patterns |
+| `miro.md` | Miro | Bright yellow accent, infinite canvas aesthetic |
+| `notion.md` | Notion | Warm minimalism, serif headings, soft surfaces |
+| `pinterest.md` | Pinterest | Red accent, masonry grid, image-first layout |
+| `webflow.md` | Webflow | Blue-accented, polished marketing site aesthetic |
+
+### Fintech & Crypto
+
+| Template | Site | Style |
+|---|---|---|
+| `coinbase.md` | Coinbase | Clean blue identity, trust-focused, institutional feel |
+| `kraken.md` | Kraken | Purple-accented dark UI, data-dense dashboards |
+| `revolut.md` | Revolut | Sleek dark interface, gradient cards, fintech precision |
+| `wise.md` | Wise | Bright green accent, friendly and clear |
+
+### Enterprise & Consumer
+
+| Template | Site | Style |
+|---|---|---|
+| `airbnb.md` | Airbnb | Warm coral accent, photography-driven, rounded UI |
+| `apple.md` | Apple | Premium white space, SF Pro, cinematic imagery |
+| `bmw.md` | BMW | Dark premium surfaces, precise engineering aesthetic |
+| `ibm.md` | IBM | Carbon design system, structured blue palette |
+| `nvidia.md` | NVIDIA | Green-black energy, technical power aesthetic |
+| `spacex.md` | SpaceX | Stark black and white, full-bleed imagery, futuristic |
+| `spotify.md` | Spotify | Vibrant green on dark, bold type, album-art-driven |
+| `uber.md` | Uber | Bold black and white, tight type, urban energy |
+
+## Choosing a Design
+
+Match the design to the content:
+
+- **Developer tools / dashboards:** Linear, Vercel, Supabase, Raycast, Sentry
+- **Documentation / content sites:** Mintlify, Notion, Sanity, MongoDB
+- **Marketing / landing pages:** Stripe, Framer, Apple, SpaceX
+- **Dark mode UIs:** Linear, Cursor, ElevenLabs, Warp, Superhuman
+- **Light / clean UIs:** Vercel, Stripe, Notion, Cal.com, Replicate
+- **Playful / friendly:** PostHog, Figma, Lovable, Zapier, Miro
+- **Premium / luxury:** Apple, BMW, Stripe, Superhuman, Revolut
+- **Data-dense / dashboards:** Sentry, Kraken, Cohere, ClickHouse
+- **Monospace / terminal aesthetic:** Ollama, OpenCode, x.ai, VoltAgent

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/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 | Bundled (installed by default) |
+| Path | `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/bundled/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> && python3 -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 `python3 -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 `python3 -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.