Skip to content

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.

12.8 KB
Raw Blame

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 from REPO_FILE_BASE/GITHUB_REPO in site/src/lib/site-links.ts, now https://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-doorway flame and smoke, night-bridge water shimmer); lowering MOTION_PSNR_DB in site_media_clips.py to ≈ 40 would orbit them.
  • Create the Cloudflare Pages project — after the Harness Village redistribution rights are confirmed, not before.