Agent skill for creative 3D visualization: turn an idea into a Three.js/Blender scene worth exploring. Claude Code + Codex plugin, 223 recipes, 440 knowledge records, 22 proved kits, 37 runnable studies.
Landing page (site/)
site/ is the project's public landing page: one scrolling page — a daylight hero, the 37 studies
as demo cards, the repository's own counters, how a sentence becomes a scene, installation, footer
— which then serves the built studies at /examples/<id>/. It is a presentation of this
repository, not a second source of truth: every counter is read at build time from skills/,
docs/, evals/ and evidence/; every card's title, blurb and chapter is read from
examples/README.md joined with examples/shared/catalog.js, so a
number or a name cannot drift from the data behind it.
Stack: React 19 · Vite 7.1.5 · Tailwind v4 · TypeScript strict (tsc --noEmit runs in
prebuild). Visual system: the maintainer's "Daylight" design (phase 8, 2026-09-10) — cream
#fffaf2, ink #1c2a23, green #0b7553, Outfit + JetBrains Mono — with tokens authored in
site/scripts/build-data.mjs. The hero is the showcase frame
docs/demos/showcase/village-overcast-morning.jpg, re-encoded to media/hero/overcast-morning.{jpg,webp};
the live Three.js village of phases 3–7 is still in the tree but gated off
(HERO_LIVE_LOOK = null in site/src/hero/hero-looks.ts), so no three.js chunk ships.
Component and script details are in site/README.md.
What a card does: hovering (or focusing) it plays a 4 s muted loop recorded from the study;
Show 3D opens the study in a modal <dialog> with an iframe on /examples/<id>/ and an
"Open in new tab" link. Under prefers-reduced-motion no clip is mounted and the counters do not
count up.
Build it
From the repository root, in order:
pnpm --dir examples install --frozen-lockfile
bash site/scripts/bundle-examples.sh # builds examples/ and copies it into site/public/examples/
pnpm --dir site install --frozen-lockfile
pnpm --dir site build # build-data → tsc --noEmit → vite build
pnpm --dir site test # 16 node tests over the generated data
node site/scripts/check-budgets.mjs # byte budgets, measured on the build output
pnpm --dir site preview # http://127.0.0.1:4173 (Safari/WebKit refuse port 4190)
The build must run from a full checkout: site/scripts/build-data.mjs reads files one level
above site/. A shallow copy of site/ alone cannot build. The modal iframe needs the bundled
examples, so it 404s under vite dev and works under preview.
Generated versus committed
| Path | State |
|---|---|
site/src/generated/*.json, theme.css |
generated by pnpm build-data on every dev/build; git-ignored |
site/public/examples/ |
generated by bundle-examples.sh (≈ 170 MiB); git-ignored |
site/public/media/** |
committed (≈ 9 MiB: 37 stills, 74 clip files, 2 hero posters, plus the key-art and origin media no section renders since phase 8), hashed in media-manifest.json / hero-manifest.json, so the site builds without a GPU |
site/public/fonts/*.woff2 |
committed (Outfit + JetBrains Mono latin variable subsets, OFL) |
build output (site/dist/) |
generated; git-ignored |
Regenerate the media
All of these need a GPU-capable headless Chromium (Playwright) and ffmpeg, and none of them is
part of the build — the outputs are committed. Pass --python (or set PLAYWRIGHT_PYTHON) when
the system interpreter has no Playwright.
| Command (from the repository root) | Produces |
|---|---|
python3 site/scripts/site-media.py |
all four capture stages below plus site/public/media/media-manifest.json |
python3 site/scripts/site-media.py --stills |
the 37 study stills, ?plate=1 chrome-free, view-quality checked |
python3 site/scripts/site-media.py --clips |
one hover clip per study (37 × webm + mp4, 640 × 360, 4 s). A study whose frames MOTION_MS apart score ≥ 42 dB PSNR (still to the eye) is recorded under a pointer-drag orbit instead; the manifest records motion: native | orbit per clip (16 native, 21 orbit on 2026-09-10) |
python3 site/scripts/site-media.py --keyart |
the 21 showcase frames as full + thumb JPEGs (not rendered since phase 8; kept for the pipeline) |
python3 site/scripts/site-media.py --origin |
the Harness Village clip from docs/demos/harness-village.gif (not rendered since phase 8) |
python3 site/scripts/hero-posters.py --from-frame docs/demos/showcase/village-overcast-morning.jpg --look overcast-morning |
the hero poster pair from the showcase frame, no browser needed |
python3 site/scripts/social-assets.py |
the favicons, apple-touch-icon.png and the 1200 × 630 share image site/public/og/3dviz-pro-max.jpg; needs Pillow + cairosvg, no browser |
python3 site/scripts/site-media.py --hero --url … / hero-poster-diff.py |
the live-look poster route and its pixel check; only meaningful once HERO_LIVE_LOOK names a look again |
--print-commands prints every ffmpeg argv a run would use without running one.
Icons and the share card. All of them are rendered from site/public/favicon.svg (the header's logo mark on a cream tile) and from the same showcase frame the hero uses, by site/scripts/social-assets.py, and all of them are committed. site/index.html carries the canonical URL, the Open Graph and Twitter card tags, a SoftwareSourceCode JSON-LD block and site/public/site.webmanifest; the card image is referenced by absolute URL under https://3dviz.dev (SITE_URL in site/src/lib/site-links.ts), so the origin above has to be right before the first link is shared. check-budgets.mjs holds the share image to 200 KiB on its own line — it is fetched by crawlers, never by the page, so it stays out of the landing-transfer budget.
Deploy (Cloudflare Pages)
The Pages project is 3dviz-pro-max in the maintainer's Cloudflare account (production alias
https://3dviz-pro-max.pages.dev, custom domain https://3dviz.dev), first deployed 2026-09-10 with
wrangler pages deploy site/<build dir> --project-name 3dviz-pro-max --branch main from a local build.
Anatomy geometry is served from the R2 bucket 3dviz-assets at https://assets.3dviz.dev/ (see
examples/assets-manifest.json). For a Git-connected build these are the settings:
| Setting | Value |
|---|---|
| Root directory | / — the repository root, because the data build reads skills/, docs/, evals/, evidence/ and examples/ |
| Build command | pnpm --dir examples install --frozen-lockfile && bash site/scripts/bundle-examples.sh && pnpm --dir site install --frozen-lockfile && pnpm --dir site build |
| Build output directory | site/dist |
| Node version | 24 (NODE_VERSION=24); pnpm 10.30.1 via packageManager |
| Environment variables | none — bundle-examples.sh exports VITE_ASSET_BASE itself, from the base field of examples/assets-manifest.json. Set it in the Pages project only to override that value. |
Deploy size (measured 2026-09-10, Apple M4 Max)
| Part | Files | Bytes |
|---|---|---|
| Site itself (HTML, JS/CSS, fonts, committed media incl. the 37-clip set) | 176 | 10,115,150 (9.6 MiB) |
Bundled examples (/examples/**) — code only, no geometry |
92 | 1,074,793 (1.02 MiB) |
| Total upload | 268 | 11,189,943 (10.7 MiB) |
Largest single file: examples/assets/catalog-*.js, 842 KB — far under the 25 MiB per-asset limit
that bundle-examples.sh enforces, and the file count is far under the 20,000-asset limit.
Anatomy geometry is not deployed. The 108 files (106 STL + two attribution.json, 168.6 MiB)
live in the R2 bucket 3dviz-assets, served from https://assets.3dviz.dev/ (its pub-…r2.dev
URL also answers), with GET/HEAD CORS for the site origins. examples/assets-manifest.json lists
every key with its size and sha256 and holds the base URL that both bundle-examples.sh (for the
deploy build) and examples/scripts/fetch-assets.sh (for a local copy) read — change the URL
there and nothing else. The anatomy studies (heart, brain, muscle-atlas, knee) each pull
several megabytes of STL from that origin when opened in the modal or a tab, so they are still
slow on a cold cache. The landing page itself never pays it: clips are preload="none" and
fetched only on hover, and no study geometry is requested until a study opens.
Uploading to the bucket needs --remote: wrangler r2 object put 3dviz-assets/<key> --file=… --remote. Without it wrangler 4 writes to a local miniflare .wrangler/ directory and the keys
never reach the bucket.
Byte budgets
node site/scripts/check-budgets.mjs measures the build output — text at gzip -9, media at file
size — and exits 1 on any breach. Measured 2026-09-10 on Apple M4 Max:
| Budget | Limit | Measured |
|---|---|---|
| Entry JS (gzip) | 120 KiB | 70.8 KiB |
| Hero chunk (gzip) | 250 KiB, or absent | absent — the hero is the baked frame |
| Landing transfer: HTML + CSS + entry JS (gzip) + heaviest poster + both fonts | 900 KiB | 386.1 KiB |
| Any study still | 120 KiB | 106.7 KiB (night-mill.jpg) |
| Any hover clip (76 files) | 600 KiB | 258.8 KiB (probability.webm) |
| Origin clip | 700 KiB | 357.3 KiB (harness-village.mp4) |
| Any key-art frame | 250 KiB | 210.1 KiB (stone-bridge-over-water.jpg) |
| Any hero poster (4 files) | 250 KiB | 245.8 KiB (overcast-morning.jpg; desktop browsers fetch the 206.9 KiB webp, phones the 59.3 KiB 960-wide webp) |
Share image (og/3dviz-pro-max.jpg, crawlers only) |
200 KiB | 100.9 KiB |
Lighthouse
Run against the production preview, one page, no throttling changes beyond the preset:
pnpm --dir site preview # http://127.0.0.1:4173
pnpm dlx lighthouse http://127.0.0.1:4173/ --preset=desktop --chrome-flags="--headless=new"
pnpm dlx lighthouse http://127.0.0.1:4173/ --chrome-flags="--headless=new" # mobile, the default preset
Measured 2026-09-10 after phase 8 (Daylight), Apple M4 Max, Lighthouse 12.8.2, headless Chrome, loopback preview
| Run | Performance | LCP | CLS | TBT |
|---|---|---|---|---|
| Desktop | 97 | 1.2 s | 0 | 0 ms |
| Mobile (2 runs) | 93 | 3.2 s | 0 | 0 ms |
The LCP element is the hero poster in both. Desktop lost its blocking time with the live hero
(phase 7 scored 68–85 because the village was built on the main thread). Mobile was 88 with the
1920-wide poster alone (LCP 3.9 s); a 960 × 540 pair (overcast-morning-960.{webp,jpg}, 59/73 KiB)
behind <source media="(max-width: 640px)"> brought it to 93. High-DPR phones get ≈ 2.4× density
from that file; add a 1440-wide step if it reads soft on a device.
Earlier measurements (phases 5–7, 2026-09-09) are in the CHANGELOG entry and the phase files; they describe a page that no longer exists.
Caveats
- Licensing. The repository's own code, data and authored media are MIT licensed
and the footer says so. Third-party material is not covered: BodyParts3D anatomy meshes
(CC BY-SA 2.1 Japan), the bundled fonts (OFL 1.1,
site/public/fonts/OFL.txt) and the author-supplied Harness Village recording, whose redistribution rights are still to be confirmed. - Compatibility labels are the documented ones. The install card's WORKS WITH rows carry EVALUATED (Codex) and OBSERVED (Claude Code) from docs/compatibility.md, not the mock-up's "SUPPORTED".
- Blender, Three.js and Chromium marks are trademarks of their owners, used to identify the
tools. They are inlined monochrome in the STEP 05 diagram
(
site/src/components/brand-logos.tsx), which names its sources. - BodyParts3D attribution for the anatomy STLs stays in the page footer and in the examples.
- The Harness Village recording (
site/public/media/origin/) is still committed although no section plays it since phase 8; its redistribution rights remain to be confirmed and it is outside the MIT grant (docs/demos/README.md). - The site adds no external request: fonts, media and scripts are all self-hosted, and no analytics, tag manager or font CDN is loaded.
- Repository links (
GitHub,READ THE PROMPTS,Installation guide,License) are built fromREPO_FILE_BASE/GITHUB_REPOinsite/src/lib/site-links.ts, nowhttps://github.com/viettranx/3dviz-pro-max; change them there if the repository moves.
Follow-ups
- STL → GLB (Draco/meshopt) for the hosted anatomy geometry: no longer a deploy-size item (the 168.6 MiB moved to R2 on 2026-09-10), but still the reason the anatomy studies are slow to open over a network — compression would cut what each visitor downloads from the bucket.
- Drop or keep the unrendered key-art and origin media (2.3 MiB committed, two pipeline stages).
- Two native clips move only faintly at card size (
night-doorwayflame and smoke,night-bridgewater shimmer); loweringMOTION_PSNR_DBinsite_media_clips.pyto ≈ 40 would orbit them. - Create the Cloudflare Pages project — after the Harness Village redistribution rights are confirmed, not before.