Skip to content

skywain/trip-planner-skill

trip-planner

Unverified

End-to-end international trip planning: turns "I want to go to X for N days" into a verified, bookable plan — route skeleton across cities, flight price scans (international + domestic legs), train-vs-fly decisions, hour-by-hour daily timelines with opening hours, dwell times, holiday collisions and tappable turn-by-turn map links (小时级行程+地图导航+离线KML), hotel shortlists by neighborhood, budget rollup, and a booking checklist with deep links. Use this whenever the user asks to plan a trip, vacation, itinerary or honeymoon, compare flight dates/prices, pick between cities or routes, schedule a travel day hour by hour, fill a spare block of time ("I'm near X with 2 free hours"), turn a finished plan into a designed page (eight themed renders: illustrated / clay / noir / glass / journal / zine / splash / portal — 插画/黏土/夜航/玻璃/手账/Zine/闪屏/穿越版), or asks 旅行规划/行程安排/机票比价/去某国玩N天怎么安排/现在有空档干嘛/把行程做成好看的网页 — even if they only mention one piece (just flights, just hotels, or just navigation), the playbook and verification rules here still apply.

FileKindSize
SKILL.mdskill md32.9 KB
assets/plan.example.jsonconfig12.1 KB
examples/README.mdmarkdown13.0 KB
examples/china-2026/china-splash.htmlother937.1 KB
examples/china-2026/china.art.jsonconfig6.4 KB
examples/china-2026/china.geo.jsonconfig58.3 KB
examples/fixtures/bad/bracketed-note.geo.jsonconfig7.8 KB
examples/fixtures/bad/brief-card-not-text.geo.jsonconfig943 B
examples/fixtures/bad/decision-point-date-two-days-before.geo.jsonconfig848 B
examples/fixtures/bad/decision-point-day-date-not-iso.geo.jsonconfig7.8 KB
examples/fixtures/bad/decision-point-no-if-no.geo.jsonconfig715 B
examples/fixtures/bad/decision-point-same-what.geo.jsonconfig8.2 KB
examples/fixtures/bad/decision-point-src-not-http.geo.jsonconfig803 B
examples/fixtures/bad/decision-point-t-not-hhmm.geo.jsonconfig764 B
examples/fixtures/bad/decision-points-null.geo.jsonconfig594 B
examples/fixtures/bad/driver-enum.geo.jsonconfig711 B
examples/fixtures/bad/driver-self-no-driving-card.geo.jsonconfig736 B
examples/fixtures/bad/driving-card-no-as-of.geo.jsonconfig861 B
examples/fixtures/bad/driving-card-no-desk.geo.jsonconfig800 B
examples/fixtures/bad/driving-card-no-legality-line.geo.jsonconfig811 B
examples/fixtures/bad/driving-card-no-verdict.geo.jsonconfig939 B
examples/fixtures/bad/driving-card-zh-verdict-trailing.geo.jsonconfig967 B
examples/fixtures/bad/hotel-checkout-null.geo.jsonconfig786 B
examples/fixtures/bad/hours-as-of-not-date.geo.jsonconfig674 B
examples/fixtures/bad/hours-bare-string.geo.jsonconfig655 B
examples/fixtures/bad/hours-src-not-http.geo.jsonconfig662 B
examples/fixtures/bad/hours-text-empty.geo.jsonconfig647 B
examples/fixtures/bad/kind-enum.geo.jsonconfig7.9 KB
examples/fixtures/bad/must-false.geo.jsonconfig914 B
examples/fixtures/bad/must-no-stand.geo.jsonconfig755 B
examples/fixtures/bad/must-no-view.geo.jsonconfig758 B
examples/fixtures/bad/must-not-boolean.geo.jsonconfig798 B
examples/fixtures/bad/must-see-unmatched.geo.jsonconfig963 B
examples/fixtures/bad/must-see-view-empty.geo.jsonconfig910 B
examples/fixtures/bad/pending-no-checklist-row.geo.jsonconfig1021 B
examples/fixtures/bad/refundable-not-boolean.geo.jsonconfig686 B
examples/fixtures/bad/rental-leg-no-driving-card.geo.jsonconfig829 B
examples/fixtures/bad/review-counts-disagree.geo.jsonconfig1.0 KB
examples/fixtures/bad/review-lens-enum.geo.jsonconfig1.1 KB
examples/fixtures/bad/review-no-driving-lens.geo.jsonconfig1.3 KB
examples/fixtures/bad/review-not-object.geo.jsonconfig611 B
examples/fixtures/bad/review-single-pass-with-counts.geo.jsonconfig1.0 KB
examples/fixtures/bad/review-two-lenses.geo.jsonconfig959 B
examples/fixtures/bad/self-drive-no-driving-card.geo.jsonconfig635 B
examples/fixtures/bad/sub-stop-no-name.geo.jsonconfig763 B
examples/fixtures/bad/sub-stop-no-query.geo.jsonconfig763 B
examples/fixtures/bad/sub-stops-null.geo.jsonconfig578 B
examples/fixtures/bad/tour-confirmed-prefix.geo.jsonconfig902 B
examples/fixtures/bad/tour-not-boolean.geo.jsonconfig562 B
examples/fixtures/bad/tour-on-day-object.geo.jsonconfig7.8 KB
examples/fixtures/bad/tour-unconfirmed.geo.jsonconfig837 B
examples/fixtures/strict/clean.plan.geo.jsonconfig4.5 KB
examples/fixtures/strict/hours-as-of-after-asof.geo.jsonconfig4.1 KB
examples/fixtures/strict/hours-missing-in-window.geo.jsonconfig4.0 KB
examples/fixtures/strict/hours-stale-as-of.geo.jsonconfig4.1 KB
examples/fixtures/strict/no-generated.geo.jsonconfig3.8 KB
examples/fixtures/strict/refundable-no-clause.geo.jsonconfig3.8 KB
examples/fixtures/strict/rows-without-clock-or-kind.geo.jsonconfig3.7 KB
examples/fixtures/strict/self-drive-not-legal-no-decision.geo.jsonconfig4.4 KB
examples/fixtures/strict/t-n-date-mismatch.geo.jsonconfig3.8 KB
examples/fixtures/strict/tour-no-review.geo.jsonconfig3.4 KB
examples/fixtures/substops.plan.geo.jsonconfig9.1 KB
examples/gates-sample.icsother11.5 KB
examples/japan-2026/japan-illustrated.htmlother1.4 MB
examples/japan-2026/japan.art.jsonconfig6.2 KB
examples/japan-2026/japan.geo.jsonconfig65.5 KB
examples/kyoto-sample.htmlother13.0 KB
examples/kyoto-sample.kmlother1012 B
examples/kyoto-sample.plan.geo.jsonconfig7.2 KB
examples/mexico-2026/mexico-journal.htmlother2.0 MB
examples/mexico-2026/mexico.art.jsonconfig9.4 KB
examples/mexico-2026/mexico.geo.jsonconfig77.1 KB
examples/morocco-2026/morocco-glass.htmlother1.3 MB
examples/morocco-2026/morocco-portal.htmlother13.8 KB
examples/morocco-2026/morocco.art.jsonconfig3.8 KB
examples/morocco-2026/morocco.geo.jsonconfig85.1 KB
examples/nordic-2026/nordic-noir.htmlother686.8 KB
examples/nordic-2026/nordic.art.jsonconfig8.7 KB
examples/nordic-2026/nordic.geo.jsonconfig58.5 KB
examples/turkey-2026/turkey-clay.htmlother1.3 MB
examples/turkey-2026/turkey.art.jsonconfig3.5 KB
examples/turkey-2026/turkey.geo.jsonconfig75.8 KB
examples/vietnam-2026/vietnam-zine.htmlother2.5 MB
examples/vietnam-2026/vietnam.art.jsonconfig10.8 KB
examples/vietnam-2026/vietnam.geo.jsonconfig85.1 KB
references/art-schema.mdmarkdown318 B
references/country-quick-notes.mdmarkdown58.6 KB
references/cover-titles.mdmarkdown10.6 KB
references/data-sources.mdmarkdown49.2 KB
references/navigation.mdmarkdown23.6 KB
references/output-template.mdmarkdown49.2 KB
references/phase-0-intake.mdmarkdown12.4 KB
references/phase-1-brief.mdmarkdown22.8 KB
references/phase-3-legs.mdmarkdown10.5 KB
references/phase-4-days.mdmarkdown13.6 KB
references/phase-6-assemble.mdmarkdown22.3 KB
references/scheduling.mdmarkdown28.8 KB
references/themes.mdmarkdown37.9 KB
scripts/build_site.pyscript47.8 KB
scripts/flight_scan.pyscript18.9 KB
scripts/plan_lint.pyscript58.4 KB
scripts/render_plan.pyscript28.2 KB
scripts/route_tools.pyscript90.0 KB

references/themes.md

View on GitHub
# Themed renders — the manual

Read this before rendering any theme, and all of it before touching a renderer.
Written for an AI that meets the theme system for the first time. **A themed page is
the deliverable** — SKILL.md Phase 6: the plan ships as `trip-<theme>.html` in the theme
chosen at Phase 0 (`prefs.theme`, default **illustrated 插画版**) plus `trip.kml`, and a
plain text page is never what the user gets. The plain `scripts/render_plan.py` page is
an **extra** — the printable version on request, or the last resort after one honest fix
attempt at the theme renderer. A session with no image generator and no key does not
fall back to that plain page either: it renders a theme from the built-in stock kit
(§3b).

## 1. The model in one paragraph

A themed page = **plan** (`plan.geo.json`, the facts) + **art** (`plan.art.json`, what
this trip looks and sounds like in a theme: titles, captions, which pictures) +
**renderer** (`themes/render_<x>.py`, the theme's craft — layout, type, colour,
motion; it knows nothing about any particular trip). The one rule for what goes
where: *anything that names this trip's places, dates, people, jokes or picture
files lives in art.json; the theme's own vocabulary (its tape kit, stamp mechanics,
doodle sketches, layout rhythm) stays in the renderer as a named kit that art picks
from and supplies words to.* Every art field is optional and every renderer must
produce a usable page from an empty art file — never a crash, never a line that
belongs to another trip. The full field contract is `themes/ART-SCHEMA.md` (the only
authoritative copy; `references/art-schema.md` just points there).

Commands (all relative to the skill root):

```
python3 themes/render_<x>.py plan.geo.json [--art F|none] [--assets DIR ...] -o out.html
python3 themes/qc.py out.html                       # exit code = number of FAILs
themes/xprobe.sh out.html module '#d5' out.png      # click the real export button, rasterise it
themes/xprobe.sh out.html page   ''    out.png      # whole-page export (ANCHOR=bottom → last 2600px)
themes/xt.sh    out.html module '#d5'               # title-only probe, ~25 s, no picture
python3 themes/render_picker.py plan.geo.json -o picker.html [--products DIR] [--prefix NAME]
    # the style-chooser page; expects the eight pages as {prefix}-{theme}.html
    # with the English theme key (japan-illustrated.html; pages exported under
    # the old Chinese tag — e.g. -插画版.html — still resolve). prefix defaults
    # to cover.kick_en with spaces→"-"
```

Assets are looked up by `theme_common.data_uri(stem, size)` in this order: every
`--assets DIR` (later wins) → the art file's directory → the plan's directory →
`themes/assets/`. So a trip keeps its own webp beside its plan and copies nothing
into the library; prefix trip assets with the trip name (`au-…`, `nordic-…`) so a
library size-variant can never shadow them. Only webp is ever embedded (as data
URIs — pages open by double-click, zero fetches); png originals never enter a page.

## 2. The eight themes

Each theme is a different *species*, not a re-skin. The four axes that keep them
apart (a new theme has to answer all four differently): organising principle ·
interaction · type voice · shape language. Renderer docstrings carry the full ART
contract; this is the field guide.

### illustrated 插画 — `render_theme2.py`
- Paradigm: a **painted book on paper** — one long paper scroll, full-width colour
  bands between chapters, pictures as the page's background rather than framed cards.
- Voice/shape: **zero monospace**, serif with lining numerals; no capsules — 〔square
  bracket〕 annotations, underlined pinned items, footnote `[n]`, printer's rules;
  page-edge bookmark tabs as navigation.
- Art (`themes.illustrated`): `cover.zh/en/credit/sub`, `cover.hero` (full-bleed
  cover painting), `end.hero` (endcap cut-out) + `end.fine`, `days[d].hero` (one
  cut-out stem, inlined as sm/md/lg into menu card / plate sticker / faint backdrop),
  `days[d].feature` (wide menu card). Kit: paper palette, four plate tints cycled by
  day, sticker tilt and backdrop side alternating by day parity.
- Limits: the fine print prints the full date, so `end.fine` is overridden per theme.

### clay 黏土 — `render_clay2.py`
- Paradigm: **one continuous clay landscape** — a road runs the whole page and is
  anchored to the milestone stones; terrain bands (cut-out strips with negative
  margins) and chained gradients make chapters bite into each other.
- Voice/shape: hand-pinched irregular radii (the same curve as the stones); the
  signature only clay can do — a **mini-road navigator** (the world path redrawn into
  300×44, stones are the hit areas).
- Art (`themes.clay`): `cover.zh/sub`, `cover.title_stem` (3-D clay title sticker;
  absent → embossed text h1), `zones` (`from_day` = day number or ISO date, `kind` ∈
  the neutral SVG kit ridge|plain|coast|forest|lake|desert, or `custom` with your own
  `{band, to, decor}` — the copy-able three-zone recipe is in ART-SCHEMA's clay block;
  city|park|west|isle are the US-2026 bands), `days[d].figurine`. Every clay picture
  slot is a cut-out.
- Limits: `zones` is where the terrain changes; an unknown kind falls back to ridge
  with one stderr warning.

### noir 夜航 — `render_noir2.py`
- Paradigm: **one unbroken tracking shot** — a single sticky 100svh night negative;
  days scroll over it, the plate cross-dissolves only inside the hop interstitial
  between two days; a travelling amber glow tracks trip progress; titles are burned
  into the negative (`mix-blend-mode:overlay`) and glide aside as body text arrives.
- Voice/shape: **monospace as body**, serif only for the giant title (the inverse of
  illustrated); no boxes — hairlines and letterspaced labels; bottom numbered rail.
- Art (`themes.noir`): `cover.zh/en/credit`, `plates` (stems in reel order, `[0]` =
  cover), `day_plate` (`{"<ISO date>"|"<day no>": plate index}`; date keys survive
  inserting a day). No plates → flat gradient, no photos, no AI credit line.
- Limits: **module-only export** (day / appendix blocks; a sticky stage cannot be
  flattened into a whole-page image).

### glass 玻璃 — `render_glass2.py`
- Paradigm: **Liquid Glass** — frosted glass panes floating over a fixed world of
  photographs that cross-fade by zone (IntersectionObserver zone spy).
- Voice/shape: capsules (it is an app), the focus ring is itself a pane of glass;
  glass rail → floating dock on mobile. Recipe: low blur (8–10px) high saturate,
  directional inset specular stack, `feImage` displacement lens (Chromium only,
  gated), one glass never on top of another.
- Art (`themes.glass`): `cover.zh/en/credit`, `plates` (`[0]` hero, last = appendix
  backdrop), optional `zones` (slugs, internal), `day_plate` as in noir.
- Limits: **module-only export**; `backdrop-filter` does not survive `foreignObject`,
  exports use a solid semi-opaque stand-in (clean but not glassy — accepted).

### journal 手账 — `render_journal.py`
- Paradigm: **a vintage travel journal lying open on a dark desk** — the book is an
  object (page-edge shadow stairs, curled corner, foxing), one continuous sheet of
  aged paper, a fountain-pen route down the spine, brass push-pins as navigation.
- Voice/shape: Kaiti handwriting for titles/annotations, typewriter for clock digits,
  Caveat (embedded OFL webfont) for English asides; torn edges, washi tape, ticket
  stubs, postage stamps, postmarks, wax seal; blocks rotate ≤1°.
- Art (`themes.journal`): `cover.zh` (auto-sized h1: 2–3 chars full size, ≥7 shrunk
  to one line) / `sub` / `credit` / `photo`, `cover_stamps` (≤3), `stamps` (slot →
  scan: `st-a`/`st-b` portrait, `st-wide` landscape), per day `photo`, `caption
  [main, aside]` (two type slots — Kaiti line + Caveat aside — not two languages),
  `annot`, `props` (kit: img · stamp · vtk vintage ticket · bagtag · seal
  · flora · postcard), `doodle` (`sketch` from 12 kit drawings or your own `svg`, +
  `note` ≤2 lines × ≤18 chars, break by hand with `\n` — the box does not wrap),
  `photos2`, `poster` (stem, or `title` for the CSS kraft poster).
- Limits: a pure-CJK doodle note without `\n` was once a one-glyph column; large
  reveal animations were removed for performance — do not add them back.

### zine — `render_zine.py`
- Paradigm: **paper-poster zones** — real photographs as anchors, colour blocks as
  structure; the cover alone is a solid flood, inner pages return to cream paper
  with a torn colour band per chapter head; giant vertical riso two-colour glyphs.
- Voice/shape: structured sans + DIN print numerals; torn edges and flat blocks —
  anti-card, anti-radius; left-edge torn ticket index 01–NN.
- Art (`themes.zine`): `cover.zh` (vertical glyphs — 2 by design, 4 the ceiling) /
  `en` / `credit` (printed on the cover since 2026-08-16) / `photo` (torn cover print,
  `tear_seed`; its `caption` is a "PLACE · CITY" caps side line, not the poem's source),
  `toc_strip`, `props` (colophon paper props by section), per day `poster`,
  `photo` (`treat: mono`), `pair` (two overlapping prints), `sticker`, `band`
  (full-bleed closing photo), `lineart` (kit sketch name or `{svg}`).
- Limits: kit rule — on a poster day the print takes the poster's opposite side and
  is emitted **after** the timeline (defect ⑨ below); write floats as `-1.0`, they
  are emitted verbatim.

### splash 闪屏 — `render_splash.py`
- Paradigm: **a game splash screen stretched into a scroll** — 13 chapters of
  180° gradients chained end-to-start into a day/night narrative, floating islands
  per day, seeded particles, side floaters at two depths, ribbon road per chapter.
- Voice/shape: thick-painted title plate + round 900 weight, brush-feel big
  numerals; bold silhouettes and bevelled solid badges, zero white rounded cards.
- Art (`themes.splash`): `cover.zh/sub`, `hero.palette` (kit mood name) / `title` /
  `art` / `sides`, `appendix.palette`, `vehicles` / `mascots` / `strips`
  registries (`stem` + `ratio`), per day `palette`, `island`, `fx` (kit words),
  `vehicle` / `mascot` (`kind` + inline `pos` — safe ranges and the `ratio` = real
  `.cut.webp` w/h rule are in ART-SCHEMA's splash block), `strip`, `sides`.
- Limits: unknown palette → index rhythm; a registry entry whose file is missing
  emits no CSS class and its days draw nothing; contrast report prints at build.

### portal 穿越 — `render_portal.py`

Footage can come from the agent's **own native video generation** if it has one (no key; 16:9 h264 mp4 24 fps, dive 5–6 s / link 4 s, first/last-frame conditioning for links — ART-SCHEMA.md §Generator choice), from `themes/genvideo.py` (OpenRouter video API, same key as `gen.py`; first/last-frame conditioning; ≈$3 per ten-world chain on `google/veo-3.1-lite`, `minimax/hailuo-3` for quality), or from the local ComfyUI/MiniMax-H3 pipeline (`build_portal_jobs.py`, free).
- Paradigm: **scroll = flight** — scroll position scrubs a chain of mp4 clips
  (dive into a world, frame-chained link to the next, dive again); day overlays
  fade in while the camera is inside that day's world. Two `<video>` slots, hard
  cuts at seams (never crossfade — it overlays a frozen future frame), blob preload
  over HTTP, direct `src` fallback on `file://` so double-click always works.
- Art (`themes.portal`, contract in the renderer docstring): `intro`, `outro`,
  `video_dir` (relative to the art file), `clips` (`file/dur/off/kind/day`).
- Limits: **the "only when footage exists" theme** — the US reference chain (19 clips,
  ~35 MB) is a release asset, **not in the tree**: `themes/assets/portal/` is empty in a
  fresh clone and [its README](../themes/assets/portal/README.md) has the one-line
  curl+unzip restore. The shipped portal case is Morocco (live on the demo site); the US
  chain is the style reference / pipeline fixture only, so another trip needs its own
  clips (build recipe: `build_portal_jobs.py --spec worlds.json` + a ComfyUI i2v
  box; sampler `STEPS` defaults to **10** since 2026-08-16 — same look as 20 to the
  owner's eye, half the wall clock, ≈21 min for 5 dives + 4 links). Videos stay
  sidecar files next to the HTML. Share buttons are exempt (video state) — so no
  `xprobe.sh` on portal; eyeball it in a browser.

`render_picker.py` renders the style chooser (one card per live theme + a table);
add every new theme to its `THEMES` list or the chooser silently falls behind.

## 3. Rendering a trip (Phase 6 checklist)

**Destination scenery is never reused.** Cover / hero / title sticker / clay terrain band / noir plate / splash island are generated for the trip; only generic props (IMAGE-LIBRARY §12) are shared. Clay's default terrain is the neutral `ridge`; `city|park|west|isle` are US-2026 bands.

0. **Start the plan from `assets/plan.example.json`** — it is the only complete
   example of the plan skeleton the renderers read (`budget` = a list of `{cat,
   per_person, total, note}` rows, `legs` = a list of objects, `checklist`, …;
   `references/output-template.md` describes the sections in prose). A section of
   the wrong shape no longer crashes a renderer — `theme_common.norm_plan` prints
   `WARN plan.<key>: expected …` on stderr pointing at output-template.md and renders
   that block empty — so **read stderr after every render**: an empty budget/legs
   grid with a green qc is a plan-shape bug, not a theme bug.
1. Pick the theme(s). Write the **common** art block: cover poem title from
   `references/cover-titles.md` (roles: `zh` = display h1 · `sub` = copy · `en` =
   English line · `credit` = source, printed by all eight themes · `kick` = short trip
   word used ONLY for `<title>` and export filenames on a zh page; `kick_en` takes
   that job on an en page), `home`, `end`, and for every day `theme` (4
   chars) / `en` / `mark`. Titles are per theme in practice — put `zh/en/sub/credit`
   under `themes.<theme>.cover`.
2. Per theme, pick pictures — **reuse first**: `themes/assets/IMAGE-LIBRARY.md`
   §Generic pieces (通用件) lists what any trip may use (a plane, a bus, a beach, tape, flora…).
   Place-bound assets (Liberty, Golden Gate, Yosemite, `noir-*`, `glass-*`,
   `zine-*`, `au-*`, `nordic-*`…) never cross trips. Note the index's merged rows
   (`name-a/b/c`, `name-*(N)`) — expand before deciding something is missing.
3. Generate only what is missing — with the agent's **own native image generation if
   it has one (no key; same specs/prompts, then the same split/cutout/webp/manifest
   steps — ART-SCHEMA.md §Generator choice)**, otherwise `python3 themes/gen.py <trip>/jobs.json --outdir
   <trip> --manifest <trip>/manifest.<trip>.json` (`--dry-run` first; small parts go
   on a **sheet** — one image cut into 6–12 pieces by `split_sheet.py`, ~$0.005 each;
   `--probe` first, then names in the prompt's Row 1 → Row 2 order; recipe and the
   full command forms in ART-SCHEMA.md §Image toolchain), then `cutout.py` for every
   **cut-out** slot (stickers, islands, figurines, bands, stamps, props — the "shape"
   column of ART-SCHEMA's size table) or `towebp.py` for opaque plates/photos, and
   `towebp.py x.cut.png --sizes sm,md,lg` for size variants of a cut-out (running
   `towebp --sizes` on the white-background PNG gives a white square, silently).
   `split_sheet.py` / `cutout.py` / `towebp.py` all take `--outdir` and default to
   the input's directory — write full paths, the shell cwd does not persist between
   calls. Pick the smallest variant that fits the display size — the same image
   referenced twice doubles its base64. The trip's `manifest.<trip>.json` is the
   record of what was generated; **do not write into `themes/assets/` or
   `IMAGE-LIBRARY.md`** — folding a test trip's generic pieces back into the
   library is the main agent's job after the batch (ART-SCHEMA §Test-trip asset recycling).
4. Write the words: captions, annotations, doodle notes, the closing line. Voice
   rules live in each renderer's docstring.
5. Render → `qc.py` exit 0 → `xprobe.sh` one module and, for whole-page themes, one
   page export → **look at both PNGs** (§6). Deliver the HTML (and for portal, the
   video directory beside it).

Steps 2-3 above assume the session **can** make pictures. Whether it can is decided
once, at Phase 0, and recorded in `prefs.pictures` — §3b is the branch for when it
cannot.

### 3b. Stock mode — no generator, no key, still a themed page

Phase 0's **picture-capability check** writes one of three values into the plan's
`prefs.pictures`, and Phase 6 reads it instead of guessing:

1. **`native`** — the agent has its own image-generation tool → generate this trip's art
   with it; nothing to configure, no key. Same specs, same prompts-as-style-anchors, same
   four downstream steps (ART-SCHEMA.md §Generator choice). §3 steps 2-3 as written.
2. **`key`** — `themes/.auth_header` exists (checked with `test -s`; never read, print or
   copy it) → `gen.py` / `genvideo.py` over OpenRouter with the user's key. §3 steps 2-3.
3. **`stock`** — neither. **This is not a reason to ship the plain page.** The built-in
   stock kit supplies the pictures and the page still renders in a theme:

```
python3 themes/stock_art.py plan.geo.json --theme illustrated -o plan.art.json
    # also: --theme clay · --lang zh|en · --index PATH (a different stock index)
```

- **What the script fills**: the picture side of the art file — cover painting, per-day
  heroes/cut-outs and props — matched to the plan's country and each day's stops from
  `themes/assets/stock/` (`stock/index.json`, catalogue in `stock/README.md`) plus the
  shared library's same-country pictures and generic props (`IMAGE-LIBRARY.md` §Generic pieces).
- **What it does not fill — you write the words**: the cover title from
  `references/cover-titles.md`, each day's `theme` (4 chars) / `en` / `mark`, captions,
  annotations and the closing line. A page shipped with the script's placeholders in it
  is a defect, exactly as in §3 step 4.
- **Keep the notice.** The script writes the stock notice into the page's fine print
  (`end.fine`); leave it there, and repeat it once in the chat summary — *"pictures come
  from the built-in stock kit because no image generator or key was available; provide
  one and the art gets generated for this trip."* Never ask the user for a key in chat
  and never handle one.
- **Coverage today**: **illustrated** (the default) is complete; **clay** works — its
  terrain bands come from the built-in neutral SVG kit (`ridge|plain|coast|forest|lake|
  desert`) plus generic clay props. The other six themes (noir, glass, journal, zine,
  splash, portal) need generated pictures for their plates / photos / islands / footage —
  if the user asks for one of them in stock mode, say so and offer illustrated instead;
  rendering them anyway gives a page with empty picture slots, and portal has no footage
  at all. Stock packs for the remaining styles are future work
  ([`docs/KNOWN-ISSUES.md`](../docs/KNOWN-ISSUES.md) AST-8).
- Everything else is unchanged: render, `qc.py` exit 0, probe and **look** at the PNG
  (§6). A stock page is a real themed page and gets the same verification.

## 4. Adding a theme

1. **Answer the four questions first**, or do not start: ① organising principle
   (paper / terrain / negative / imagery / …) ② interaction (vertical scroll,
   horizontal paging, spatial selection…) ③ type voice (which face does which job)
   ④ shape language (what buttons and markers look like). Swapping backgrounds and
   illustrations = a re-skin; an audit will call it the same species. Check the
   result against §2's axes; the strongest differentiation is a move only this
   theme can make (clay's mini-road, noir's hop-band dissolve).
2. Owner's bar for every theme: modules blend into one another (no "box next to
   box"), the main picture is the page's background rather than a framed painting,
   and the theme carries pictures — pure-text designs are retired.
3. Start from the shortest live renderer; `from theme_common import …` gives you
   `esc/et/ic/sprite`, `data_uri`, `day_embed_url`, `dist_km`, `load_plan`,
   `short_dates`, `Art/load_art/add_art_arg`, `export_prefix`, `export_js`, and the
   i18n set `init_lang/lang/T/tag_pretty/weekday/theme_name/brief_titles` (§4a). Share
   only what does not hurt identity: **layout, type, colour, motion and interaction
   widgets stay in the renderer** — that is exactly the part that must differ.
4. Contract to honour: `add_art_arg(ap)` + `load_art(plan, args.art, args.assets)`;
   read the common block via `Art` (theme block merges over common per key); every
   field optional with the neutral fallbacks documented in your docstring; a
   `--art none` render of `examples/kyoto-sample.plan.geo.json` must work with no
   trace of any other trip (`grep` the renderer for place names: zero hits).
   The timeline loop appends `theme_common.sub_stops_html(row, pin, et)` inside each
   row's cell — `pin(href, label)` is the theme's own row-pin markup and both arguments
   arrive escaped — so a row's `sub_stops` (output-template.md §city-block) print under
   it in every theme; a card with no room or no pointer events passes `brief=True`.
   The same loop prepends `theme_common.hours_html(row, et)` for a row's `hours`, the
   day card opens with `theme_common.decision_points_html(day, et)`, and each hotel
   option appends `theme_common.stay_rules_html(option)` (`checkout` / `bag_hold`) —
   all three return `''` when the key is absent, so a plan without them renders
   byte-identically.
5. Share buttons: wire `theme_common.export_js(theme, page_bg, extra_css,
   page_root)`. Buttons are `class="xbtn no-export"` with `data-x-for="#dN"
   data-x-label="DAY0N"` (module) or `data-x-page` (whole page); build-time
   `html.replace("EXPORT_JS_PLACEHOLDER", export_js(...))`. `.no-export` content is
   excluded. `extra_css` is make-or-break: anything revealed by scroll (`.reveal`,
   rAF opacity) must be forced visible with `!important` under the `.__xbody`
   prefix, or the export is blank. Sticky/fixed-stage themes pass `page_root=""`
   (module-only). Labels are fixed: 保存这一天 / 保存附录 / 生成长图 (never 导出/下载/
   存储) — always via `T("btn.save_day")` etc. so the en page says Save this day /
   Save appendix / Save long image (§4a); the button must speak the theme's own shape
   language.
6. **Continuous-world recipe** (any "one landscape" theme): per-chapter gradient
   whose start colour = previous chapter's end (never a page-wide percentage
   gradient — content height changes and the stops drift); terrain strips = cut-out
   webp with negative margins + `first-of-type` padding to protect the next line;
   any decoration line that spans the page is drawn **per chapter** (a single global
   SVG is covered by chapter backgrounds; layer order background < line < content);
   each layer's SVG holds only the path segments inside its own window (a 12k-px
   path in every layer blows the GPU texture limit — blank tiles), and no CSS
   `filter:blur()` on long paths (fake it with 2–3 wide low-alpha strokes).
7. Acceptance: `qc.py` exit 0 · **byte-identical rebuild** (render twice to two
   files and `cmp` — all randomness must be seeded; a diff means `Math.random` or a
   timestamp leaked in) · 390px cold load with per-element `right > innerWidth`
   check · re-derive the signature mechanic with your own arithmetic in the browser
   (§6) · module + page export probed and eyeballed · added to `render_picker.py`.

### 4a. i18n — how the pages speak two languages, and how to add a third

- **Source of truth**: `plan["lang"]` (fallback `plan["meta"]["lang"]`; `zh` default,
  `en`), overridden per run by `--lang` (added by `add_art_arg`). Every renderer's
  `main()` calls `init_lang(args, plan)` right after `load_plan`; nothing else in the
  file decides the language.
- **Three tables, one per kind of word** (`themes/theme_common.py` §i18n):
  1. `STRINGS[lang]` — words every theme shares, read with `T(key)`: `tag.*`
     (`tag_pretty(tag)`, incl. `swap→X`), `btn.save_day|save_appendix|save_page`,
     `toast.*` (baked into `export_js` at build time), `label.page|day|appendix`,
     `sec.*` (brief/decisions/unverified/legs/hotels/budget/checklist/appendix/route/
     map), `sun.dawn`/`walk`/`rain_alt`/`late_cut`/`hop.map`/`verify.est`/
     `price.check`/`link`, `week` (`weekday(date)`), `html_lang` (`<html lang>`).
  2. `THEME_NAMES[lang]` — `theme_name(key)` for `<title>` and export filenames
     (手账版 → Journal …); `BRIEF_TITLES` / `BRIEF_TITLES_EN` behind `brief_titles(art)`.
  3. Each renderer's local `L = {"zh": {...}, "en": {...}}` + `t(k)` — the theme's own
     voice only (cover fallback word, chapter eyebrows, stamp/badge text, quips,
     credit line). Generic words never go here; if two themes need the same word it
     is a `STRINGS` key.
  Content is never translated: plan text, art copy and `sun` are printed as written
  (`sun` parsers accept 天亮 and dawn — `route_tools.py sun --write --lang en`).
- **Adding a language `xx`**: add `STRINGS["xx"]` (every key of `zh`, including
  `week` and `html_lang`), `THEME_NAMES["xx"]`, a `BRIEF_TITLES_XX` and its branch in
  `brief_titles()`, `SUN_DAWN["xx"]` in `route_tools.py`, then an `"xx"` column in each
  renderer's `L` (`t()` falls back to zh for a missing key, so ship complete columns);
  `--lang` picks up the new choice from `STRINGS` automatically. Then render an `xx`
  plan through every theme + `render_picker.py`, `qc.py` exit 0, and grep the output
  for CJK — any Chinese that is not plan/art content is a leaked shell string.
- **The CJK-leak grep, comment-free**: a bare `grep -o '[一-龥]\{2,\}'` hits CSS/JS
  *comments* on every en page (journal 纽约/第一站/秋水长天, noir 路线地图/插画版, and the
  export engine's `渲染引擎不支持` from theme_common — all comments, all invisible), so
  strip comments first, then look:

  ```bash
  python3 - out.html <<'EOF'
  import re, sys
  s = open(sys.argv[1], encoding="utf-8").read()
  def strip(m):                       # comments inside <script>/<style> only
      body = re.sub(r"/\*[\s\S]*?\*/", "", m.group(0))
      return re.sub(r"(?m)^[ \t]*//.*$", "", body)      # line-start // (URLs keep theirs)
  s = re.sub(r"<(script|style)\b[^>]*>[\s\S]*?</\1>", strip, s)
  s = re.sub(r"<!--[\s\S]*?-->", "", s)
  hits = sorted(set(re.findall(r"[一-鿿]{2,}", s)))
  print(*hits, sep="\n") if hits else print("no CJK outside comments")
  EOF
  ```
  Verified 2026-08-16 on the Mexico journal/noir and Morocco glass/portal en pages: the
  bare grep hits 1–4 comment strings each, this prints `no CJK outside comments`. **The
  known residue lives only in comments**; a hit from this script on an en page whose
  plan/art carry no Chinese is a real leak.
- **Regression gate — zh bytes never move**: `zh` is the historical shell, and the
  US baselines (`trips/us-2026/US-2026-<theme>版.html`) are the oracle. After any i18n
  edit, render `trips/us-2026/plan-A.geo.json` with each renderer (no `--lang`, and
  again with `--lang zh`) and `cmp` against the baseline: byte-identical or the change
  is wrong (a shifted RNG call, a re-ordered replace, a stray space). Never edit a zh
  value in `STRINGS`/`L` without rebuilding the baselines on purpose.

## 5. Recurring-defect checklist (run every item on every new theme)

Two audit rounds produced 76 findings; every class below recurred in ≥2 themes.

1. **Contrast** — decorative colours are fine, text gets its own `-ink` ramp; compute
   the worst case over the whole background gradient with the relative-luminance
   formula, do not eyeball (illustrated once had 16/16 tokens failing AA).
2. **The signature mechanic itself is broken** — the most expensive class; §6.
3. **`.reveal{opacity:0}` without JS** — scope as `.js .reveal{}`, add the `js`
   class as the IIFE's first statement, wrap decoration JS in try/catch.
4. **Print strips backgrounds** — filled chips go white-on-white; dark themes leak
   their tokens into `@media print` — reset the whole token set there and use
   `print-color-adjust:exact` on the few colours that matter.
5. **No `:focus-visible` rule** (four themes missed it).
6. **Icon links without an accessible name / <44px hit area; `target=_blank`
   without `rel=noopener`.**
7. **Compositor killers** — world-length paths in every SVG layer; `filter:blur()`
   on long paths; `overflow:clip` + `border-radius` around a 12k-px element.
   Symptom: scroll areas screenshot as flat colour, real devices stall.
8. **Quote nesting in inline `url("data:…")`** — the style attribute truncates and
   every decoration silently dies (25 stamps once rendered as `url("")` while QC
   passed). Emit `url(<fully-escaped uri>)` unquoted; qc.py check 7 fails on
   `url("` inside a style attribute. Same family: a bare `<` in CSS tears the
   export `<foreignObject>` XML — the engine now escapes `&`/`<`; whenever HTML/CSS
   is spliced into another syntax (XML, attribute, URL), escape at the boundary.
9. **Grid/flex row between two floats collapses to a one-glyph column** — on a
   poster day float the print/sticker after the timeline so the flow ever sees one
   float at a time. Only a headless-Chrome screenshot catches this.
9½. **`file://` synchronous-init ordering** — declarations reached by init must sit
   before the loader block; over HTTP the async fetch hides the bug, on `file://`
   the sync path throws on every scroll (portal once lost every overlay). Accept
   under both modes.
10. **Sprite `<use>` across documents** — the export clone is a separate SVG
   document, so `<use href="#i-…">` dangles and icons/particles export blank while
   the probe title stays green. The engine copies referenced `<symbol>`s
   (`spriteFor()`), but audit every `#id` reference (use, `url(#grad)`, filter,
   clip-path, mask) on any clone/serialise path; and when another theme has fixed
   the same class, promote the fix to the engine or this list.

Runtime half (browser only): 390px cold-load per-element overflow (`docOv=0` is
not proof — `overflow-x:clip` hides content silently); grid children holding long
text need `minmax(0,1fr)` + `min-width:0` + `overflow-wrap:anywhere`; data-URI
images never `loading=lazy`; itinerary grids never `grid-auto-flow:dense`.
11. **A `brief` key with no title** — every theme titles brief cards with
    `theme_common.brief_titles()` and falls back to the raw key, so a plan key that is
    not in `BRIEF_TITLES` prints as an English identifier on a zh page (as "health"
    did before 2026-09; today `lookalikes` is the known one — it takes an art
    `brief_titles` override). Add
    the key to both dicts (canonical order: output-template.md §Brief templates) before
    any plan uses it.

## 6. Verification discipline

- **"Works on paper ≠ works in CSS."** Noir's burned-in title was dead for days: a
  `z-index` on the content layer created a stacking context that isolated the blend
  group — the fix is lowering the plate, not raising the content. Clay's road once
  missed the stones it claimed to thread by 137px (anchored to viewport ratios) —
  anchor to `getBoundingClientRect()` centres, and re-run on `ResizeObserver` plus
  a capture-phase `toggle` listener (`<details>` toggles do not bubble).
- **Scan the whole interval, not the endpoints.** A dissolve checked only at chapter
  and hop centres passed while mid-chapter was a 50/50 double exposure; sample
  10%–90% in nine steps per chapter and require every one to pass.
- **Read authoritative fields, never sniff prose** — transport mode comes from
  `legs`, not hop text (a precedence slip once made 8/11 days "fly").
- **Export probes**: `xprobe.sh` reports `OK <w>x<h> blob=<bytes> errs=<n>` and
  writes the export as PNG. Green is necessary, not sufficient — **open the image**:
  icons and particles present? no stray colour band at the top? last decoration
  at the bottom intact? `ANCHOR=bottom … page ''` shows the tail. The tail bar is
  **the page's last element, named**: the colophon / end card / credit line must be
  readable in the image. "The bottom looks like plausible content" proves nothing —
  a clipped export also ends in plausible prose, which is exactly how the
  zine/splash tail clip hid from every bottom-anchored probe until 2026-09-01. Both `xprobe.sh`
  and `xt.sh` start Chrome in the background with a throwaway `--user-data-dir`,
  poll for output, then kill that Chrome by profile — do not wait on it in the
  foreground (Chrome 151 headless never exits on this machine) and do not run
  headless Chrome unless the task calls for it (memory). A `Killed: 9` job line
  from an older copy of either script is that self-kill, not a failure (the
  current scripts swallow it); the title/png line is the result.
- **Cover check — which themes have a whole-page button, and what `page ''` gives you.**
  Whole-page (`data-x-page`) buttons exist in illustrated, clay, journal, zine and
  splash. **noir and glass are module-only** (sticky/fixed stage, `page_root=""`), and
  portal has no share buttons at all. On those, `xprobe.sh out.html page '' cover.png`
  prints `NO-BTN` — **not a failure**: pass 2 still screenshots the live page at
  1200×2600, so `cover.png` is the first 2600 px of the real page, i.e. exactly the
  cover shot you wanted to eyeball. **splash** is the opposite trap: its whole-page
  export deliberately zeroes the hero's 100svh (`extra_css`, see the renderer
  docstring), so the export's first screen is DAY 01 and the cover is not in it —
  shoot the live page instead. Same for any theme whose cover you want at true
  viewport geometry. Live-page shot, the way xprobe.sh does it (background Chrome,
  throwaway profile, poll, kill by profile — never wait on Chrome in the foreground):

  ```bash
  CH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  mkdir -p "${TMPDIR:-/tmp}/xprobe" qa; UDD=$(mktemp -d "${TMPDIR:-/tmp}/xprobe/udd.XXXXXX"); OUT=$PWD/qa/splash-live-cover.png
  { "$CH" --headless=new --disable-gpu --no-first-run --user-data-dir="$UDD" --hide-scrollbars \
      --window-size=1200,2600 --virtual-time-budget=45000 --screenshot="$OUT" "file://$PWD/out.html" 2>/dev/null & } 2>/dev/null
  last=-1; for i in $(seq 1 120); do [ -s "$OUT" ] && { sz=$(stat -f%z "$OUT"); [ "$sz" = "$last" ] && break; last=$sz; }; sleep 1; done
  { pkill -9 -f -- "--user-data-dir=$UDD"; wait; } 2>/dev/null; rm -rf "$UDD"
  ```
  (If the shell blocks a foreground `sleep`, poll with
  `python3 -c "import time;time.sleep(1)"` instead — same one-second beat.)
  (For a `.reveal` theme inject `.reveal{opacity:1!important}` into a copy first —
  IntersectionObserver never fires headless.) `ANCHOR=bottom xprobe.sh … page ''`
  shows the export's last 2600 px — the tail check; on a module-only theme it is the
  same live first screen, so check the tail there with a module probe on the last
  block (noir `module '.appx'`, glass `module '#checklist'` / `'#brief'` — the
  selectors are the page's own `data-x-for` values).
- **Headless viewport floor**: macOS headless Chrome will not shrink `innerWidth`
  below ≈500 no matter what `--window-size` says — `--window-size=390,844`
  lays the page out at 500 px and screenshots its left 390 px, which looks exactly
  like an overflow bug. Run the 390 px cold-load check by injecting the
  measurement into the page (a 390 px-wide iframe/container, or per-element
  `right > innerWidth` printed into the title) rather than by narrowing the window.
- **English trips**: the CJK-sized slots have Latin ceilings — `days[].theme`
  ≤12 Latin chars (zine's vertical title ≤10), illustrated `cover.zh` ≈11 — see
  ART-SCHEMA.md "Latin length ceilings"; longer titles overrun rather than wrap.
  On an en page `<title>` and the download prefix come from `cover.kick_en`
  (`theme_common.title_kick`, all eight themes), so write it as you want it read
  (`"MEXICO 2026"`). English copy runs 30–40 % longer than the Chinese it replaces:
  containers sized for CJK — journal sticky notes (`rain_alt` / `late_cut`), the
  cover envelope (`meta.route` ≤68 chars), noir/glass credit lines — need a look
  in the export, not just a green probe. Journal now leaves room at the foot of
  its en notes and keeps its cover epigraph off the postmark (2026-08-16), but keep
  note copy short (~≤180 chars) rather than relying on it.
- **Screenshot traps**: measure and shoot at the same viewport (svh/sticky shift
  layout); in headless, IntersectionObserver never fires — inject
  `.reveal{opacity:1!important}` before shooting `.reveal` themes; a hidden in-app
  browser pane freezes rAF/video and reports 0×0 geometry — check `innerWidth>0`
  first, prefer geometry assertions (rect intersection, `isPointInStroke`) over
  pixels; only a real wheel scroll moves the screenshot engine, JS `scrollTo` does
  not; bust caches with `?v=n` after a rebuild.
- **Export engine defaults**: day blocks PNG 2×; blocks over ~1.2e7 px and whole
  pages JPEG 0.92; height cap 30000, page area budget 3.2e7 px, one half-size
  retry; viewport units are frozen to px before capture (skipping `url(...)`).
  Canvas height comes from the **inked bottom of a padded probe raster**, not from
  the live `scrollHeight` alone: the SVG image can lay the same markup out ~5–7%
  taller than the live page (CJK prose worst) and a foreignObject clips silently
  at its height attribute, so ink at or past the measured height grows the canvas
  (+140px of paper) instead of vanishing; ink clear of it takes the pre-fix code
  path — byte-identical to the old engine in a same-run comparison; rasterisation
  is not deterministic across runs (2026-09-02 fix; before it, zine/splash whole
  pages lost their decisions/colophon/end-card tail).

## 7. Recipes worth reusing

- **Google Maps embed, keyless**: `https://maps.google.com/maps?saddr=<start>&daddr=<2nd>+to:<3rd>…+to:<end>&dirflg=r&output=embed` — `daddr` starts the chain and the last stop closes it; take the longest run of hops each ≤150 km (skip flights); inject the iframe `src` only when its `<details>` opens (`theme_common.day_embed_url`).
- **Smooth-scroll fallback**: the in-app browser ignores `scroll-behavior` and
  `scrollTo({behavior:'smooth'})` — try smooth, hard-jump after 350 ms if nothing moved.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall