Purpose

The merchant's own authenticated preview of their public store: opening /store/storefront shows the exact product grid an anonymous visitor would see (every product with status === 'published', each card linking to its own /buy/:productId checkout) plus a one-click "copy the store link" action, so a merchant can check what they are about to share before they share it. The invariant that makes it trustworthy: the page's own filter, products.filter(p => p.status === 'published'), is the same predicate the backend enforces on the read a card's link actually resolves to (GET /commerce/public/product/{id} returns only Product.is_active.is_(True) rows, commerce_router.py line 868): a card shown here is a card a real visitor can open, and a card hidden here is a card that visitor's link would 404 on.

It makes visible one sibling backend recipe directly: product-catalog-crud, whose GET /api/products is this page's only read. The other four backend recipes in this domain (checkout-and-order-creation, payrexx-order-settlement, order-fulfillment-and-delivery, workshop-seat-capacity) are not called by this component at all; this preview is the merchant-facing anchor a visitor leaves through, via a card's /buy/:id link, to reach the pipeline those four recipes cover. That pipeline itself renders on BuyPage.tsx, out of scope for this recipe.

When to use

Trigger phrases: "the storefront preview", "what does my store look like", "the store link", "copy my store link", "which products are live", "my public store page". Surface: SPA, a private Labs page behind PrivateRoute, reached only at /store/storefront ("Storefront" under the "Store" domain, App.tsx line 973, live for every signed-in tenant with the store surface).

Not this recipe: the page a visitor actually lands on when they follow a card (/buy/:productId, BuyPage.tsx), a separate, unauthenticated, single-product page this recipe does not rebuild; there is no live public store-listing route in this app at all: BuyPage.tsx is reached only per product, never through a /store/<slug> style public index, so "the public store" a visitor experiences is entirely this recipe's grid of individual /buy/:id links, never a page of its own. Also not this recipe: /billing/checkout (Checkout.tsx), the Labs platform's own Stripe SaaS pricing-tier picker, a different product, a different payment provider, and a different domain entirely from a merchant's Payrexx-backed commerce store. And not the four backend recipes a visitor's checkout actually exercises once they leave this page (backend_modules above), none of which this component calls.

Stack assumptions

S1 tokens and S2 skeleton assumed; pinned per the source at 62ba4fc: react 19, react-router-dom 7, tailwindcss 3.4. Component library: @prima-modules/alchemy-ui, of which the page uses exactly one atom, Button (components/alchemy-ui re-export); everything else on the page, the header, the chrome mock, the hero, the product tiles, is raw Tailwind against this repo's token classes (purple, ink, ink-60, paper, line, shadow-card, shadow-lift, the same @prima-modules/tokens preset billing-credits/ui/subscription-manager's gradients draw from), not alchemy-ui molecules; there is no Card, no Heading, no Text on this page, unlike every other frontend recipe in this kit measured so far. Data-fetch style: plain fetch through commerceService.ts's getAuthHeaders() (Bearer token from authSession.ts, S2, plus X-Workspace-ID read from localStorage when set), not the api axios singleton billing-credits/ui/subscription-manager uses; this page's provider (commerce/store.tsx) is its own fetch layer. Copy language: German, de-CH, every string on the page including the two hardcoded ones (Gotchas).

Data model

Client state (Storefront.tsx line 9 to 19), all local to the component: copied: boolean (initially false, flips true on the copy click and resets after 1.6s via setTimeout). url, a const, not state: the literal string 'atelier.alchemy.store', identical for every tenant (Gotchas). Everything else the page renders comes from useStore() (commerce/store.tsx), a context the route re-provides fresh on every mount of CommerceStoreProvider (App.tsx line 976): products: Product[], fetched by GET /api/products and mapped through productFromApi (adapter.ts line 184 to 227). The component destructures only products, never the context's own loading or error booleans (store.tsx lines 47 to 48), which is why this page has no loading spinner and no error card of its own (Application logic, Gotchas).

The demo's props (demo.tsx): { viewer, workspace, products: StoreProduct[] }, StoreProduct trimmed to the six fields the component reads (id, name, description, glyph, accent, status, billing) off the real Product type (types.ts lines 88 to 105); BillingConfig likewise trimmed to the fields billingSummary reads. copied is not a prop: it is the one piece of genuinely local UI state, seeded to false inside the demo's own useState, the same convention billing-credits/ui/subscription-manager's demo uses for its voucher input.

Browser storage: nothing of its own; relies on S2's accessToken and on currentWorkspaceId / workspaceId / X-Workspace-ID, whichever localStorage key commerceService.ts's getWorkspaceId() finds first (lines 9 to 15), attached as the X-Workspace-ID header the one read below actually consumes (Security and tenancy).

API surface

One read this page's own data depends on, plus two the provider it mounts inside issues unconditionally and this page never touches:

No write. No error path of its own: a thrown listProducts() (a 401, a 500) is caught by store.tsx's refresh() and turned into the context's error string (line 91), which this page never reads, so a failed load and an empty store are visually identical here: an empty grid, nothing else (Application logic).

Application logic

1. Storefront mounts inside CommerceStoreProvider, which the route wraps fresh (App.tsx 974 to 979, not the outer App-level provider some pages share), so the provider's refresh() (store.tsx 76) fires on every visit to this exact route, issuing all three reads before products is populated.
2. useStore() destructures products only; live = products.filter(p => p.status === 'published') (line 11) runs on every render, no memoization, cheap at the product counts this app handles.
3. url is the fixed literal 'atelier.alchemy.store', computed once per render, not derived from workspace, from an EmDash push target, or from any per-tenant field (Gotchas).
4. copy() (lines 15 to 19): writes https://${url} to the clipboard if the API is available (navigator.clipboard?.writeText, swallowing a rejection with an empty catch), flips copied to true, and a bare setTimeout flips it back after 1600ms with no cleanup on unmount (Gotchas).
5. The chrome mock and hero are static markup: the address bar shows the same hardcoded url, the mark and "Atelier Zürich" title are literal JSX, not read from workspace.name or any brand field (Gotchas): a merchant named "Studio Rendez-Vous" sees "Atelier Zürich" in their own preview.
6. The grid maps live; each card is a plain <Link> to /buy/${p.id}, rendering p.glyph, p.name, p.description (clamped to two lines by line-clamp-2), billingSummary(p.billing) and a static "Ansehen →" affordance. No pagination, no sort order beyond whatever list_products returns (created_at desc, commerce_router.py 159), no per-card availability check (workshop seat counts, workshop-seat-capacity, are not queried here).
7. When live is empty (no published products, or the read has not resolved yet), the .map produces nothing: the chrome mock, the hero and the header all still render, only the grid area is blank, with no message telling the merchant why.

Invariants

• What is shown here is exactly what a visitor could open: live's predicate, status === 'published', is the client-side mirror of the server's own is_active.is_(True) filter on the public read (commerce_router.py 868); the only way this preview and the real store could diverge is a change to one filter without the other, not anything this component itself gets to decide.
• No mutation without an endpoint: this page performs zero writes; its only actions are a clipboard write and client-side navigation via <Link>.
• A loading store and an empty store are the same screen: the component reads no loading flag, so there is exactly one "nothing here yet" rendering, not two (Data model, Gotchas).
• The copy-link target is a constant, not a lookup: url never reads workspace, so this invariant is really an anti-invariant worth stating plainly: the button always copies the same string regardless of which tenant is signed in (Gotchas).

Frontend

The rendering is the live rebuild storefront-preview/demo.tsx, built from @prima-modules/alchemy-ui and @prima-modules/tokens and rendered by the docs host as one frame per state. The page's one input is products; the tree is the frontmatter's. The console is rendered inside the shell rebuild (ui-design-system/ui/appshell-navigation/demo.tsx, imported relatively the way billing-credits/ui/subscription-manager's demo imports it) with a member viewer, not an admin, on /store/storefront, so "Store" is the lit rail entry.

States (rendering.states, in order): default (four published products spanning all three billing models (one-time, subscription, intro-then-subscription) plus one draft product present in products but absent from the grid, proving the filter); empty (only the same draft product, so live is empty and the grid area renders no cards, no message, directly under the still-rendered chrome mock and hero: this is the real component's actual "nothing to show" rendering, not an invented empty-state design, Application logic). A third loading state is deliberately not given its own frame: the source has no visually distinct loading rendering to show (Data model), so a loading state here would either duplicate empty pixel-for-pixel or invent a spinner the app does not have; that is a real gap in the source, noted here and in Gotchas rather than papered over with a state the component cannot actually produce.

Tokens and classes as the source uses them: border-line, bg-paper, text-ink / text-ink-60, bg-purple / text-purple, shadow-card, shadow-lift, all from the @prima-modules/tokens preset, not alchemy-ui's own Tailwind layer (Stack assumptions); the single alchemy-ui atom is Button variant="ghost" size="sm". The product-tile background carries a grain class with no definition anywhere in this repo's CSS or in the app's own (Gotchas), kept for fidelity, visually inert either place.

Responsive: the grid is grid sm:grid-cols-2 lg:grid-cols-3, one column below sm, two at sm, three at lg; the header's actions wrap under the title on a narrow viewport (flex-wrap). Empty state: empty above, no dedicated empty-state component is used (commerce/ui.tsx's own EmptyState export exists in this app and is not reached for from this page, a real, measured choice, not an oversight this recipe can correct). Error state: none exists on this page (Data model); a failed GET /api/products looks identical to empty. Loading state: not given, for the reason above.

What the demo deliberately does not render: CommerceStoreProvider itself (the demo takes products as a prop, Data model); the real clipboard permission prompt some browsers show on first use (the click handler is real and functional once the frame hydrates, only untested here); the workspace-provider chain (AuthContext, WorkspaceContext) the shell rebuild already stands in for, the same convention every sibling demo in this kit follows.

Security & tenancy

What the browser may hold: S2's tokens and, when set, a workspace id string in localStorage, never a Payrexx credential, never a product's raw price beyond what GET /api/products already returns to its owner. Origin and CSRF: plain fetch with a Bearer header, not a cookie, the same as S2's default; X-Workspace-ID is attached client-side from localStorage and is advisory only, since WorkspaceID (api/dependencies.py) derives the authoritative workspace server-side from the verified session, not from a header a client could forge to read another workspace's catalog. Surface gating: PrivateRoute checks hasSurface for the build's own surface (store under the Labs surface set) before this component ever mounts (PrivateRoute.tsx); the backend refuses the same request at the router mount point independently (surface_gate.py), so the frontend check is UX only, not the boundary, the same split PrivateRoute.tsx's own comment documents.

Tenancy here is per-workspace, unlike billing-credits/ui/subscription-manager's per-user page: GET /api/products takes both VerifiedUser and WorkspaceID (commerce_router.py 150 to 153) and filters Product.workspace_id == workspace_id server-side (line 156), so switching workspaces in the shell and returning to this route does change what renders here, correctly. Hidden by CSS versus enforced: nothing; every published product a merchant's workspace owns is shown to that merchant regardless of role, and only the server enforces which workspace's rows come back. Attacker-controlled input the page sends: none; this route sends no path or query parameters of its own beyond the standard headers. What the page renders from the server unescaped: nothing; name, description and glyph are React children, escaped like any other string, and no dangerouslySetInnerHTML appears on this page (unlike the product editor, which renders contentHtml, out of scope here).

Tests

• Colocated with the demo: storefront-preview/demo.test.tsx (vitest, jsdom, @testing-library/react), afterEach(cleanup) per this kit's test-layout: default renders exactly four cards and never the draft product's name; empty renders zero cards and still renders the chrome mock's url pill and the hero title; clicking the copy button flips the label to "✓ Kopiert" and, after the timer, back; no state's markup contains an access-token shape.
• The kit's render smoke: node tooling/verify/render-smoke.mjs commerce-payments/ui/storefront-preview renders both states with renderToString and fetch stubbed (Acceptance checks).
• Labs at 62ba4fc has no unit test of Storefront.tsx (grep -rl Storefront frontend/src --include='*.test.*' is empty) and no Playwright spec for /store/storefront. Backend coverage of GET /api/products belongs to product-catalog-crud's own suite, not to this page.
• What a new app adds: a jsdom test that a listProducts() rejection leaves the grid empty with no visible error, to pin down the gap this recipe's Gotchas documents today so a future fix has something to break; a Playwright spec that seeds one published and one draft product and asserts the draft's name never appears in /store/storefront's DOM.

Deploy & ops

Build target: the Labs Vite bundle (S2), a lazy chunk (App.tsx line 162, lazy(() => import('./pages/commerce/Storefront'))). Env baked at build: VITE_API_URL, S2's own; no other PUBLIC_*/VITE_* value is read on this page. CSP and CORS: nothing of its own; GET /api/products answers on the API origin under the SPA's existing allowance, gated by the store surface as above. Deploy path: S13's frontend rsync with the bundle; rollback is the bundle's. Nothing to migrate here directly; the schema GET /api/products reads belongs to product-catalog-crud. Argus: a synthetic workspace session calling GET /api/products returning 200 with an array is this page's liveness; the page has no health signal of its own.

Gotchas

• 2026-09-12 (measured at 62ba4fc): const url = 'atelier.alchemy.store' (line 13) is a fixed literal, identical for every tenant regardless of their actual store domain, EmDash push target, or workspace slug. The copy-link button always copies the same string. A rebuild reads the real domain off workspace or the product's own emdash.url (types.ts line 85) instead.
• 2026-09-12 (measured at 62ba4fc): the store hero is likewise static: "Atelier Zürich" (line 57) and the tagline "Objekte, Workshops und Guides aus dem Studio." (line 58) are literal JSX, not read from workspace.name or any brand field. Every tenant's preview shows the same studio name.
• 2026-09-12 (measured at 62ba4fc): the product-tile background carries a grain class (line 70) that resolves to nothing: grep -n '\.grain' frontend/src/index.css at this commit is empty, and no Tailwind plugin in frontend/tailwind.config.js defines it either. The comment on index.css line 390 to 393 describes "the faint Swiss paper grain" as a shell-level effect (.az-shell's background gradients), a different, unrelated rule; the product tile's own grain class has never been wired to anything. Visually inert in the app today.
• 2026-09-12 (measured at 62ba4fc): CommerceStoreProvider.refresh() (store.tsx 76 to 92) fires listProducts(), listOrders() and listSubscriptions() together with Promise.all on every mount; because the route wraps a fresh provider per commerce page (App.tsx 974 to 979 et al.) rather than sharing one at the app root, visiting /store/storefront costs two reads (orders, subscriptions) this component never uses. Cheap at current data volumes, a real amount of unnecessary network on a merchant with a long order history.
• 2026-09-12 (measured at 62ba4fc): the component reads no loading and no error from useStore() (lines 9 to 10 only destructure products), so a first fetch and a genuinely empty, all-draft store render identically: the chrome mock and hero paint immediately, the grid area is blank, with nothing telling the merchant which case they are looking at.
• 2026-09-12 (measured at 62ba4fc): setTimeout(() => setCopied(false), 1600) (line 18) has no cleanup; a merchant who clicks copy and navigates away within 1.6s leaves a pending timer that calls setState on an unmounted component. Harmless in practice (React discards it), the same class of un-cleaned timer as billing-credits/ui/subscription-manager's post-voucher setTimeout.
• 2026-09-12 (measured at 62ba4fc): commerce/ui.tsx exports an EmptyState component (used elsewhere in the commerce pages, e.g. Products.tsx) that this page never imports; the empty grid documented above is not a deliberate design decision reachable in the code, it is simply the absence of one.

Reference implementation

Branch: alchemy_labs main at 62ba4fc41009b454e1c033e5036c7e8577db2061 (2026-09-12). Paths relative to the repo root:

• frontend/src/pages/commerce/Storefront.tsx (92 lines): imports (1 to 7), the component, live and copied (9 to 19), the header (21 to 33), the chrome mock and hero (35 to 59), the product grid (61 to 87).
• frontend/src/components/Navigation.tsx: the delegator to AppShell.
• frontend/src/components/nav.tsx: the store domain, its five items including "Storefront" (162 to 174).
• frontend/src/components/commerce/store.tsx: useStore() (184), StoreProvider and refresh() (76 to 92).
• frontend/src/components/commerce/ui.tsx: PageHeader (77 to 102), the unused EmptyState (104 onward).
• frontend/src/components/commerce/adapter.ts: productFromApi (184 to 227), the status/glyph/accent mapping (203, 204, 225).
• frontend/src/lib/commerceFormat.ts: chf, perInterval, billingSummary (3 to 49).
• frontend/src/services/commerceService.ts: listProducts (276 to 282), listOrders (510 to 517), listSubscriptions (540 to 545), getAuthHeaders and getWorkspaceId (9 to 26).
• frontend/src/pages/commerce/BuyPage.tsx: the page a card's link resolves to, not rebuilt by this recipe.
• frontend/src/App.tsx: the lazy import (162), the route (973 to 981).
• backend/api/routers/commerce_router.py: list_products (149 to 163), public_get_product (853 to 873, the is_active filter this recipe's Purpose cites at line 868).
• The demo: modules/commerce-payments/ui/storefront-preview/demo.tsx; the shell it renders in: modules/ui-design-system/ui/appshell-navigation/demo.tsx and nav.tsx.

Deviations of the reference from this recipe, all dated 2026-09-12: the hardcoded url and hero copy; the dead grain class; the unread loading/error context fields; the two unused parallel reads on every mount; the uncleaned setTimeout.

Acceptance checks

From alchemy_labs/frontend at 62ba4fc with the harness up (tooling/verify/labs-local.sh up, an owner session with at least one published and one draft product seeded), or from a new app built to this recipe:

1. grep -n "status === 'published'" src/pages/commerce/Storefront.tsx prints one line (11).
2. grep -n "atelier.alchemy.store" src/pages/commerce/Storefront.tsx prints one line (13), confirming the hardcoded domain named in Gotchas is still present (or absent, once fixed).
3. Browser walk-through, signed in as the owner of a workspace with two published and one draft product: (a) open /store/storefront, observe the shell paint, then the chrome mock and hero, then exactly two cards in the grid, never the draft's name; (b) click "Teilen-Link kopieren", observe the label flip to "✓ Kopiert" for about 1.6 seconds and the clipboard hold https://atelier.alchemy.store; (c) click a card, observe navigation to /buy/<that product's id>; (d) with the workspace's products all set to draft, reload, observe the grid area render blank with the chrome mock and hero still present and no message.
4. Demo gate: node tooling/verify/render-smoke.mjs commerce-payments/ui/storefront-preview renders both states with renderToString, fetch stubbed, 0 failures.
5. Verifier: node tooling/verify/compare.mjs commerce-payments/ui/storefront-preview --state default --docs http://127.0.0.1:4321 --app http://127.0.0.1:3020 --session-file tooling/verify/.labs-local/session.json (an owner session with the four sample products' real-world equivalents seeded) writes a report with page_errors: []; mismatch_ratio is read for the header and chrome-mock structure only, since the app's actual product names, prices and count are the seeded account's and the demo's are fictional sample data.