feat(twin-renderer): Three.js USD product twin renderer + Varitea demo

[ninan-versioning]

Summary

New package @shoploop/twin-renderer (packages/twin-renderer/) — the browser-side counterpart to the open-imagine GPU render path. Same source-of-truth product_twin.usda emitted by @shoploop/connector-shopify (#15), two consumers: interactive browser preview here, offline EXR render there.

• src/parser/usda.ts — minimal, dependency-free USDA → typed ProductTwinStage AST. Covers exactly the connector's subset: layer metadata + customLayerData, def/over/class prims, Xform/Mesh/Material/Scope, prim metadata (kind, variantSets, variants, references, apiSchemas), typed attrs (string/int/float/bool/token/asset + [] arrays + numeric tuples), relationships, variantSet blocks, commerce:*/brand:*. No heavy USD libs, no WASM.
• src/scene/build.ts — AST → THREE.Group. Honors authored mesh geometry, renders a tasteful procedural tea-tin (rounded cylinder) for placeholder meshes, and resolves external GLB/USDZ refs via an injectable loader (kept synchronous + network-free for tests).
• src/scene/loaders.ts — GLTFLoader/USDZLoader wrapper (browser only; no SSR of GLBs).
• Components — <ProductTwin> (props: productTwinUrl, initialVariants, onVariantChange, environment, cameraPreset hero|pdp|lifestyle), <VariantSelector> (reads variant sets from the parsed stage, standalone or via context), <Stage> (HDRI + soft warm light + DOF on hero + subtle bloom + vignette + ground shadow — no sterile gray-studio look, no debug helpers).
• demo/ — Varitea-styled card loading the canonical fixture with a working size switcher. pnpm dev serves it on :5173.
• Docs — README (Next.js/Remix embedding, pointing at shoploop-shopify ingest output, perf notes) + DESIGN.md (Kinfolk gate).

Public API is intentionally tiny and stable — it ships into the Varitea landing page (separate PR).

Components

ProductTwin · VariantSelector · Stage · parseUsda / getVariantSets / resolveVariantData / getLayerCommerce · buildScene · createAssetLoader · TwinContext/useTwinContext.

Perf budget

• 60 fps target on a 2021 MBP at hero preset (placeholder twin).
• ≥30 fps mid-tier mobile; bloom + DOF are the heaviest passes — drop to pdp/lifestyle or bloom={0} on low-end.
• dpr capped [1,2], 2048² shadow map. Geometry built once per stage; variant switches are allocation-free.
• ESM lib bundle: ~28 kB gzip (React + Three externalized).

Decision gate

1. Varitea critical path? Yes — renderer for the Varitea landing page; consumes the dogfood twin.
2. Deepens moat? Yes — USD scene graph + brand-constrained preview, not image gen.
3. Mistral cheaper? N/A (no model calls).
4. Ships ≤2 weeks solo? Yes.
5. Monthly cost: $0 — pure browser-side Three.js, no server render. Optional runtime HDRI fetch from Poly Haven CDN (CC0), with a built-in drei preset fallback.

Testing

• pnpm --filter @shoploop/twin-renderer test — 14 passing (parser AST shape: xform/variant-set names/commerce attrs/asset refs/over; scene builder: placeholder graph, per-variant userData, tea-tin vs box, injected GLB loader).
• pnpm --filter @shoploop/twin-renderer typecheck — clean.
• pnpm --filter @shoploop/twin-renderer build — ESM lib (+ rolled-up .d.ts) and demo site both build.
• Dev server boots on :5173 serving the Varitea demo + fixture (verified 200s).

Varitea acceptance: pnpm --filter @shoploop/twin-renderer dev loads the Varitea twin with a working variant switcher at 60fps on a 2021 MBP.

Screenshot/gif: placeholder — capture from pnpm dev on :5173.

Note: this package lives in packages/; the Shopify connector fixture is copied into test/fixtures/ + public/. PR #15 (the connector) is the source of the twin format and is not yet merged to main.

🤖 Generated with Claude Code