@augeo/smelt 1.2.2

package/docs/build-spec.md

@@ -0,0 +1,466 @@
+---
+status: draft
+---
+
+# Smelt Build Pipeline
+
+Spec for the source-to-theme compiler that turns the `src/` authoring tree into
+the flat, namespaced files Shopify expects.
+
+The build is the only thing this document describes. Theme-wide concerns
+(initial scaffolding choices, deployment workflow, store configuration) live
+elsewhere or are out of scope.
+
+## Goal
+
+Let theme authors work in colocated components (Liquid + TS + CSS + tests in one
+directory) and have a build step emit the flat, namespaced output Shopify
+expects. The build is **additive**: hand-written files in `sections/`,
+`snippets/`, etc. are never touched — the compiler only writes files prefixed
+`built--` (or `_built--` for private theme blocks).
+
+## Inputs and Outputs
+
+The build runs in a **consumer theme's** repo. It reads from an ordered list of
+**layers** — directories that each contain a
+`src/{sections,blocks,components, utilities}/` tree — and writes the merged
+output into Shopify's flat directories at the consumer's repo root.
+
+In this repository the consumer is `example/`, so paths shown below as `src/…`
+and `sections/…` are physically at `example/src/…` and `example/sections/…`. The
+pipeline itself is identical either way.
+
+```
+<layer>/src/                   # one such tree per layer
+├── sections/                  # → sections/built--*.liquid
+├── blocks/                    # → blocks/built--*.liquid
+├── components/                # → snippets/built--*.liquid
+└── utilities/                 # no Liquid output; bundled into importers
+
+sections/                      # outputs (mixed with hand-written) — at the
+snippets/                      # consumer's repo root, written by the build
+blocks/
+```
+
+The default layer list is `[<consumer>, "@augeo/smelt"]` — the consumer's own
+tree first, then Smelt's baseline. See [Layer Resolution](#layer-resolution)
+below for how files merge across layers.
+
+Directories the build does **not** read or write:
+
+- `config/`, `layout/`, `templates/`, `locales/`, `assets/` — entirely
+  hand-written in v1.
+- Any file in an output directory that lacks the `built--` prefix.
+
+## Component Model
+
+A **component** is a directory with at minimum a `.liquid` file matching the
+directory name. Optional sibling files extend it:
+
+```
+src/components/button/
+├── button.liquid              # required — Liquid template
+├── button.ts                  # optional — inlined as {% javascript %}
+├── button.css                 # optional — inlined as {% stylesheet %}
+├── button.test.ts             # optional — vitest test (via @augeo/assay)
+└── props.ts                   # optional — typed schema (future)
+```
+
+Component types differ only by their source directory and output target:
+
+| Source dir        | Output dir  | Notes                                    |
+| ----------------- | ----------- | ---------------------------------------- |
+| `src/sections/`   | `sections/` | Renderable as Shopify sections           |
+| `src/blocks/`     | `blocks/`   | Theme blocks                             |
+| `src/components/` | `snippets/` | Reusable across sections/blocks/snippets |
+| `src/utilities/`  | (none)      | TS/CSS-only; bundled into importers      |
+
+Nested components are supported and namespaced into the output name (see
+[Output Naming](#output-naming)).
+
+## Layer Resolution
+
+The build accepts an ordered list of **layers**; each layer is a directory
+containing its own `src/{sections,blocks,components,utilities}/` tree. The
+default layers, in order, are:
+
+1. **The consumer's layer** — `process.cwd()`. The consumer's own `src/`.
+2. **`@augeo/smelt`** — the published package's `src/`, the baseline.
+
+For every component (keyed by `type` + path segments), each of the five file
+slots — `liquid`, `ts`, `css`, `test.ts`, `schema.ts` — is resolved
+**independently**: the first layer that has the file wins, the later layers are
+shadowed.
+
+A consumer who drops just `src/components/button/button.css` into their tree
+inherits the baseline's `button.liquid` and `button.ts` and overrides only the
+styles. The same shadowing rule applies to all five slots.
+
+A component is included in the build if **any** layer has its `liquid` slot
+filled. A consumer-only `.css` for a component that doesn't exist in any layer
+is dead code (no liquid anchor) and is silently ignored.
+
+## Authoring Conventions
+
+### Liquid imports — `@/` and `./` aliases
+
+Inside `.liquid` source files, reference other source components via one of two
+aliases (modeled on Next.js / TypeScript path conventions):
+
+- **`@/...`** — rooted at `src/`. Use for anything outside the current
+  component's subtree.
+- **`./...`** — relative to the current source file's directory. Use for
+  references into the current component's nested children. **Descending only —
+  `../` is not supported.** If you need to reach a sibling-of-parent, use `@/`;
+  if you find yourself wanting `../` repeatedly, the nested component should
+  probably be hoisted to a shared location.
+
+<!-- prettier-ignore -->
+```liquid
+{# inside src/sections/hero/hero.liquid: #}
+
+{% render './components/foo' %}        {# nested child of hero       #}
+{% render '@/components/button' %}     {# top-level shared component #}
+```
+
+Both rewrite to namespaced output names:
+
+```liquid
+{% render 'built--sections--hero--components--foo' %}
+{% render 'built--components--button' %}
+```
+
+Hand-written snippets remain referenceable by their bare name as usual:
+
+```liquid
+{% render 'icon-cart' %} {# unchanged — resolves to snippets/icon-cart.liquid #}
+```
+
+### TS / CSS — colocated and implicit
+
+If `<name>.ts` exists alongside `<name>.liquid`, it is the component's
+JavaScript entry point. The bundled output is inlined into a `{% javascript %}`
+tag at the end of the built `.liquid` file. Same for `<name>.css` →
+`{% stylesheet %}`.
+
+Each component owns its own `{% javascript %}` / `{% stylesheet %}` block.
+Shopify supports these tags in sections, blocks, and snippets (one per file) and
+handles per-file asset deduplication at runtime.
+
+### Cross-component imports — utilities only
+
+A component's TS may import from `src/utilities/` and those will be bundled into
+the component's IIFE. Importing another _component's_ TS
+(`src/components/foo/foo.ts`) is **not supported** — foo is rendered as its own
+snippet with its own script tag; the DOM already gets foo's behavior when
+`{% render 'foo' %}` runs.
+
+### Section / block schemas — `<name>.schema.ts`
+
+Sections and theme blocks can author their schema as a TypeScript file alongside
+the component:
+
+```ts
+// example/src/sections/hero/hero.schema.ts
+import { defineSchemaSection } from "@augeo/smelt/schema";
+
+export const schema = defineSchemaSection({
+	name: "Hero",
+	settings: [
+		{ type: "text", id: "heading", label: "Heading", default: "Welcome" },
+	],
+	presets: [{ name: "Hero" }],
+});
+```
+
+Conventions:
+
+- **Filename:** `<name>.schema.ts`.
+- **Required export:** a named `schema` constant. Other named exports are fine
+  and ignored.
+- **Helper per component kind:** `defineSchemaSection` for `src/sections/*`,
+  `defineSchemaBlock` for `src/blocks/*`. Each is an identity function whose
+  generic preserves literal types so the schema author gets autocomplete for
+  `type` / `id` / setting shapes.
+- **Types are codegen'd** from Shopify's authoritative JSON Schemas in
+  `vendor/theme-liquid-docs`. Update via
+  `npm run docs:update && npm run schema:codegen`.
+
+At build time the engine executes the schema file (esbuild bundle → `import()`),
+takes the `schema` export, `JSON.stringify`s it, and injects a
+`{% schema %} … {% endschema %}` block into the built `.liquid`.
+
+**Schemas may only live in `<name>.schema.ts` files.** Inline `{% schema %}`
+blocks in `.liquid` source files are a build error — the engine refuses to emit
+and points at the expected sibling filename. This keeps a single source of truth
+and avoids surprises when shadowing across layers.
+
+Shared settings (padding, alignment, etc.) compose through plain TS imports:
+
+```ts
+import { paddingSettings } from "@/utilities/schemas/padding";
+
+export const schema = defineSchemaSection({
+	name: "Hero",
+	settings: [
+		{ type: "text", id: "heading", label: "Heading" },
+		...paddingSettings,
+	],
+});
+```
+
+### Private blocks — nested `blocks/`
+
+Shopify treats theme block files prefixed with `_` as **private**: hidden from
+the merchant's block picker, renderable only via the parent's
+`{% content_for "blocks" %}`. Smelt expresses this structurally — a `blocks/`
+directory nested under a section or block emits its children with the `_` prefix
+on the built filename, mirroring the parent/child relationship that private
+blocks already imply in Shopify.
+
+```
+src/sections/hero/
+├── hero.liquid
+├── hero.schema.ts
+└── blocks/
+    └── headline/
+        ├── headline.liquid
+        └── headline.schema.ts
+```
+
+Compiles to:
+
+```
+sections/built--sections--hero.liquid
+blocks/_built--sections--hero--blocks--headline.liquid
+```
+
+Top-level `src/blocks/*` files remain public (no `_` prefix). The trigger is
+"this block was reached through a nested `blocks/` type marker" — i.e.
+`component.type === "blocks"` AND a `"blocks"` segment appears at any position
+after the root (`component.segments.slice(1).includes("blocks")`). That covers
+both a section/component owning private blocks (`sections/hero/blocks/headline`)
+and a public block owning its own private blocks (`blocks/promo/blocks/item`).
+The rule applies recursively: a private block can have its own `blocks/` subdir,
+producing privately-scoped grandchildren that walk the same way.
+
+The parent section or block's schema auto-merges these private children into its
+`blocks: [...]` array — discovered children sorted by directory name and
+prepended, any blocks the author explicitly lists (e.g. globally-shared block
+types) appended after. No helper call required.
+
+## Build Pipeline
+
+The engine lives in `lib/build/build.ts` and is invoked by `lib/cli.ts` (a citty
+CLI bundled by tsdown to `dist/cli.mjs` — the published `smelt` bin). From a
+consumer's repo the commands are `smelt build` (one-shot compile) and
+`smelt dev` (build then watch — see below). From this repo, `npm run build`
+rebuilds the bin and `npm run test:all` runs the full integration chain against
+`example/`. The engine itself:
+
+1. **Resolve layers** — walk each layer's `src/` tree and produce a merged
+   `Map<segments, ResolvedComponent>` where each component's `liquid` / `ts` /
+   `css` / `test` / `schema` slots are independently first-wins (see
+   [Layer Resolution](#layer-resolution)).
+2. **Clean previous output** — sweep any file matching `/^_?built--/` from
+   `sections/`, `snippets/`, and `blocks/`. Output is regenerated from scratch
+   on every build, so removed source components disappear cleanly. Hand-written
+   files without the prefix are untouched.
+3. **For each component** (anything with a `.liquid`):
+   - Prepend a `{%- comment -%}` banner naming the source file, for tracing.
+   - Bundle `<name>.ts` (esbuild, IIFE, utilities inlined) → string.
+   - Read `<name>.css` as-is (no transform today — see TODO).
+   - Execute `<name>.schema.ts` — esbuild → `data:` URL → dynamic `import()`,
+     capturing the named `schema` export. esbuild auto-discovers the consumer's
+     `tsconfig.json` so `@/...` (and any custom path aliases) resolve the way
+     `tsc` sees them.
+   - Auto-merge any immediate private `blocks/` children into the loaded
+     schema's `blocks: [...]` array (see
+     [Private blocks](#private-blocks--nested-blocks)).
+   - Transform `<name>.liquid`:
+     - **Error** if the source `.liquid` contains an inline `{% schema %}` block
+       — schemas must live in `<name>.schema.ts`.
+     - Rewrite `{% render '@/...' %}` and `{% render './...' %}` to namespaced
+       output names (private blocks get the `_built--` form).
+     - Append `{% schema %}…{% endschema %}` block if schema present.
+     - Append `{% stylesheet %}…{% endstylesheet %}` block if CSS present.
+     - Append `{% javascript %}…{% endjavascript %}` block if TS present.
+   - Emit to the matching output directory under the namespaced name.
+
+The build never touches files in output directories that lack the `built--` /
+`_built--` prefix.
+
+**Watch mode (`smelt dev`)** re-runs the whole pipeline on any source file
+change, debounced ~100ms. Build failures log and keep the watcher alive. Today
+that's a full rebuild every time — see TODO for the dependency-graph-aware
+version.
+
+## Output Naming
+
+Source path → output name:
+
+```
+src/components/button/button.liquid
+  → snippets/built--components--button.liquid
+
+src/sections/hero/hero.liquid
+  → sections/built--sections--hero.liquid
+
+src/sections/hero/components/foo/foo.liquid
+  → snippets/built--sections--hero--components--foo.liquid
+
+src/blocks/promo/promo.liquid
+  → blocks/built--blocks--promo.liquid
+```
+
+Rules:
+
+- Prefix `built--` marks compiler output: anything matching `/^_?built--/` in
+  `sections/`, `snippets/`, or `blocks/` is the build's territory — cleaned and
+  rewritten every build. Hand-written files in those directories are untouched.
+- Path segments under `src/` are joined with `--`.
+- Final segment (directory name) appears once; the matching `.liquid` filename
+  is not duplicated.
+- Sections, blocks, and components-of-components all flatten into the same set
+  of Shopify-flat directories.
+- Private blocks (reached through a nested `blocks/` marker) get an additional
+  `_` prefix on the filename — see
+  [Private blocks](#private-blocks--nested-blocks).
+
+## Worked Example
+
+A fuller picture showing source files, nested components, and the compiled
+output sitting alongside hand-written files.
+
+### Source (`src/`)
+
+```
+src/
+├── sections/
+│   └── hero/
+│       ├── hero.liquid
+│       ├── hero.css
+│       ├── hero.ts
+│       ├── hero.test.ts
+│       ├── components/
+│       │   └── foo/
+│       │       ├── foo.liquid
+│       │       ├── foo.css
+│       │       ├── foo.ts
+│       │       └── foo.test.ts
+│       └── blocks/
+│           └── headline/        # private — see Private blocks section
+│               ├── headline.liquid
+│               └── headline.schema.ts
+├── blocks/
+├── components/
+│   └── button/
+│       ├── props.ts             # typed prop schema (future — see Open Questions)
+│       ├── button.liquid
+│       ├── button.css
+│       ├── button.ts
+│       └── button.test.ts
+└── utilities/
+```
+
+### Compiled output (Shopify-flat dirs)
+
+```
+sections/
+├── built--sections--hero.liquid           # ← src/sections/hero/
+└── old_legacy_section.liquid              # hand-written, preserved
+
+snippets/
+├── built--sections--hero--components--foo.liquid   # nested under hero
+├── built--components--button.liquid                # top-level component
+└── icon-cart.liquid                                # hand-written, preserved
+
+blocks/
+└── _built--sections--hero--blocks--headline.liquid   # private to hero
+
+assets/
+└── (hand-written static files; build does not write here in v1)
+```
+
+Notes:
+
+- Co-located `hero.ts` / `hero.css` are inlined into
+  `built--sections--hero.liquid` as `{% javascript %}` / `{% stylesheet %}`
+  blocks — no separate files in `assets/`.
+- `built--` is the only namespace the compiler writes. Files without the prefix
+  (`old_legacy_section.liquid`, `icon-cart.liquid`) are treated as hand-written
+  and survive rebuilds untouched.
+- The nested `hero/components/foo/` directory illustrates that components scoped
+  to a single section live inside it and flatten into a path-encoded snippet
+  name on output.
+
+## Testing
+
+Tests use [`@augeo/assay`](https://www.npmjs.com/package/@augeo/assay) — Vitest
+browser mode + liquidjs + Playwright.
+
+- `<name>.test.ts` lives beside `<name>.liquid`.
+- Tests run against the **built** theme directories (Liquid in `sections/`,
+  `snippets/`, `blocks/`), not against `src/` directly, since assay / liquidjs
+  cannot resolve the `@/...` alias.
+- `npm test` runs `build` first, then `vitest`.
+
+Vitest config uses the assay preset:
+
+```ts
+import { assayPreset } from "@augeo/assay/preset";
+
+export default assayPreset({
+	liquidPaths: ["./sections", "./snippets", "./blocks"],
+	assetsPath: "./assets",
+});
+```
+
+## Decisions Made (and Why)
+
+- **`{% javascript %}` / `{% stylesheet %}` inlining over standalone
+  `assets/section-*.js` files.** Compiled output is inlined into the
+  per-component tag; Shopify owns the asset generation and runtime dedup. Less
+  file proliferation in `assets/`. An earlier objection — that these tags were
+  section-only — was based on outdated docs; current Shopify supports them in
+  sections, blocks, and snippets (one tag of each kind per file).
+- **No cross-component TS imports.** Each component is its own bundle. Sharing
+  happens through `src/utilities/`, which has no Liquid output and is purely a
+  code-sharing layer.
+- **Tests run against built output.** Avoids reimplementing the `@/...` resolver
+  inside the test runner. `npm test` builds first, then runs vitest.
+- **Build is additive, not destructive.** The compiler only writes files
+  prefixed `built--`. Hand-written files in output directories are preserved
+  across rebuilds, allowing gradual migration into `src/`.
+
+## Open Questions
+
+- `src/components/<x>/props.ts` — typed prop schema for non-section/block
+  components (snippets), declaring the variables a `{% render %}` call must
+  pass. Distinct from `<name>.schema.ts`, which describes Shopify's
+  merchant-facing settings for sections and theme blocks. Possibly with runtime
+  validation injected into the built snippet for dev mode. Defer.
+- LSP / editor support for the `@/...` alias (go-to-definition). Defer.
+
+## TODO
+
+Deferred work — things we've decided we want to address eventually but aren't
+scoped or designed yet.
+
+- **Utility deduplication across component bundles.** Currently each component's
+  IIFE inlines its imported utilities, so a utility used by N components ships N
+  times. Acceptable for a small theme; revisit when measured page weight
+  justifies the design work. Candidate approaches include a single shared
+  `assets/built--utilities.js` bundle exposed on a global, ES modules via an
+  importmap, or per-utility snippet guards.
+
+- **CSS processing.** Today `<name>.css` is inlined as-is. A real pipeline would
+  run something like [lightningcss](https://lightningcss.dev/) or
+  [postcss](https://postcss.org/) for autoprefixing, nesting, custom-property
+  fallbacks, and source-of-truth normalization across components. Defer until
+  someone authoring components asks for a feature that needs it.
+
+- **Dependency-graph-aware watch.** `smelt dev` currently re-runs the whole
+  pipeline on any source change. A smarter loop would track which components
+  import which utilities and rebuild only the affected set — important once
+  builds get slow enough that full-rebuild latency hurts the authoring loop.