@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## Unreleased
+
+- **Candidate pinning contract (local prerelease `0.4.0-mvp.0`, not published)**:
+  the install record separates declared compatibility (Node `>=20.9.0`, Yarn 4,
+  the `node-modules` linker, direct dependency ranges including `@thorprovider/types`
+  and the CLI itself, and `cliVersion`) from the resolved pin (exact `node_modules`
+  versions, the real `yarn.lock` content hash, and the package-owned asset BOM).
+  `doctor`/`update` validate the record against the live project and refuse to stamp
+  an incomplete or mismatched pin set; `doctor` compares the live declarations,
+  resolved versions, lockfile, and installed owned BOM against the record instead of
+  the record against itself. Only package-owned suite paths are hashed, so a user's
+  own skill/command files are neither stamped nor reported as drift.
+- **Composition manifest (in progress)**: a `storefront.config.json` manifest becomes
+  the source of truth for composition (theme, views, features, per-slot intents) and
+  the structural files are derived from it. This reuses the existing `recipes/` +
+  `archetypes.json` registry and the CLI rather than the LLM-driven view-edit path,
+  which is superseded: agents will delegate structural changes to the CLI and edit
+  only user-owned files. Coordinated with the in-progress `storefront-automation-commands`
+  and `deterministic-sf-init-cli` changes (shared registry and CLI).
+- **Project resolution**: only `create` takes a directory. Every other command resolves
+  the storefront from the current directory upward (looking for `storefront.config.json`)
+  and errors without writing when none is found.
+
 ## 0.4.0
 
 - **Renamed package**: `@thorprovider/create-storefront` → `@thorprovider/storefront`;

package/README.md

@@ -1,7 +1,7 @@
 ---
 title: "@thorprovider/storefront"
 purpose: "Deterministic storefront scaffolder and installable command suite for Thor Commerce"
-lastReviewed: "2026-10-01"
+lastReviewed: "2026-10-08"
 ---
 
 # @thorprovider/storefront
@@ -36,13 +36,18 @@ storefront it generates resolves its own dependencies from the registry.
 | Package manager | Yarn with the `node-modules` linker (for generated projects) |
 | OpenCode | a version that supports project skills in `.opencode/skills/` |
 | OS | macOS, Linux, Windows (via WSL) |
-| Network | access to the npm registry (the generated project installs its dependencies from it) |
+| Network | access to the npm registry — only for the first scaffold per machine (repeat scaffolds can run offline, see [troubleshooting](#flaky-network-etimedout)) |
 
 Generated projects use Yarn with the `node-modules` linker, not Plug'n'Play (PnP).
 Yarn 4 defaults to PnP, which Next.js 16's Turbopack cannot resolve from, so the
 scaffold writes a `.yarnrc.yml` setting `nodeLinker: node-modules` before installing
 dependencies. PnP is not used. You do not need to configure this yourself.
 
+The same `.yarnrc.yml` hardens installs for unreliable networks: `httpRetry: 10`
+and `networkConcurrency: 8`. The first successful scaffold warms the global Yarn
+cache (`~/.yarn/berry/cache`); repeat scaffolds then download no packages, and
+`YARN_ENABLE_OFFLINE_MODE=1` drops even the metadata requests.
+
 ### Install
 
 Run the scaffolder directly from npm — no global install required. `npx` and
@@ -64,10 +69,13 @@ it is where `.opencode/`, the Next.js app, and `lib/<name>/` live. Run the comma
 from the parent directory you want the project created in.
 
 In a terminal, `create` runs an interactive wizard for any input you omit (name,
-site name, backend URL, preset — Maia is preselected). Without a terminal, every
-required input must be passed as a flag; the command fails fast and writes nothing
-rather than guessing. Brand color is never asked by the wizard — apply it later with
-`/sf-theme`, or pass `--brand` on the command line.
+site name, backend URL, preset — Maia is preselected). Pressing Enter on an empty
+prompt accepts the suggested default: the storefront name is suggested from the
+target directory basename, and the site name from the Title Case of that name
+(`my-shop` → `My Shop`). Without a terminal, every required input must be passed
+as a flag; the command fails fast and writes nothing rather than guessing. Brand
+color is never asked by the wizard — apply it later with `/sf-theme`, or pass
+`--brand` on the command line.
 
 Once the package is installed as a dependency, the shorter binary form is available:
 
@@ -96,14 +104,15 @@ storefront create my-shop \
 | --- | --- | --- |
 | `<dir>` (positional) | target project directory (created if missing) | required |
 | `--name <name>` | kebab-case storefront name = `lib/<name>/` = `__STOREFRONT__` | prompted in the wizard |
-| `--site-name <name>` | human site name (`__SITE_NAME__`) | `<name>` |
+| `--site-name <name>` | human site name (`__SITE_NAME__`) | Title Case of `<name>` (`my-shop` → `My Shop`) |
 | `--backend-url <url>` | Medusa backend URL | `http://localhost:9000` |
 | `--preset <preset>` | visual preset: `maia`, `nova`, `vega`, `luma`, `lyra`, `mira` | prompted in the wizard (Maia preselected) |
 | `--brand <color>` | named brand color overriding preset primary/nav/ring tokens (never prompted) | none |
 | `--force`, `-f` | overwrite files that already exist | off |
 
-The pipeline runs: preconditions → Next.js base → shadcn base with the preset →
-`.yarnrc.yml` (`nodeLinker: node-modules`) → dependency install → template copy +
+The pipeline runs: preconditions → Next.js base (files only, `--skip-install`) →
+`.yarnrc.yml` (`nodeLinker: node-modules`, retry and concurrency hardening) →
+shadcn base with the preset → dependency install → template copy +
 placeholder substitution → default-page removal → `.env.local` + theme → suite
 install into `.opencode/`.
 
@@ -137,19 +146,57 @@ it incrementally from OpenCode:
 
 ### Backend configuration
 
-Generated projects expect a Medusa backend. `create` writes a `.env.local` with the
-backend URL you passed and blank placeholders for the rest:
+Generated projects resolve an explicit single-store context from the host
+environment before any commerce call. `create` writes a git-ignored `.env.local`
+with the data source and backend URL you passed, a generated cookie secret, and
+blank placeholders for the store identity, plus a committed `.env.example` that
+documents every variable (never a real secret):
 
 ```bash
-MEDUSA_BACKEND_URL=http://localhost:9000
-MEDUSA_REGION_ID=
+# .env.local (git-ignored)
+THOR_DATA_SOURCE=medusa
+MEDUSA_BASE_URL=http://localhost:9000
 MEDUSA_PUBLISHABLE_KEY=
+MEDUSA_REGION_ID=
+MEDUSA_SALES_CHANNEL_ID=
+THOR_STORE_ID=my-shop
+THOR_CURRENCY_CODE=
+THOR_SESSION_SECRET=<generated per install>
 ```
 
-Set `MEDUSA_REGION_ID` and `MEDUSA_PUBLISHABLE_KEY` as needed, then restart
-`yarn dev`. The storefront shows no catalog data until these are set (see
-[Backend not configured](#backend-not-configured)). During local development you can
-use the `mock` adapter data source instead of a live backend.
+The store context is **explicit and validated**:
+
+- `THOR_STORE_ID` — stable store identity (seeded from the manifest name).
+- `MEDUSA_SALES_CHANNEL_ID` — the sales channel the store is scoped to.
+- `MEDUSA_REGION_ID` — the backend region that supplies currency, countries, and
+  shipping.
+- `THOR_CURRENCY_CODE` — ISO 4217 currency, taken from the environment; it is
+  **never hardcoded** in the app.
+- `THOR_SESSION_SECRET` — host-only cookie signing secret (≥16 chars, 32
+  recommended). Generate your own; never commit or log it.
+
+`THOR_DATA_SOURCE` selects the mode **explicitly** and is never inferred from a
+failure:
+
+- `THOR_DATA_SOURCE=mock` renders labelled demo data (`Datos de demostración`).
+  The store context must match the mock fixture: channel
+  `mock-sales-channel`, region `mock-region-us` (currency `USD`) or
+  `mock-region-eu` (currency `EUR`). The committed `.env.example` ships these.
+- `THOR_DATA_SOURCE=medusa` uses the real backend. A missing provider, invalid
+  configuration, or a provider failure is surfaced as a **visible error** — the
+  store never silently degrades to demo data. Until `MEDUSA_PUBLISHABLE_KEY` is
+  set, the home view shows the error notice instead of a fake catalog. Fill in
+  the variables, then restart `yarn dev` to serve real catalog data.
+
+The guest flow is backend-authoritative end to end: the signed host cookie
+issues a shopper identity and binds a persistent backend cart; the PDP adds the
+explicitly selected variant; the cart and checkout render the backend's totals;
+checkout applies the one approved manual TEST provider after shipping and
+completes the cart with its native discriminator. An ambiguous completion is
+never retried — the shopper reconciles the committed cart, and the active cart
+is cleared only after a confirmed order. No card data is collected at launch.
+
+For offline-only work set `THOR_DATA_SOURCE=mock` on purpose.
 
 ### Troubleshooting / Known Issues
 
@@ -157,54 +204,38 @@ Each entry below follows the same shape: **cause** → **symptom** → **remedy*
 
 #### Ancestor `.opencode/`
 
-- **Cause**: the project is created under a directory tree in which an ancestor
-  directory already contains a `.opencode/`.
-- **Symptom**: OpenCode resolves the wrong command set — `/sf-add-view`, `/sf-view`,
-  and `/sf-theme` run commands from the ancestor's `.opencode/` instead of the ones
-  this package installed, so you see stale or unrelated behaviour.
-- **Remedy**: scaffold in a clean root with no ancestor `.opencode/` (for example a
-  fresh directory outside the monorepo), or remove/relocate the ancestor `.opencode/`
-  before opening the project.
+- **Cause**: an ancestor directory already contains a `.opencode/`.
+- **Symptom**: OpenCode resolves the wrong command set (`/sf-add-view`, `/sf-view`, `/sf-theme`), so you see stale or unrelated behaviour.
+- **Remedy**: scaffold in a clean root with no ancestor `.opencode/`, or remove/relocate the ancestor `.opencode/` before opening the project.
 
 #### Non-empty target directory
 
-- **Cause**: `create` runs against a directory whose `lib/<name>/` already exists (a
-  previous scaffold with the same name), or whose root is already a Next.js project.
-- **Symptom**: the run stops at the preconditions stage with
-  `lib/<name>/ already exists — refusing to overwrite`.
-- **Remedy**: choose a different `--name`, or remove the existing `lib/<name>/`
-  directory. To extend an existing storefront instead of creating one, use
-  `/sf-add-view`. `create-next-app` also refuses to initialize a directory that is
-  already a Next.js project unless it can reuse it; run `create` in an empty directory.
+- **Cause**: `lib/<name>/` already exists, or the root is already a Next.js project.
+- **Symptom**: the run stops at the preconditions stage with `lib/<name>/ already exists — refusing to overwrite`.
+- **Remedy**: choose a different `--name`, or remove the existing `lib/<name>/`. To extend an existing storefront, use `/sf-add-view`; run `create` in an empty directory.
 
 #### Missing or invalid `--preset`
 
-- **Cause**: `--preset` was omitted (in a non-interactive run) or the value is not one
-  of the recognized presets.
-- **Symptom**: the run stops at the input-validation stage with
-  `--preset must be one of: maia, nova, vega, luma, lyra, mira`.
-- **Remedy**: pass `--preset` with one of `maia`, `nova`, `vega`, `luma`, `lyra`,
-  `mira`. In a terminal the wizard preselects `maia`, so the preset is only required
-  on the command line for non-interactive runs.
+- **Cause**: `--preset` was omitted (non-interactive) or is not a recognized preset.
+- **Symptom**: the run stops at input validation with `--preset must be one of: maia, nova, vega, luma, lyra, mira`.
+- **Remedy**: pass one of those presets. In a terminal the wizard preselects `maia`, so the flag is only required for non-interactive runs.
 
 #### Yarn Plug'n'Play / linker
 
 - **Cause**: a generated project installed with Yarn's default PnP linker.
-- **Symptom**: Next.js 16's Turbopack fails to resolve the Next.js package
-  (`Could not find the Next.js package`).
-- **Remedy**: this is why `create` writes `.yarnrc.yml` with
-  `nodeLinker: node-modules` before installing. If you set up the project manually,
-  add that file and re-run `yarn install` so a real `node_modules/` is materialized.
-  Do not use PnP.
+- **Symptom**: Next.js 16's Turbopack fails to resolve Next.js (`Could not find the Next.js package`).
+- **Remedy**: `create` writes `.yarnrc.yml` with `nodeLinker: node-modules` before installing; if you set the project up manually, add that file and re-run `yarn install`. Do not use PnP.
+
+#### Flaky network (ETIMEDOUT)
+
+- **Cause**: an unstable connection stalls registry requests mid-transfer (`RequestError … AggregateError [ETIMEDOUT]`).
+- **Remedy**: the scaffolded `.yarnrc.yml` sets `httpRetry: 10` and `networkConcurrency: 8`; that run warms the global cache (`~/.yarn/berry/cache`), which later scaffolds reuse. For offline re-scaffolding run `YARN_ENABLE_OFFLINE_MODE=1 storefront create <dir> …`; the first scaffold per machine still needs one successful online run.
 
 #### Backend not configured
 
-- **Cause**: `MEDUSA_REGION_ID` / `MEDUSA_PUBLISHABLE_KEY` (or a reachable backend) are
-  not set in `.env.local`.
-- **Symptom**: the storefront renders its layout but shows no catalog data.
-- **Remedy**: fill in the variables in [Backend configuration](#backend-configuration)
-  and restart `yarn dev`, or use the `mock` adapter data source during local
-  development.
+- **Cause**: `THOR_DATA_SOURCE=medusa` but `MEDUSA_BASE_URL`/`MEDUSA_PUBLISHABLE_KEY` are missing, empty, or unreachable.
+- **Symptom**: the storefront renders a visible error notice (`role="alert"`) instead of backend data; real-mode failures never degrade to a fake catalog.
+- **Remedy**: fill in the variables in [Backend configuration](#backend-configuration) and restart `yarn dev`. For offline work set `THOR_DATA_SOURCE=mock` on purpose.
 
 ---
 
@@ -212,13 +243,18 @@ Each entry below follows the same shape: **cause** → **symptom** → **remedy*
 
 ```
 <project>/.opencode/
-  storefront.json            # { version, installedAt } — what generation is installed
+  storefront.json            # install record: { version, installedAt, pinning }
+                             # pinning separates declared ranges from the resolved
+                             # versions, yarn.lock hash, and owned asset BOM
   commands/
     sf-add-view.md
     sf-view.md
+    sf-feature.md
     sf-theme.md
   skills/
-    sf-view-gen/             # assets/templates/views/, assets/recipes/, scripts/validate.mjs
+    storefront-workflow/     # the four phases + CLI/manifest authority
+    sf-view-gen/             # assets/recipes/, scripts/validate.mjs
+    sf-feature/
     sf-theme-gen/            # assets/
     nextjs-shadcn/
     shadcn-theming/
@@ -229,18 +265,123 @@ Each entry below follows the same shape: **cause** → **symptom** → **remedy*
 
 Each skill carries the templates, recipes, and scripts it uses inside its own
 directory. Skills address them by relative path, so nothing needs the package to be
-located on disk at generation time.
+located on disk at generation time. The feature command is
+[`commands/sf-feature.md`](./commands/sf-feature.md) and the workflow model is
+[`skills/storefront-workflow/SKILL.md`](./skills/storefront-workflow/SKILL.md).
+
+## Workflow: bootstrap → compose → customize → verify
+
+The project manifest (`storefront.config.json`) is the structural source of truth;
+the `storefront` CLI is the only writer of derived files; the developer/agent edits
+only user-owned files. Read the installed `storefront-workflow` skill for the full
+model. Every command runs from inside the project (no directory argument).
+
+| Phase | Authority | Command |
+| --- | --- | --- |
+| **Bootstrap** | CLI only | `npx @thorprovider/storefront create <dir> --name <name> --preset <preset>` |
+| **Compose** | CLI only (agents choose, CLI writes) | `view add\|remove`, `feature add\|remove`, `theme --mode` |
+| **Customize** | developer/agent | edit user-owned `content.ts`/`props.ts`/`data.ts`/`schema.ts`/`mappers.ts` |
+| **Verify** | CLI + build | `npx @thorprovider/storefront sync`, `doctor`, `yarn build` |
+
+**Ownership classes.** *Derived* files (`views/index.ts`, `views/registry.ts`,
+`index.tsx`, `registry.tsx`, `catalog.ts`, `runtime.ts`, `spec/index.ts`,
+`state.ts`, `handlers.ts`, `features/*/adapter.ts`) are regenerated by the CLI and
+never hand-edited. *User-owned* files (content, props, data, local schema, mapper
+bodies) are consumed through thin derived wrappers and survive `sync` and removal.
+*External* files (`app/layout.tsx`, `app/globals.css`) belong to create-next-app +
+shadcn; the CLI only appends idempotent markers.
+
+**Curated MVP defaults.** Standalone views `home`, `category`, `product`; the
+`checkout` feature (which owns the `checkout` view — a direct `view add checkout`
+is rejected, use `feature add checkout`). Held post-MVP and rejected before any
+write: `user-panel`, recommendations, and sections. A generated storefront is not a
+complete commerce implementation: the `checkout` feature ships structural wiring
+only, and the purchase flow is owned by the separate `single-tenant-commerce-mvp`
+change.
+
+**Prerequisites and pinning.** Node `>=20.9.0`, `node-modules` linker, and the
+canonical Yarn pinned in the generated `package.json` as
+`"packageManager": "yarn@4.5.1"` (Corepack resolves it; the scaffold runs every
+install under that version). The generated project pins an exact compatible
+candidate toolset and installs the local `@thorprovider/*` packages from packed
+tarballs via Yarn `resolutions` (`--packs <dir>`), with no publish and no
+workspace import. No package-manager safety policy is suppressed: the generated
+`.yarnrc.yml` sets no `npmPreapprovedPackages`, and the pinned versions are
+published past Yarn's age gate. `doctor` reports the observed linker/Node/Yarn
+against the declared ranges and exits non-zero on a mismatch instead of a false
+clean stamp.
+
+### Configurable composition (E1)
+
+The composition engine is a truthful semantic catalog plus a structured
+`inspect → plan → apply` boundary. Run these inside the project:
+
+```bash
+storefront inspect --json
+storefront plan --operations operations.json [--out plan.json] [--json]
+storefront apply --plan plan.json [--json]
+```
+
+- **`inspect --json`** is read-only and deterministic: `formatVersion: 1` /
+  `catalogVersion: 1`, every slot/variant with `executable` or `held` + a reason, and a
+  capability catalog with `verified`/`unverified` state. A held or unverified unit is
+  never reported as available.
+- **`plan`** validates the whole intended state and emits before/after fingerprints and
+  the exact derived-file diff. Without `--out` it writes nothing and prints the plan to
+  stdout; with `--out` it writes only a safe plan artifact. `--out` is refused
+  (`E_OUT_PATH_REFUSED`) for owned, derived, secret-bearing, or installation paths and
+  for the operation input.
+- **`apply`** is the only composition mutation. It applies from the recorded
+  before-state, reports a **verified no-op** at the recorded after-state, and rejects
+  anything else as stale (`E_STALE_PLAN`); concurrent runs are serialized by a local
+  lock. A handled write failure rolls back every touched file. An abrupt process kill is
+  **not** crash-atomic — the manifest is written last and `sync` detects and repairs the
+  divergence.
+
+The operations envelope is `{ "formatVersion": 1, "operations": [ ... ] }` (missing or
+different `formatVersion` → `E_INVALID_ENVELOPE`). Operation names are
+`view.add|remove|configure` and `feature.add|remove|configure`; `view add|remove` and
+`feature add|remove` remain thin aliases over the same engine.
+
+**What E1 proves.** The only executable non-default swap is `home.benefits`
+`Feature1 → Feature2` (identical `BenefitsItem[]` data shape, no bridge); every bridged
+variant is `held`. A feature may declare a `config` and `mounts`; the bounded `benefits`
+feature mounts at `home.benefits` with `{ "presentation": "compact" | "detailed" }`,
+claims the slot exactly once, and preserves user-owned content on removal. Checkout
+keeps its existing feature-owned route only — unproven checkout variants or route
+options are rejected (`E_UNPROVEN_CHECKOUT_OPTION`). The category filter's action is
+**held** (`unverified`, owner E2) and its control is omitted rather than exposed as a
+no-op; catalog search/filters (E2) and composable sections (E3) are **not** implemented
+here.
 
 ## Commands
 
 | Command | Purpose |
 | --- | --- |
-| `/sf-add-view <view>` | Add one view incrementally (`product`, `category`, `checkout`, `user-panel`) |
-| `/sf-view <view> <change>` | Modify an existing view's spec, preserving structure |
+| `/sf-add-view <view>` | Add a curated view via the CLI (`product`, `category`; `checkout` via `/sf-feature`) |
+| `/sf-view <view> <change>` | Customize a view's user-owned content/props/data, then `sync` |
+| `/sf-feature add\|remove <name>` | Add/remove a feature bundle (e.g. `checkout`) via the CLI |
 | `/sf-theme` | Customize OKLCH color tokens (light/dark), typography, and identity metadata |
 
 Scaffolding itself is `npx @thorprovider/storefront create <dir>` — there is no
-`/sf-init` command; the wizard lives in the CLI and is deterministic.
+`/sf-init` command; the wizard lives in the CLI and is deterministic. The color
+mode is likewise a CLI capability: `npx @thorprovider/storefront theme --mode light|dark|system`.
+
+## Philosophy: determinism first; the LLM only where there is judgment
+
+A storefront task is one of three kinds, and the tool follows the kind:
+
+- **Deterministic** (output is a pure function of input) → a CLI subcommand with flags
+  (e.g. `storefront theme --mode`). Repeatable, reviewable, no model in the loop.
+- **Mixed** → split it: the script applies the deterministic part, the LLM decides the
+  judgment part (`/sf-theme` decides the mode; `storefront theme --mode` applies it).
+- **Pure judgment** → an `sf-*` skill (e.g. `/sf-view`): variant selection, copy, and
+  layout choices live here.
+
+**Test criterion**: if you can assert the result without a model ("after this, the file
+contains X"), it must be a script; if you cannot, it is skill work. LLM edits are
+non-deterministic and expensive to review, so keep the judgment-heavy work where a
+model adds value and make the rest a reliable script.
 
 ## Design guarantees
 
@@ -252,40 +393,59 @@ Scaffolding itself is `npx @thorprovider/storefront create <dir>` — there is n
   installer copies anything.
 - **Stack-constrained**: UI comes only from `@thorprovider/blocks`; data only from
   `@thorprovider/adapters` and `@thorprovider/runtime/commerce`.
-- **Varied output**: a recipe registry lets the skills pick block variants and optional
-  sections (testimonials, FAQ, statistics, logo cloud, pricing) from your description,
-  so sites are not identical.
+- **Truthful output**: a versioned recipe/catalog exposes every slot and variant with an
+  `executable` or `held` status and a reason. Only executable variants render; a held
+  variant is rejected before any write, so a site is never presented with a choice that
+  silently does nothing. E1 ships a small proven set (`home.benefits` `Feature1`↔
+  `Feature2`); bridged variants and optional sections stay held.
 
 ## Generated project structure
 
-Each view is a self-contained module. Shared files compose whatever the view barrel
-exports and never name a view, so adding one is a copy plus a single registration.
+Each view is a self-contained module. The CLI generates the barrels and wiring
+from the manifest; shared files compose whatever the barrel exports and never name
+a view. Only user-owned files (marked `*`) are hand-edited.
 
 ```
 lib/<name>/
-  catalog.ts, registry.tsx, runtime.ts, handlers.ts, state.ts   # shell; compose the barrel
-  mappers.ts                                                   # CardProduct -> FeaturedProduct / CategoryCard
-  spec/index.ts, spec/page-root.ts, spec/types.ts               # routes built from the barrel
+  catalog.ts, registry.tsx, runtime.ts, handlers.ts, state.ts   # derived shell; compose the barrel
+  mappers.ts *                                                  # user-owned: CardProduct -> block props
+  shell/
+    content.ts *                                                # user-owned: wordmark accents + footer newsletter
+    props.ts *                                                  # user-owned: shell element props
+  spec/index.ts, spec/page-root.ts, spec/types.ts               # derived routes built from the barrel
   views/
-    index.ts            # barrel: export const views: ViewModule[] = [home, ...]
-    types.ts            # ViewModule contract
-    sections/*.tsx      # optional-section fragments (testimonials, faq, ...)
-    home/index.tsx      # one folder per view
-    product/index.tsx
-    category/index.tsx
-    checkout/index.tsx
-    user-panel/index.tsx
+    index.ts            # derived server barrel: export const views: ViewModule[] = [home, ...]
+    registry.ts         # derived client barrel: viewRegistries (no server loaders)
+    types.ts            # ViewModule / ViewRegistry contract
+    home/
+      index.tsx         # derived thin wrapper (imports ./content, ./props, ./data)
+      registry.tsx      # derived 'use client' component mappings
+      content.ts *      # user-owned copy/data
+      props.ts *        # user-owned element props
+      data.ts *         # user-owned loader shaping
+      schema.ts *       # user-owned local Zod mirror
+    product/ category/ checkout/   # same shape
 ```
 
-A view folder ships the package's default block variants; `/sf-add-view` picks the
-intent/variant from your description (validated by the skill's `scripts/validate.mjs`)
-and substitutes only the imported block identifier. The scaffold templates live at
-the package root, and the view templates travel inside the skills that use them:
+The shell's derived `spec/index.ts` imports the user-owned `shell/props.ts`
+(`...navbarShellProps`, `...footerShellProps`) and composes it **last**, so the brand
+surface and footer copy are configured without touching derived files. Configure
+`shell/content.ts` (`logoAccent`/`brandAccent`, `navbarClassName`/`footerClassName`,
+`brandDescription`, `linkColumns`); defaults are neutral and link only to served routes
+(`/`, `/categorias`, `/checkout`), never dead `#` links. `newsletter` defaults to `false`
+and the scaffold ships no submit callback, so a content-only newsletter renders no form
+— never a fake form.
+
+A view's derived `index.tsx` imports the user-owned `content.ts`/`props.ts`/
+`data.ts`, so a customization changes real spec/loader output and survives `sync`.
+`npx @thorprovider/storefront view add <view>` chooses the intent/variant from the
+registry, writes the derived files, and regenerates the barrels; the agent edits
+only the user-owned files. The scaffold templates live at the package root:
 
 ```
-assets/templates/app/                                 # shell (copied by `create`)
-assets/templates/views/home/                          # home (copied by `create`)
-skills/sf-view-gen/assets/templates/views/<view>/     # the other views (copied by /sf-add-view)
+assets/templates/app/                                 # shell (generated by `create`)
+assets/templates/views/home/                          # home (generated by `create`)
+assets/templates/views/<view>/                        # the other views (generated by `storefront view add`)
 ```
 
 ## Development
@@ -301,24 +461,13 @@ node bin/storefront.js doctor <tmp>                # report the recorded version
 node scripts/render-templates.mjs <tmp> my-shop    # re-render templates only (no install; fast loop)
 ```
 
-`scripts/render-templates.mjs` is the same renderer the `create` action uses for
-stage 6. It copies the templates and substitutes placeholders without touching
-dependencies, so iterating on a template against a persistent project (e.g.
-`projects/<name>/`) costs seconds and no network.
-
-`npm pack` exists to verify a different thing: **what actually ships to npm** —
-the `files` list, and that every asset travels inside its skill. It is only
-meaningful at these moments:
-
-| Moment | Action |
-| --- | --- |
-| Day-to-day development | Nothing — use the local binary above |
-| Changing `files`, moving assets, adding or removing directories | `npm pack --dry-run` to list what would ship |
-| CI, before publishing | `yarn check-assets` + `npm pack --dry-run` as a guard |
-| Publishing a release | `npm pack` / `yarn npm publish` — the real tarball |
-
-A generated `.tgz` goes stale the moment the tree changes, so it is not a
-development tool. Keep it out of the working tree.
+`scripts/render-templates.mjs` is the same renderer `create` uses for stage 6; it copies
+templates and substitutes placeholders without touching dependencies, so iterating on a
+template costs seconds and no network. `npm pack` verifies a different thing — **what
+actually ships to npm** (the `files` list, and that every asset travels inside its
+skill). Use it only when `files`/assets change or before a release (`npm pack --dry-run`
+to list; `yarn check-assets` + `npm pack --dry-run` in CI). A generated `.tgz` goes
+stale the moment the tree changes, so keep it out of the working tree.
 
 ## Maintenance
 

package/assets/templates/app/app/[[...slug]]/page.tsx

@@ -2,16 +2,27 @@
 
 import { notFound } from 'next/navigation'
 import { __STOREFRONT_CAMEL__App } from '@/lib/__STOREFRONT__/runtime'
+import { readCartStateForRender } from '@/lib/__STOREFRONT__/cart-state'
 import { StorefrontRenderer } from './renderer'
 
 export const { generateMetadata, generateStaticParams } = __STOREFRONT_CAMEL__App
 
 export default async function Page({
   params,
+  searchParams,
 }: {
   params: Promise<{ slug?: string[] }>
+  searchParams: Promise<Record<string, string | string[] | undefined>>
 }) {
-  const data = await __STOREFRONT_CAMEL__App.getPageData({ params })
+  // The raw URL search params are forwarded to the loader, which validates them
+  // through the canonical boundary before any commerce call (E2 task 5.1).
+  const data = await __STOREFRONT_CAMEL__App.getPageData({ params, searchParams })
   if (!data) return notFound()
-  return <StorefrontRenderer {...data} />
+
+  // Read the signed cookie and load the backend cart for the initial render.
+  // This never creates a cart; a guest identity is issued by a Server Action.
+  const cartState = await readCartStateForRender()
+  const initialState = { ...(data.initialState ?? {}), ...cartState }
+
+  return <StorefrontRenderer {...data} initialState={initialState} />
 }

package/assets/templates/app/app/layout.tsx

@@ -2,10 +2,12 @@
 
 import type { Metadata } from 'next'
 import { Geist } from 'next/font/google'
+import { ThemeProvider } from 'next-themes'
 import { StorefrontProvider } from '@thorprovider/runtime/host-glue/providers'
 import { themeVarsToCss, themeTokensToVars } from '@thorprovider/runtime/render-core/theme'
 import { DEFAULT_THEME_TOKENS } from '@thorprovider/runtime/contracts'
 import { registry } from '@/lib/__STOREFRONT__/registry'
+import { getSiteUrl } from '@/lib/__STOREFRONT__/store-context'
 import './globals.css'
 
 const geist = Geist({
@@ -15,20 +17,32 @@ const geist = Geist({
 
 const themeCss = themeVarsToCss(themeTokensToVars(DEFAULT_THEME_TOKENS))
 
+// The canonical public origin is optional: when THOR_SITE_URL is unset no base
+// URL is invented. `metadataBase` is left undefined in that case.
+const siteUrl = getSiteUrl()
+
 export const metadata: Metadata = {
+  metadataBase: siteUrl ? new URL(siteUrl) : undefined,
   title: '__SITE_NAME__',
   description: 'Tienda online de __SITE_NAME__.',
+  openGraph: {
+    title: '__SITE_NAME__',
+    description: 'Tienda online de __SITE_NAME__.',
+    url: siteUrl,
+  },
 }
 
 export default function RootLayout({
   children,
 }: Readonly<{ children: React.ReactNode }>) {
   return (
-    <html lang="es" className={geist.variable}>
+    <html lang="es" className={geist.variable} suppressHydrationWarning>
       <body className="font-sans antialiased">
-        <StorefrontProvider themeCss={themeCss} registry={registry}>
-          {children}
-        </StorefrontProvider>
+        <ThemeProvider attribute="class" defaultTheme="__STOREFRONT_MODE__" enableSystem>
+          <StorefrontProvider themeCss={themeCss} registry={registry}>
+            {children}
+          </StorefrontProvider>
+        </ThemeProvider>
       </body>
     </html>
   )

package/assets/templates/app/app/robots.ts

@@ -0,0 +1,13 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/app/robots.ts)
+// Always served. Points at the sitemap only when THOR_SITE_URL is configured.
+
+import type { MetadataRoute } from 'next'
+import { robotsSitemapUrl } from '@/lib/__STOREFRONT__/spec/seo'
+import { getSiteUrl } from '@/lib/__STOREFRONT__/store-context'
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: { userAgent: '*', allow: '/' },
+    sitemap: robotsSitemapUrl(getSiteUrl()),
+  }
+}

package/assets/templates/app/app/sitemap.ts

@@ -0,0 +1,12 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/app/sitemap.ts)
+// Lists the storefront's fixed routes. Absolute URLs are emitted only when
+// THOR_SITE_URL is configured; otherwise the sitemap is empty (no invented URL).
+
+import type { MetadataRoute } from 'next'
+import { __STOREFRONT_CAMEL__Spec } from '@/lib/__STOREFRONT__/spec'
+import { sitemapUrls } from '@/lib/__STOREFRONT__/spec/seo'
+import { getSiteUrl } from '@/lib/__STOREFRONT__/store-context'
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  return sitemapUrls(__STOREFRONT_CAMEL__Spec.routes ?? {}, getSiteUrl()).map((url) => ({ url }))
+}