Modernize Liquid Loom for Shopify 2026 native theme workflows

CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes follow [Keep a Changelog](https://keepachangelog.com/) and t
 
 ## [Unreleased]
 
+### Added
+
+- Shopify-native component CSS and JavaScript in the reference storefront through `{% stylesheet %}` and `{% javascript %}` tags.
+- Theme-block-first product composition with merchant-reorderable vendor, title, price, purchase, description, `@theme`, and `@app` blocks.
+- Shopify standard storefront view events for product, collection, recommendation, and cart surfaces, plus cart mutation through `Shopify.actions.updateCart()` with the native product form retained as the no-JavaScript fallback.
+- Shopify `color_palette` design tokens and `<shopify-account>` customer-account integration in the fresh reference theme.
+- A documented compiled-branch/deployment-repository workflow and opt-in GitHub Actions recipe for Shopify GitHub theme integration.
+- A complete Shopify 2026 modernization plan covering architecture, compatibility constraints, implementation order, and real-store acceptance criteria.
+
+### Changed
+
+- Fresh projects now default to Shopify-native static/component assets with `viteConfig: false` instead of requiring a Vite/Tailwind storefront bundle.
+- Vite and Tailwind remain supported framework integrations but are now documented as explicit optional asset strategies rather than the framework's product identity.
+- The reference product, header, predictive search, collection, featured collection, and cart surfaces now demonstrate current Shopify-native platform primitives.
+- The embedded `create-liquid-loom` starter stays byte-for-byte synchronized with the modernized reference storefront and targets Shopify CLI 4.8+ for new projects.
+- README, recipes, and roadmap now describe Liquid Loom as a deterministic engineering layer for Shopify Liquid themes and sequence platform modernization after the `0.3` project-intelligence work.
+
+### Removed
+
+- The fresh starter's default global Vite entrypoint, Tailwind stylesheet source, and bundled `theme.js`/`style.css` architecture.
+- The obsolete default Vite configuration from the reference project and embedded starter. Existing projects that explicitly enable Vite remain supported.
+
 ## [0.2.0] - 2026-09-09
 
 ### Added

ROADMAP.md

@@ -73,7 +73,38 @@ Now proving:
 
 See [Project model](docs/PROJECT_MODEL.md) and [Shopify Liquid July 2026 developer preview](docs/LIQUID_JULY_2026_PREVIEW.md).
 
-## 0.4 - Extension surface, if earned
+## 0.4 - Shopify 2026 platform modernization
+
+Modernize fresh-project defaults and the reference storefront around Shopify's current native theme capabilities without weakening the `0.2` ownership/migration guarantees or the `0.3` project-intelligence model.
+
+Implemented in the modernization PR:
+
+- [x] make Shopify-native `{% stylesheet %}` / `{% javascript %}` component assets the preferred fresh-project path where practical;
+- [x] keep Vite and Tailwind as explicit, tested optional asset strategies rather than Liquid Loom's product identity;
+- [x] make theme blocks and merchant-reorderable composition central to the reference storefront, especially product information and purchase surfaces;
+- [x] implement relevant Shopify standard storefront view events and cart actions in the reference theme;
+- [x] move the reference color system to `color_palette` plus semantic CSS custom properties;
+- [x] adopt the `<shopify-account>` component with a merchant-configurable account menu;
+- [x] add a documented compiled branch/deployment-repository workflow and opt-in GitHub Actions recipe for Shopify GitHub integration;
+- [x] target Shopify CLI 4.8+ in fresh scaffolds and document disposable dev-store validation;
+- [x] preserve explicit `stable` / `july-2026-preview` modes and keep preview syntax outside the stable release gate;
+- [x] preserve zero-migration adoption and existing asset pipelines for established themes;
+- [x] add automated capability tests and keep the reference storefront byte-for-byte synchronized with the embedded starter.
+
+Still requiring real Shopify evidence before calling the milestone complete:
+
+- [ ] preview the modernized fresh scaffold on a Shopify development store;
+- [ ] verify product-block reordering and app-block placement in Theme Editor;
+- [ ] verify `<shopify-account>` with customer accounts enabled and disabled;
+- [ ] verify palette editing through Theme Editor;
+- [ ] verify standard storefront event/action behavior in a real browser session;
+- [ ] verify the compiled deployment branch against Shopify GitHub integration and confirm Shopify-originated commits do not create a deployment loop;
+- [ ] run the modernization against at least one established client-style theme without changing its existing asset pipeline;
+- [ ] extend project intelligence only if those real workflows expose new statically provable relationships worth modeling.
+
+See [Shopify 2026 platform modernization](docs/SHOPIFY_2026_MODERNIZATION.md) for the full architecture decisions, compatibility constraints, implementation order, and acceptance criteria.
+
+## 0.5 - Extension surface, if earned
 
 Only after repeated consumer needs justify a public extension API:
 
@@ -97,5 +128,6 @@ Only after repeated consumer needs justify a public extension API:
 - Requiring migration before an existing theme can receive value from Liquid Loom.
 - Guessing dynamic Liquid relationships in order to make the project model look more complete.
 - Making developer-preview Liquid syntax the default before Shopify stabilizes it.
+- Introducing a second storefront runtime to imitate headless frameworks.
 
 See [Validation](docs/VALIDATION.md) for the evidence expected before broadening the public API.

docs/GITHUB_DEPLOYMENT.md

@@ -0,0 +1,62 @@
+# Shopify GitHub deployment
+
+Liquid Loom intentionally keeps authored source separate from deployable Shopify output. Shopify's GitHub theme integration, however, expects the connected branch to contain Shopify's canonical theme directories.
+
+For repositories that use `src`, tests, and build tooling, connect Shopify to a **compiled deployment branch** or a separate deployment repository rather than to the authored branch.
+
+## Recommended topology
+
+```text
+main
+├── src/
+├── tests/
+├── liquid-loom.config.ts
+└── package.json
+      |
+      | CI: install -> validate -> build
+      v
+shopify-production
+├── assets/
+├── blocks/
+├── config/
+├── layout/
+├── locales/
+├── sections/
+├── snippets/
+└── templates/
+      |
+      v
+Shopify GitHub integration
+```
+
+The deployment branch is generated output. `main` remains the source of truth.
+
+## Safe CI policy
+
+Use a workflow triggered only by authored branches. Never trigger the build from `shopify-production` itself; that prevents a Shopify-originated commit on the connected branch from creating a deployment loop.
+
+When publishing:
+
+1. fetch the current `shopify-production` head;
+2. create a worktree from that head so the new deployment is a fast-forward commit;
+3. replace only the canonical Shopify theme directories with `dist/theme`;
+4. commit only when the compiled output changed;
+5. push without `--force`.
+
+A concurrent Shopify write will make the push fail rather than silently overwrite history. Re-run only after reviewing the branch state.
+
+See [`docs/examples/shopify-deploy.yml`](examples/shopify-deploy.yml) for an opt-in workflow recipe.
+
+## Theme Editor writes
+
+A compiled branch can't automatically translate Theme Editor changes back into organized source. Choose one of these policies explicitly:
+
+- **Source-authoritative:** Theme Editor changes on the deployment branch are temporary and the next successful source deployment may replace them. Keep history so drift can be reviewed first.
+- **Reconciliation workflow:** review Shopify-originated commits and manually port intentional changes into authored source before the next deployment.
+- **Separate deployment repository:** use this when you want stronger operational separation between authored source and generated theme output.
+
+Do not pretend two-way synchronization is lossless when a build step changes source shape.
+
+## Development stores
+
+For protected integration CI, Shopify CLI 4.8+ can create a disposable dev store, preview the built theme, run browser smoke tests, and remove the store afterwards. Public CI should continue to run without Shopify credentials.

docs/RECIPES.md

@@ -8,21 +8,53 @@ Place a file anywhere under `src/public/`. Its basename becomes the Shopify asse
 src/public/icons/cart.svg → dist/theme/assets/cart.svg
 ```
 
-Basenames must be unique across the entire public tree and cannot be `theme.js` or `style.css` unless generated-output configuration changes with matching Vite output.
+Basenames must be unique across the entire public tree. When Vite is enabled, static assets also cannot collide with any configured generated output.
 
-## Add a section or snippet
+## Add component CSS or JavaScript
 
-Organize by feature; Shopify’s destination remains flat:
+Fresh Liquid Loom projects prefer Shopify-native component assets:
+
+```liquid
+{% stylesheet %}
+	.product-card {
+		display: grid;
+	}
+{% endstylesheet %}
+
+{% javascript %}
+	customElements.define('product-card', class extends HTMLElement {});
+{% endjavascript %}
+```
+
+Keep truly global styles in a static file such as `src/public/theme.css`. Liquid doesn't render inside `{% stylesheet %}` or `{% javascript %}` tags, so pass dynamic values through markup, data attributes, or CSS custom properties.
+
+## Add a section, block, or snippet
+
+Organize by feature; Shopify's destination remains flat:
 
 ```text
 src/theme/sections/editorial/story.liquid → dist/theme/sections/story.liquid
+src/theme/blocks/product/title.liquid → dist/theme/blocks/title.liquid
 ```
 
 Run `pnpm build` immediately after adding the file. Portable collisions fail before the output changes.
 
-## Add another Vite entrypoint
+## Opt into Vite or Tailwind
+
+The fresh starter uses Shopify-native assets by default, but the framework still supports Vite and Tailwind. Add a Vite config and enable it explicitly:
+
+```ts
+export default defineConfig({
+	viteConfig: "vite.config.js",
+	reservedOutputs: ["assets/theme.js", "assets/style.css"]
+});
+```
+
+Install the asset tooling your project needs and configure stable output names. Generated outputs participate in the same ownership/collision plan as authored Shopify assets.
+
+## Deploy compiled output through Shopify GitHub integration
 
-Extend `rollupOptions.input` and give its output a stable name in `vite.config.js`. Add that output to `reservedOutputs` in `liquid-loom.config.ts` so a public asset cannot overwrite it.
+If your source repository contains `src`, tests, and build tooling, connect Shopify to a generated branch or separate deployment repository that contains only canonical Shopify theme directories. See [GitHub deployment](GITHUB_DEPLOYMENT.md).
 
 ## Scan for organization-specific terms