@shop-on/create-theme 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/create-theme",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Scaffolds a Shop-On storefront theme: `npm create @shop-on/theme <dir>`.",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "bin": {

package/template/.claude/skills/theme-dev/SKILL.md

@@ -64,6 +64,7 @@ src/
   config/            settings-*.json   theme-wide settings
   components/        template-renderer.tsx  core resolver (don't usually touch)
   server/            settings.ts (route server fns), enrich-adapter.ts (fetch-depth policy), template-loader.ts (loader config)
+  ai/                guide.md + recipes/*.json   what the editor's AI tools read — see below
 ```
 
 ## Core rules — read before authoring
@@ -264,6 +265,17 @@ A theme change is not finished when it type-checks — the artifact carries a ve
 
 Write the notes **for the merchant, not the diff**: what changes in their store, in their words. Match the file — plain bullets under the heading, no `### Fixed` subsections, no file names, no component names. "Prices now say when tax is included", not "added `taxIncludedCaption` to the price block".
 
+## AI guide + recipes (`src/ai/`)
+
+AI assistants connected to a store (Claude, ChatGPT), `shop-on theme mcp` and the theme editor's AI chat edit a theme through one set of editor tools. What they know about _this_ theme comes from `src/ai/`: `get_theme_guide` serves `guide.md`, `list_recipes` / `apply_recipe` serve `recipes/<handle>.json`.
+
+- **`guide.md`** — a designer's brief for the model, plain Markdown, ≤ 16 KB: what the theme is for, which section does which job, the settings that matter, what to avoid. Section, block and setting handles in backticks.
+- **`recipes/<handle>.json`** — named page builds, ≤ 20, each ≤ 32 KB, handle `[a-z0-9-]`. Shape: `{ "name", "description", "params": { "<id>": { "type": "text" | "collection" | "image" | …, "label", "required" } }, "position": "append" | "prepend" | "replace", "sections": [{ "type", "settings", "blocks" }] }`; a param is used as `"{{id}}"` inside a setting value.
+- **The rule is strict:** `ai/` holds exactly `guide.md` and `recipes/*.json`. No other file, subdir or dotfile — the build and the upload both refuse it.
+- **Recipes are checked at build — but only shallowly.** Every section/block type and setting id must exist, or `pnpm build` fails. Setting values are checked only when a merchant applies the recipe: a select value outside its options, an out-of-range number or a `palette:` ref the shop no longer has makes `apply_recipe` refuse the whole recipe. Keep literal values to the schema's options; leave colours to the theme's defaults.
+- **Optional params drop their line.** The editor tools store a rich-text value with nothing to show as `""` — `<p>{{tagline}}</p>` or `<a href="tel:{{phone}}">{{phone}}</a>` with the param omitted, or `<p>&nbsp;</p>` — so a theme that hides empty rich text drops it. A plain `text` setting, a button label or an FAQ row's question is not emptied for you: make that param required, or check the block renders nothing when it is blank.
+- **Keep it in step with the sections.** Adding, renaming or removing a section or block, or changing a setting the guide names, means editing `guide.md` and any recipe that uses it in the same change.
+
 ## Building in the editor (Save to source)
 
 You can also build a theme **visually in the real admin theme-editor** and persist the result to `src/`, instead of hand-editing JSON: `pnpm theme:editor` runs the theme's dev server + a dev-host gateway (`@shop-on/theme-dev-host`) that serves the editor API from `src/` with drafts held in memory.

package/template/.claude/skills/theme-dev/recipes/dynamic-sources.md

@@ -130,9 +130,9 @@ templates only; `null` elsewhere blanks it. Each key has one form:
   stripped, `data-dyn=` attributes removed) so the last inline pass can't turn
   description content into a live token.
 
-The theme supplies `collection: { title, getDescriptionHtml }` (a
-`DynamicSourceCollection`) from `fetchCollectionMeta` +
-`fetchCollectionDescriptionHtml`; the provider runs only when
+The theme supplies `collection: routeCollectionSource(meta, locale)` (a
+`DynamicSourceCollection`, from `@shop-on/theme-server/collection`, off the
+`fetchCollectionMeta` read); the provider runs only when
 `collectCollectionAttributeBindings(template)` includes `description`, so the
 lean meta read stays lean.
 
@@ -145,8 +145,16 @@ only**, in text/textarea/richtext like a product attribute.
 There is no whole-value page source and no body attribute: the page body is
 rendered from the route page by the theme's own section or block (the starter's
 `main-page`), so a binding would be a second path to the same HTML. The theme
-supplies `page: { title }` off the `fetchPage` read its page loader already
-makes, so the source costs no extra request.
+supplies `page: routePageSource(page, locale)` (`@shop-on/theme-server/page`)
+off the `fetchPage` read its page loader already makes, so the title costs no
+extra request.
+
+Always pass a route resource through its builder, never an inline
+`{ title }`: the builder also carries the lazy `getMetafields` provider behind
+the `collection_metafield` / `page_metafield` / `blog_metafield` /
+`article_metafield` sources (a merchant's own fields on that resource, same
+grammar and sinks as `product_metafield`). An inline object type-checks and
+silently renders every such binding's literal.
 
 ### Blog and article attributes
 
@@ -156,8 +164,9 @@ blanks everywhere else. Same shape as the page source: one key, `title`,
 inline token only — the body, the cover and the post list are rendered by the
 theme's own blocks and sections.
 
-Pass them through the theme's `TemplateRequest` as `article: { title }` (off the
-`fetchArticle` read) and `blog: { title }`. **Enrich after the resource
+Pass them through the theme's `TemplateRequest` as
+`article: routeArticleSource(article, locale)` (off the `fetchArticle` read)
+and `blog: routeBlogSource(blog, locale)` (both `@shop-on/theme-server/blog`). **Enrich after the resource
 resolves**: a loader that runs `loadTemplate` (load + enrich) in a
 `Promise.all` beside the fetch resolves the token against `null`. Split the load
 into a raw read and an `enrich` call (a `loadRawTemplate` helper, say). When the

package/template/.claude/skills/theme-dev/recipes/quality.md

@@ -16,14 +16,15 @@ it will be this file's **review** lines.
 ## Run the tools
 
 ```bash
-pnpm theme:check               # every check rule; exit 1 on any finding
+pnpm theme:check               # every check rule; exit 1 on any finding but a warning
 pnpm theme:check --release     # also theme-info: run before you hand the theme off
 pnpm theme:check --json        # for CI
 pnpm build                     # postbuild enforces the build lines
 ```
 
 The output is one line per finding, `file:line rule message`, followed by the
-recipe for each rule that fired.
+recipe for each rule that fired. A `(warning)` after the rule id prints but
+doesn't fail the run.
 
 The **audit** lines come from `shop-on theme audit`, in the `@shop-on/theme-cli`
 package:
@@ -96,12 +97,16 @@ anyone else installs the theme.
 | no default for `collection`, `product`, `product_list`, `metaobject(_list)`, `review(_list)` pickers | check: `tenant-picker-default`      | [picker-data.md](picker-data.md#no-defaults-for-tenant-specific-pickers) |
 | no literal colors in class names; tokens only                                                        | check: `literal-color`              | [styling.md](styling.md#rule-tokens-never-literals)                      |
 | no raw `<a href="/…">` to an internal path                                                           | check: `raw-internal-link`          | [SKILL.md § Don't do](../SKILL.md#dont-do)                               |
+| each `closest_*` resource has one unambiguous provider                                               | check: `closest-provider` (warning) | [dynamic-sources.md](dynamic-sources.md#closest-resources--closest_)     |
 | a section with nothing picked still looks intentional                                                | review                              | [section.md](section.md#preview-readiness)                               |
 | the layout holds at 375px                                                                            | review: the editor's mobile preview | [styling.md](styling.md#responsive)                                      |
 | settings read the way a merchant would name them                                                     | review                              | [input-settings.md](input-settings.md)                                   |
 
 `schema-label-key` skips labels with nothing to translate (`16px`, `/`).
 `tenant-picker-default` also catches a preset that fills a tenant picker.
+`closest-provider` warns on a second picker of one resource with no
+`provides` for it (only the first provides), one static block in two `each`
+lists, and a `provides` whose `from` or `each` names nothing on the schema.
 
 ## Suppressing a finding
 

package/template/README.md

@@ -20,8 +20,8 @@ never commit it. A store holds at most 5 of these credentials;
 `npx @shop-on/theme-cli theme credentials revoke <client-id>` frees one.
 
 `theme dev` runs the theme behind a `cloudflared` tunnel (install it first)
-and opens the hosted theme editor on a developer preview of it. Confirm the
-connection, and keep admin on the same store. `pnpm dev` still runs the
+and opens the hosted theme editor on a developer preview of it, with nothing
+to confirm. Keep admin on the same store. `pnpm dev` still runs the
 storefront on its own.
 
 Without logging in, scaffold with `npm create` and fill in `.env` yourself:
@@ -49,10 +49,15 @@ with a "missing" message naming the variable.
 | `pnpm theme:check`   | the quality bar's static rules; `--release` before handing off         |
 | `pnpm build`         | the theme artifact in `.output/`, with `release-notes.md` alongside it |
 
-`pnpm theme:editor --tunnel --env prod --slug <store-handle> --install <install-id>`
-exposes the gateway publicly, so the hosted admin's theme editor can preview
-your local theme. In the editor, open an **unpublished** install's actions
-menu → **Local dev preview** and paste the tunnel URL.
+To sell the theme on the Lite theme store, register at the developer portal
+and submit its source: `npx @shop-on/theme-cli theme source` writes the
+tarball to upload. Lite builds it and reviews the result; see the developer
+portal guide.
+
+`npx @shop-on/theme-cli theme dev` runs the theme behind the gateway and a
+tunnel, and opens the hosted admin's theme editor on your local theme. It makes
+a dev install in your store for this, the only kind of install the editor
+connects to a local theme.
 
 ## Layout
 

package/template/package.json

@@ -10,21 +10,21 @@
     "dev": "vite dev",
     "prebuild": "node scripts/backfill-defaults.mjs && oxfmt src",
     "build": "NITRO_PRESET=cloudflare_module vite build",
-    "postbuild": "node scripts/postbuild.mjs",
+    "postbuild": "node --import tsx scripts/postbuild.mjs",
     "test": "vitest run --passWithNoTests",
     "theme:check": "node scripts/theme-check.mjs",
     "theme:editor": "theme-dev-host"
   },
   "dependencies": {
     "@bprogress/core": "1.3.4",
-    "@shop-on/i18n": "^0.4.0",
-    "@shop-on/theme-contract": "^0.4.0",
-    "@shop-on/theme-loader": "^0.4.0",
-    "@shop-on/theme-react": "^0.4.0",
-    "@shop-on/theme-routes": "^0.4.0",
-    "@shop-on/theme-runtime": "^0.4.0",
-    "@shop-on/theme-server": "^0.4.0",
-    "@shop-on/theme-system": "^0.4.0",
+    "@shop-on/i18n": "^0.6.0",
+    "@shop-on/theme-contract": "^0.6.0",
+    "@shop-on/theme-loader": "^0.6.0",
+    "@shop-on/theme-react": "^0.6.0",
+    "@shop-on/theme-routes": "^0.6.0",
+    "@shop-on/theme-runtime": "^0.6.0",
+    "@shop-on/theme-server": "^0.6.0",
+    "@shop-on/theme-system": "^0.6.0",
     "@tailwindcss/vite": "4.3.3",
     "@tanstack/react-router": "1.170.45",
     "@tanstack/react-start": "1.169.3",
@@ -35,8 +35,8 @@
     "tailwindcss": "4.3.3"
   },
   "devDependencies": {
-    "@shop-on/theme-config": "^0.4.0",
-    "@shop-on/theme-dev-host": "^0.4.0",
+    "@shop-on/theme-config": "^0.6.0",
+    "@shop-on/theme-dev-host": "^0.6.0",
     "@spiriit/vite-plugin-svg-spritemap": "7.2.0",
     "@types/node": "26.6.5",
     "@types/react": "19.3.0",
@@ -45,6 +45,7 @@
     "gql.tada": "1.11.4",
     "happy-dom": "21.0.4",
     "oxfmt": "^0.74.0",
+    "tsx": "^4.23.15",
     "typescript": "7.0.2",
     "vite": "8.3.5",
     "vitest": "5.0.5"

package/template/src/ai/guide.md

@@ -0,0 +1,27 @@
+# Starter: the designer's guide
+
+Starter is a new theme in a neutral light palette. Rewrite this guide
+as the theme grows: say what it is for, which section does which job, and what
+to avoid. The editor's AI tools read this file, so a section missing from it is
+one they won't reach for.
+
+## How a page is put together
+
+- Templates: `index` (home), `product`, `collection`, `page`, `blog`,
+  `article`, `cart`, `search`, `list-collections`, `404`, `password`,
+  `policy`. Every template except `404` has its own `main-*` section, fixed to
+  it; `404` starts empty.
+- Groups: `header` holds the `header` section and `footer` holds the `footer`
+  section. They can be edited but not added to a page.
+
+## Sections by job
+
+**Open a page (hero)**
+
+- `hero`: an eyebrow line, a headline, body text and one button
+  (`cta_label`, `cta_url`). Keep the headline short; leave the button out
+  rather than pointing it nowhere.
+
+## What to avoid
+
+- Don't stack two `hero` sections.

package/template/src/server/settings.ts

@@ -107,7 +107,13 @@ export const getThemeSettingsFn = createServerFn({ method: "GET" })
 // return `null` when the handle misses so the route `notFound()`s. A resource
 // whose template is merchant-assignable (product / collection / page) should
 // load through the package's `resolveTemplateVariant` instead of `loadTemplate`,
-// so an unshipped `product.<variant>` falls back to the base document.
+// so an unshipped `product.<variant>` falls back to the base document. A
+// template's dynamic sources read its route resource: pass
+// `collection: routeCollectionSource(meta, locale)`, `page: routePageSource(page,
+// locale)`, `blog: routeBlogSource(blog, locale)` and `article:
+// routeArticleSource(article, locale)` (theme-server's `collection`, `page` and
+// `blog` subpaths) rather than building the object inline, so the theme picks
+// up every provider (descriptions, metafields) on upgrade.
 //
 // biome-ignore lint/suspicious/noExplicitAny: serializer requires it
 type TemplatePayload = Promise<any>;