+ );
+}
+```
+
+`` fetches and parses the `.usda`, builds the scene, and provides a
+context that the built-in `` reads. Drop the selector anywhere
+inside `` as an HTML overlay, or use it standalone with explicit
+`stage`/`value`/`onChange` props.
+
+### Props (`ProductTwin`)
+
+| prop | type | notes |
+|---|---|---|
+| `productTwinUrl` | `string` | URL/path to a `.usda` from `shoploop-shopify ingest` |
+| `stage` | `ProductTwinStage?` | pre-parsed stage; skips the fetch |
+| `initialVariants` | `Record?` | initial selection, e.g. `{ size: "_100g" }` |
+| `onVariantChange` | `(c: VariantChange) => void` | fires on every selection change |
+| `environment` | `string?` | HDRI URL or a drei preset name (`apartment`, `sunset`, …) |
+| `cameraPreset` | `"hero" \| "pdp" \| "lifestyle"` | `hero` adds shallow DOF |
+| `placeholder` | `Partial?` | `{ kind: "tea-tin" \| "box", color, radius, height }` |
+
+## Pointing at a real twin
+
+```sh
+# in connectors/shopify
+pnpm shoploop-shopify ingest --product > varitea_product_twin.usda
+```
+
+Serve the `.usda` as a static asset and pass its URL to `productTwinUrl`. When
+the connector attaches a Shopify Model3d (`prepend references = @…glb@`), the
+renderer fetches and loads it via `GLTFLoader`/`USDZLoader`. When the twin only
+carries the placeholder `def Mesh`, a procedural rounded-cylinder tea tin renders
+instead — no asset required.
+
+## Embedding
+
+### Next.js (App Router)
+
+The renderer is client-only (WebGL + `fetch`). Wrap it in a client component and
+lazy-load to keep it out of the server bundle:
+
+```tsx
+"use client";
+import dynamic from "next/dynamic";
+const ProductTwin = dynamic(
+ () => import("@shoploop/twin-renderer").then((m) => m.ProductTwin),
+ { ssr: false },
+);
+```
+
+### Remix
+
+Render inside a `` boundary (e.g. `remix-utils`) so the canvas only
+mounts in the browser; pass the twin URL from your loader data.
+
+There is **no server-side GLB rendering** — all geometry work is browser-side Three.js.
+
+## Performance notes
+
+- Target **60 fps on a 2021 MBP** for the placeholder twin at the `hero` preset.
+- Mobile budget: **≥30 fps** mid-tier phones. Bloom + DOF are the heaviest passes —
+ drop to `pdp`/`lifestyle` (DOF off) or set `bloom={0}` on low-end devices.
+- `dpr` is capped at `[1, 2]`; shadow map is 2048² (halve for mobile if needed).
+- Geometry is built once per stage; variant switches only restate commerce data,
+ so the size selector is allocation-free after first load.
+- Keep external GLBs **< 2 MB** / **< 50k tris** for a snappy first paint.
+
+## Scripts
+
+```sh
+pnpm --filter @shoploop/twin-renderer dev # Vite dev server on :5173 (demo)
+pnpm --filter @shoploop/twin-renderer build # typecheck + ESM lib (+ .d.ts) + demo site
+pnpm --filter @shoploop/twin-renderer test # vitest (parser + scene builder)
+```
+
+## Scope of the USDA parser
+
+Supports exactly the subset the Shopify connector emits: layer metadata +
+`customLayerData`, `def`/`over`/`class` prims, `Xform`/`Mesh`/`Material`/`Scope`,
+prim metadata (`kind`, `variantSets`, `variants`, `references`, `apiSchemas`),
+typed attributes (`string`/`int`/`float`/`bool`/`token`/`asset` + `[]` arrays +
+numeric tuples), relationships, `variantSet` blocks, and the `commerce:*` /
+`brand:*` namespaces. It is **not** a general OpenUSD implementation.
+
+See [DESIGN.md](./DESIGN.md) for the aesthetic contract.
diff --git a/packages/twin-renderer/demo/index.html b/packages/twin-renderer/demo/index.html
new file mode 100644
index 0000000..1814e7f
--- /dev/null
+++ b/packages/twin-renderer/demo/index.html
@@ -0,0 +1,31 @@
+
+
+
+
+
+ Varitea · Product Twin
+
+
+
+
+
+
+
diff --git a/packages/twin-renderer/demo/main.tsx b/packages/twin-renderer/demo/main.tsx
new file mode 100644
index 0000000..81c1fa4
--- /dev/null
+++ b/packages/twin-renderer/demo/main.tsx
@@ -0,0 +1,75 @@
+import { StrictMode, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { ProductTwin, type VariantChange, VariantSelector } from "../src/index.js";
+
+const USDA_URL = "/varitea_product_twin.usda";
+
+function priceLabel(commerce: VariantChange["commerce"]): string {
+ const price = commerce["commerce:price"];
+ const value = commerce["commerce:option_value"];
+ const sku = commerce["commerce:sku"];
+ const parts = [
+ value ? String(value) : null,
+ price ? `$${String(price)}` : null,
+ sku ? String(sku) : null,
+ ].filter(Boolean);
+ return parts.join(" · ");
+}
+
+function App() {
+ const [change, setChange] = useState(null);
+
+ return (
+