@augeo/smelt 1.2.3 → 1.3.0

package/.github/workflows/verify.yml

@@ -32,6 +32,29 @@ jobs:
         working-directory: example
         run: npm ci
 
+      # The root build is a prerequisite: it produces the `smelt` bin
+      # (dist/cli.mjs, gitignored) that the example's `smelt build` needs.
+      - name: Build smelt bin (prerequisite for the example build)
+        run: npm run build
+
+      # Build first so the job fails fast when the committed `built--*` output is
+      # stale, before spending time on lint, typecheck, and the full test run.
+      # Only the example build writes tracked files, so it's what the drift
+      # check below actually guards.
+      - name: Build example (regenerates tracked built--* output)
+        working-directory: example
+        run: npm run build
+
+      - name: Check built files match source
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "::error::Build produced uncommitted changes. Did you forget to commit a rebuild?"
+            git status --porcelain
+            echo "---"
+            git diff
+            exit 1
+          fi
+
       - name: Restore prettier cache
         uses: actions/cache@v4
         with:
@@ -52,13 +75,3 @@ jobs:
 
       - name: Run tests (integration via example)
         run: npm run test:all
-
-      - name: Check built files match source
-        run: |
-          if [ -n "$(git status --porcelain)" ]; then
-            echo "::error::Build produced uncommitted changes — did you forget to commit a rebuild?"
-            git status --porcelain
-            echo "---"
-            git diff
-            exit 1
-          fi

package/AGENTS.md

@@ -25,9 +25,7 @@ The repo currently has two halves:
   integration test bed (same pattern as
   [`@augeo/assay`](https://github.com/seanhealy/assay)'s `example/`).
 
-See [`docs/build-spec.md`](./docs/build-spec.md) for the build pipeline spec and
-[`docs/library-conversion-plan.md`](./docs/library-conversion-plan.md) for the
-phased plan to publish it as `@augeo/smelt`.
+See [`docs/build-spec.md`](./docs/build-spec.md) for the build pipeline spec.
 
 ## Tech Stack
 
@@ -203,6 +201,12 @@ vitest + `example/`'s typecheck/build/vitest/theme-check). CI runs both.
 - **Prefer the Grep tool over CLI `grep`** when searching file contents — it
   handles permissions cleanly. Use CLI `grep` only when piping into another
   shell command that the Grep tool can't express.
+- **Use `npm run verify`, never ad-hoc `npx`.** `verify` auto-fixes lint
+  (Biome + Prettier across the whole tree) and type-checks in one pass — reach
+  for it as the default even when you just want a formatting/lint check. Don't
+  reach for `npx prettier`, `npx biome`, `npx tsc`, or the bare `lint`
+  sub-script directly — the scripts encode the right scope, config, and the
+  Biome/Prettier boundary. See [Formatting](#formatting).
 
 ## Working Style
 

package/README.md

@@ -3,8 +3,8 @@
 [![Verify](https://github.com/AugeoCorp/smelt/actions/workflows/verify.yml/badge.svg)](https://github.com/AugeoCorp/smelt/actions/workflows/verify.yml)
 
 Build Shopify themes from colocated components. Author your `button/` directory
-once — `button.liquid`, `button.ts`, `button.css`, `button.test.ts`,
-`button.schema.ts` — and Smelt compiles it into the flat, namespaced files
+once (`button.liquid`, `button.ts`, `button.css`, `button.test.ts`,
+`button.schema.ts`), and Smelt compiles it into the flat, namespaced files
 Shopify expects.
 
 ## Why
@@ -19,7 +19,7 @@ Shopify expects.
   autocomplete derived from Shopify's authoritative JSON Schemas. The build
   executes the file and injects the result.
 - **Private blocks for free.** Nest a `blocks/` directory under a section or
-  block and its children become private theme blocks — emitted with Shopify's
+  block, and its children become private theme blocks, emitted with Shopify's
   `_` prefix and auto-merged into the parent's schema. No manual filename
   mangling.
 - **Additive build.** Only files prefixed `built--` (or `_built--` for private
@@ -35,6 +35,7 @@ Shopify expects.
 - [Authoring](#authoring)
 - [Schemas](#schemas)
 - [Private blocks](#private-blocks)
+- [Block faces](#block-faces)
 - [Layering](#layering)
 - [Build](#build)
 - [Learn More](#learn-more)
@@ -89,8 +90,8 @@ smelt build
 ```
 
 Outputs `sections/built--sections--hero.liquid`,
-`snippets/built--components--card.liquid`, etc. — flat and namespaced, the way
-Shopify wants.
+`snippets/built--components--card.liquid`, etc. They're flat and namespaced, the
+way Shopify wants.
 
 See the [📄 `example/`](./example) directory for a working consumer theme.
 
@@ -110,7 +111,7 @@ Each component is a directory under `src/<type>/<name>/` where `<type>` is
 
 | File               | Role                                         |
 | ------------------ | -------------------------------------------- |
-| `<name>.liquid`    | Markup (required — anchors the component)    |
+| `<name>.liquid`    | Markup (required; anchors the component)     |
 | `<name>.ts`        | Bundled and injected into `{% javascript %}` |
 | `<name>.css`       | Injected into `{% stylesheet %}`             |
 | `<name>.schema.ts` | Typed schema (sections + blocks only)        |
@@ -154,12 +155,12 @@ Types are codegen'd from Shopify's authoritative schemas in
 [`theme-liquid-docs`](https://github.com/Shopify/theme-liquid-docs). Update via
 `npm run docs:update`.
 
-Inline `{% schema %}` blocks in `.liquid` files are a build error — single
+Inline `{% schema %}` blocks in `.liquid` files are a build error: a single
 source of truth.
 
 ## Private blocks
 
-Shopify treats theme block files prefixed with `_` as **private** — hidden from
+Shopify treats theme block files prefixed with `_` as **private**: hidden from
 the merchant's block picker, renderable only via a parent's
 `{% content_for "blocks" %}`. Smelt expresses this structurally: a `blocks/`
 directory nested under a section or block emits its children with the `_` prefix
@@ -182,19 +183,67 @@ sections/built--sections--hero.liquid
 blocks/_built--sections--hero--blocks--feature.liquid
 ```
 
-The parent's schema auto-merges discovered children into its `blocks: []` array
-— sorted by directory name and prepended; any explicit entries you list (e.g.
+The parent's schema auto-merges discovered children into its `blocks: []` array,
+sorted by directory name and prepended; any explicit entries you list (e.g.
 globally-shared block types) appended after. Nesting is recursive: a private
 block can have its own `blocks/` subdir.
 
 Top-level `src/blocks/*` files remain public (no `_` prefix).
 
+## Block faces
+
+A `src/components/*` component compiles to a snippet — reusable through
+`{% render %}`, but invisible to the theme editor. A **block face** also exposes
+that same component as a theme block a merchant can drop onto a page, without
+duplicating it. Declare one with a singular `block/` directory inside the
+component:
+
+```
+src/components/card/
+├── card.liquid          # the reusable snippet
+├── card.css
+└── block/
+    └── card.schema.ts   # the block face's schema
+```
+
+Compiles to **both**:
+
+```
+snippets/built--components--card.liquid   # the snippet, unchanged
+blocks/built--components--card.liquid      # the block face
+```
+
+With just a schema (no `block/card.liquid`), the face is **mechanical**: the
+build synthesizes the wrapper for you — rendering the component, mapping each
+setting to a render arg of the same name, and passing `shopify_attributes`
+through. So name your component's props to match the setting `id`s.
+
+```liquid
+{% # blocks/built--components--card.liquid (generated) %}
+{% render 'built--components--card',
+	title: block.settings.title,
+	body: block.settings.body,
+	shopify_attributes: block.shopify_attributes
+%}
+{% schema %}…{% endschema %}
+```
+
+When the wrapper isn't mechanical — derived props, conditional logic, or passing
+`children: block.blocks` — add a `block/card.liquid` and the build uses it as
+the body verbatim (renders rewritten, schema injected). The face is then just a
+normal block component living in `block/`, so it can carry its own
+`block/card.ts` / `block/card.css` too.
+
+Faces are **components-only**: sections and blocks don't get them. A block face
+can own private child blocks by nesting a `blocks/` directory inside `block/` —
+see [`docs/build-spec.md`](./docs/build-spec.md) for that and the full rules.
+
 ## Layering
 
 Smelt walks an ordered list of layers and merges them per-file. The default is:
 
-1. **Consumer** — your theme's `src/` (`process.cwd()`).
-2. **`@augeo/smelt`** — the package's baseline `src/`.
+1. **Consumer:** your theme's `src/` (`process.cwd()`).
+2. **`@augeo/smelt`:** the package's baseline `src/`.
 
 For each component slot (`liquid`, `ts`, `css`, `schema`), the first layer that
 has the file wins. Drop just a `button.css` in your consumer to override styles;
@@ -207,7 +256,7 @@ smelt build
 ```
 
 Run from the theme root. Outputs go to `sections/built--*.liquid`,
-`blocks/built--*.liquid`, and `snippets/built--*.liquid` — prefixed so they
+`blocks/built--*.liquid`, and `snippets/built--*.liquid`, prefixed so they
 coexist with hand-written files in the same directories.
 
 ### Watch mode
@@ -219,7 +268,7 @@ smelt dev
 Runs an initial build, then watches each layer's `src/` and rebuilds on file
 changes (add, edit, delete). Build failures log and keep the watcher alive. Pair
 with `shopify theme dev` (in another terminal or via
-[`concurrently`](https://www.npmjs.com/package/concurrently)) — `smelt dev`
+[`concurrently`](https://www.npmjs.com/package/concurrently)): `smelt dev`
 writes the built files; `shopify theme dev` uploads them.
 
 ### Committing the output
@@ -228,7 +277,7 @@ Shopify imports themes from git, so `built--*` files (and `_built--*` for
 private blocks) need to be **committed** alongside source. Two configs keep the
 noise down:
 
-`.gitattributes` — marks output as generated so GitHub collapses it in PR diffs
+`.gitattributes` marks output as generated so GitHub collapses it in PR diffs
 and excludes it from language stats:
 
 ```
@@ -238,7 +287,7 @@ blocks/built--*.liquid linguist-generated=true
 blocks/_built--*.liquid linguist-generated=true
 ```
 
-`.prettierignore` — skips the output so Prettier doesn't reformat it between
+`.prettierignore` skips the output so Prettier doesn't reformat it between
 builds:
 
 ```
@@ -248,19 +297,70 @@ blocks/built--*.liquid
 blocks/_built--*.liquid
 ```
 
+### CI: verify the build is committed
+
+Because the `built--*` files are committed, they can drift from source: someone
+edits a component but forgets to rebuild, or commits a stale build. Catch it in
+CI by rebuilding and failing if the working tree is dirty: a clean tree means
+the committed output already matches source.
+
+`.github/workflows/verify.yml`:
+
+```yaml
+name: Verify
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version-file: "package.json"
+          cache: "npm"
+
+      - run: npm ci
+
+      - name: Build
+        run: npm run build # → smelt build
+
+      - name: Check built files match source
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "::error::Build produced uncommitted changes. Did you forget to commit a rebuild?"
+            git status --porcelain
+            git diff
+            exit 1
+          fi
+```
+
+The build is [additive](#build) and deterministic: it only writes `built--*`
+files, so a rebuild on a current tree produces no diff. Any change to
+`git status` means the commit is missing a rebuild.
+
+If you run other checks (tests, `shopify theme check`), put the build step
+**first** so the job fails fast when the committed output is stale. There's no
+point linting and testing a tree you already know is out of date. See this
+repo's own [`verify.yml`](./.github/workflows/verify.yml) for the full pattern,
+including git submodules and a Playwright browser for the test suite.
+
 ## Learn More
 
-- [📄 Build Spec](./docs/build-spec.md) — pipeline, alias rules, conventions
-- [📄 Testing Conventions](./docs/TESTING.md) — how to write tests against the
+- [📄 Build Spec](./docs/build-spec.md): pipeline, alias rules, conventions
+- [📄 Testing Conventions](./docs/TESTING.md): how to write tests against the
   built output
-- [📄 Library Conversion Plan](./docs/library-conversion-plan.md) — phased plan
-  for publishing
-- [`@augeo/assay`](https://www.npmjs.com/package/@augeo/assay) — the test runner
+- [`@augeo/assay`](https://www.npmjs.com/package/@augeo/assay): the test runner
   Smelt uses
 
 ## Future Plans
 
-- **`smelt.config.ts`** — consumer-defined layer list, enabling N-layer
+- **`smelt.config.ts`:** consumer-defined layer list, enabling N-layer
   composition (e.g., a community component pack between consumer and baseline).
-- **More baseline components** — currently just `button` demo. Expanding to a
+- **More baseline components.** Currently just `button` demo. Expanding to a
   real default set.

package/dist/cli.mjs

@@ -11,30 +11,30 @@ const TYPE_NAMES = [
 	"blocks",
 	"components"
 ];
+const FACE_MARKER = "block";
 async function resolveLayers(layers) {
 	const perLayerComponents = await Promise.all(layers.map(walkLayer));
 	const allKeys = /* @__PURE__ */ new Map();
-	perLayerComponents.flat().forEach(({ type, segments }) => {
-		const key = `${type}:${segments.join("/")}`;
-		if (!allKeys.has(key)) allKeys.set(key, {
-			type,
-			segments
-		});
+	perLayerComponents.flat().forEach((descriptor) => {
+		const key = `${descriptor.type}:${descriptor.segments.join("/")}`;
+		if (!allKeys.has(key)) allKeys.set(key, descriptor);
 	});
-	return (await Promise.all(Array.from(allKeys.values()).map(async ({ type, segments }) => {
+	return (await Promise.all(Array.from(allKeys.values()).map(async (descriptor) => {
+		const anchor = descriptor.segments[descriptor.segments.length - 1];
 		const [liquid, ts, css, test, schema] = await Promise.all([
-			firstExisting(layers, segments, ".liquid"),
-			firstExisting(layers, segments, ".ts"),
-			firstExisting(layers, segments, ".css"),
-			firstExisting(layers, segments, ".test.ts"),
-			firstExisting(layers, segments, ".schema.ts")
+			firstExisting(layers, descriptor.dir, anchor, ".liquid"),
+			firstExisting(layers, descriptor.dir, anchor, ".ts"),
+			firstExisting(layers, descriptor.dir, anchor, ".css"),
+			firstExisting(layers, descriptor.dir, anchor, ".test.ts"),
+			firstExisting(layers, descriptor.dir, anchor, ".schema.ts")
 		]);
-		if (!liquid) return void 0;
+		if (!liquid && !(descriptor.face && schema)) return void 0;
 		const component = {
-			type,
-			segments,
-			liquid
+			type: descriptor.type,
+			segments: descriptor.segments
 		};
+		if (descriptor.face) component.face = true;
+		if (liquid) component.liquid = liquid;
 		if (ts) component.ts = ts;
 		if (css) component.css = css;
 		if (test) component.test = test;
@@ -48,26 +48,35 @@ async function walkLayer(layer) {
 	return (await Promise.all(TYPE_NAMES.map(async (type) => {
 		const typeDir = join(sourceRoot, type);
 		if (!await exists$1(typeDir)) return [];
-		return walkType(typeDir, type, [type]);
+		return walkType(typeDir, type, [type], [type]);
 	}))).flat();
 }
-async function walkType(directory, type, segments) {
+async function walkType(directory, type, segments, dir) {
 	const directories = (await readdir(directory, { withFileTypes: true })).filter((entry) => entry.isDirectory());
+	const inComponentContext = !TYPE_NAMES.includes(segments[segments.length - 1] ?? "");
 	return (await Promise.all(directories.map(async (entry) => {
 		const subdirectory = join(directory, entry.name);
-		if (TYPE_NAMES.includes(entry.name)) return walkType(subdirectory, entry.name, [...segments, entry.name]);
+		if (TYPE_NAMES.includes(entry.name)) return walkType(subdirectory, entry.name, [...segments, entry.name], [...dir, entry.name]);
+		if (entry.name === FACE_MARKER && inComponentContext && type === "components") return [{
+			type: "blocks",
+			segments: [...segments],
+			dir: [...dir, entry.name],
+			face: true
+		}, ...await walkType(subdirectory, type, [...segments], [...dir, entry.name])];
 		const componentSegments = [...segments, entry.name];
+		const componentDir = [...dir, entry.name];
 		const here = await exists$1(join(subdirectory, `${entry.name}.liquid`)) ? [{
 			type,
-			segments: componentSegments
+			segments: componentSegments,
+			dir: componentDir,
+			face: false
 		}] : [];
-		const deeper = await walkType(subdirectory, type, componentSegments);
+		const deeper = await walkType(subdirectory, type, componentSegments, componentDir);
 		return [...here, ...deeper];
 	}))).flat();
 }
-async function firstExisting(layers, segments, extension) {
-	const last = segments[segments.length - 1];
-	const relativePath = join("src", ...segments, `${last}${extension}`);
+async function firstExisting(layers, dir, anchor, extension) {
+	const relativePath = join("src", ...dir, `${anchor}${extension}`);
 	const winner = (await Promise.all(layers.map(async (layer) => ({
 		layer,
 		path: join(layer.path, relativePath),
@@ -100,7 +109,7 @@ async function build$2(context) {
 	if (!outputRoot) throw new Error("build() requires at least one layer.");
 	const components = await resolveLayers(context.layers);
 	await cleanBuiltOutputs(outputRoot);
-	const lookup = new Map(components.map((component) => [component.segments.join("/"), component]));
+	const lookup = new Map(components.filter((component) => !component.face).map((component) => [component.segments.join("/"), component]));
 	await Promise.all(components.map((component) => buildComponent(component, lookup, outputRoot)));
 	return components.length;
 }
@@ -113,12 +122,23 @@ async function cleanBuiltOutputs(outputRoot) {
 	}));
 }
 async function buildComponent(component, lookup, outputRoot) {
-	const source = await readFile(component.liquid.path, "utf-8");
-	assertNoInlineSchema(source, component);
-	const body = rewriteRenders(source, component, lookup);
-	const sections = [banner(component), body.trimEnd()];
-	if (component.schema) {
-		const merged = mergePrivateBlocks(await loadSchema(component.schema), component, lookup);
+	const schema = component.schema ? await loadSchema(component.schema) : void 0;
+	let body;
+	if (component.liquid) {
+		const source = await readFile(component.liquid.path, "utf-8");
+		assertNoInlineSchema(source, component);
+		body = rewriteRenders(source, component, lookup);
+	} else {
+		const snippetKey = component.segments.join("/");
+		if (!lookup.has(snippetKey)) {
+			const name = component.segments[component.segments.length - 1];
+			throw new Error(`Block face '${snippetKey}' has no underlying snippet to render — a mechanical face wraps its component. Add ${name}.liquid, or author a block/${name}.liquid override.`);
+		}
+		body = rewriteRenders(generateFaceBody(component, schema), component, lookup);
+	}
+	const sections = [banner(anchorSourceOf(component)), body.trimEnd()];
+	if (schema !== void 0) {
+		const merged = mergePrivateBlocks(schema, component, lookup);
 		sections.push(renderSchemaBlock(merged));
 	}
 	if (component.css) {
@@ -135,7 +155,7 @@ async function buildComponent(component, lookup, outputRoot) {
 function assertNoInlineSchema(source, component) {
 	if (!/\{%-?\s*schema\s*-?%\}/.test(source)) return;
 	const last = component.segments[component.segments.length - 1];
-	throw new Error(`Inline {% schema %} block in ${sourcePathForComponent(component)}. Schemas must live in a sibling ${last}.schema.ts file — import { defineSchemaSection } (or defineSchemaBlock) from "@augeo/smelt/schema".`);
+	throw new Error(`Inline {% schema %} block in ${sourcePathFor(anchorSourceOf(component))}. Schemas must live in a sibling ${last}.schema.ts file — import { defineSchemaSection } (or defineSchemaBlock) from "@augeo/smelt/schema".`);
 }
 async function loadSchema(schemaSource) {
 	const code = await bundle(schemaSource.path, {
@@ -199,15 +219,40 @@ function findPrivateChildren(component, lookup) {
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function banner(component) {
+function banner(source) {
 	return `{%- comment -%}
-	GENERATED FROM ${sourcePathForComponent(component)} — do not edit this file directly.
+	GENERATED FROM ${sourcePathFor(source)} — do not edit this file directly.
 	Edit the source and run \`npm run build\`.
 {%- endcomment -%}`;
 }
-function sourcePathForComponent(component) {
-	const relativePath = relative(component.liquid.layer.path, component.liquid.path);
-	return `${component.liquid.layer.name}/${relativePath}`;
+function sourcePathFor(source) {
+	const relativePath = relative(source.layer.path, source.path);
+	return `${source.layer.name}/${relativePath}`;
+}
+/**
+* The slot a built file traces back to: the hand-written liquid when present,
+* else the schema (a mechanical block face is anchored on its schema alone).
+*/
+function anchorSourceOf(component) {
+	const anchor = component.liquid ?? component.schema;
+	if (!anchor) throw new Error(`Component '${component.segments.join("/")}' has neither a liquid nor a schema file.`);
+	return anchor;
+}
+/**
+* Synthesize a block face's wrapper body: render the underlying component,
+* mapping each schema setting to a render arg of the same name (`id == arg`)
+* and passing `shopify_attributes` through. The `@/...` render is rewritten to
+* the built name by the caller. For non-mechanical wrappers (derived props,
+* `block.blocks`, …) author a `block/<name>.liquid` override instead.
+*/
+function generateFaceBody(component, schema) {
+	const settingArgs = (isPlainObject(schema) && Array.isArray(schema.settings) ? schema.settings : []).filter((setting) => isPlainObject(setting) && typeof setting.id === "string").map((setting) => `\t${setting.id}: block.settings.${setting.id},`);
+	return [
+		`{% render '${`@/${component.segments.join("/")}`}',`,
+		...settingArgs,
+		"	shopify_attributes: block.shopify_attributes",
+		"%}"
+	].join("\n");
 }
 function wrapEmbedded(tag, body) {
 	return `{% ${tag} %}\n${indent(body.trimEnd())}\n{% end${tag} %}`;
@@ -220,14 +265,14 @@ function rewriteRenders(source, component, lookup) {
 	return source.replace(/(\{%-?\s*(?:render|include)\s+['"])((?:@|\.)\/[^'"]+)(['"])/g, (_match, prefix, importPath, suffix) => {
 		const lookupKey = resolveImport(importPath, component).join("/");
 		const target = lookup.get(lookupKey);
-		if (!target) throw new Error(`Cannot resolve render '${importPath}' (looked up '${lookupKey}') from ${component.liquid.path}`);
+		if (!target) throw new Error(`Cannot resolve render '${importPath}' (looked up '${lookupKey}') from ${anchorSourceOf(component).path}`);
 		return `${prefix}${builtNameOf(target)}${suffix}`;
 	});
 }
 function resolveImport(importPath, component) {
 	if (importPath.startsWith("@/")) return importPath.slice(2).split("/").filter(Boolean);
 	if (importPath.startsWith("./")) {
-		if (importPath.includes("../")) throw new Error(`'../' is not supported in render path: '${importPath}' (in ${component.liquid.path})`);
+		if (importPath.includes("../")) throw new Error(`'../' is not supported in render path: '${importPath}' (in ${anchorSourceOf(component).path})`);
 		const remaining = importPath.slice(2).split("/").filter(Boolean);
 		return [...component.segments, ...remaining];
 	}

package/docs/build-spec.md

@@ -117,10 +117,10 @@ aliases (modeled on Next.js / TypeScript path conventions):
 
 <!-- prettier-ignore -->
 ```liquid
-{# inside src/sections/hero/hero.liquid: #}
+{% # inside src/sections/hero/hero.liquid: %}
 
-{% render './components/foo' %}        {# nested child of hero       #}
-{% render '@/components/button' %}     {# top-level shared component #}
+{% render './components/foo' %}        {% # nested child of hero %}
+{% render '@/components/button' %}     {% # top-level shared component %}
 ```
 
 Both rewrite to namespaced output names:
@@ -133,7 +133,8 @@ Both rewrite to namespaced output names:
 Hand-written snippets remain referenceable by their bare name as usual:
 
 ```liquid
-{% render 'icon-cart' %} {# unchanged — resolves to snippets/icon-cart.liquid #}
+{% render 'icon-cart' %}
+{% # unchanged — resolves to snippets/icon-cart.liquid %}
 ```
 
 ### TS / CSS — colocated and implicit
@@ -249,6 +250,97 @@ The parent section or block's schema auto-merges these private children into its
 prepended, any blocks the author explicitly lists (e.g. globally-shared block
 types) appended after. No helper call required.
 
+### Block faces — nested `block/`
+
+A `src/components/*` component is a snippet — reusable through
+`{% render '@/components/...' %}`, but invisible to the theme editor. A **block
+face** exposes that same component as a theme block a merchant can add, without
+duplicating it. It's declared structurally: a singular `block/` directory nested
+inside the component.
+
+```
+src/components/image/
+├── image.liquid              # the reusable snippet
+├── image.css
+└── block/
+    └── image.schema.ts       # the block face's schema
+```
+
+Compiles to **both**:
+
+```
+snippets/built--components--image.liquid   # the snippet, unchanged
+blocks/built--components--image.liquid     # the block face
+```
+
+`block/` is a **zero-segment marker**. Unlike the plural `blocks/` type marker
+(which contributes a `blocks` segment and holds private children), singular
+`block/` contributes nothing to the naming segments — it only retargets the
+component's type to `blocks` and reroots file lookup inside `block/`. That's why
+the face is named `built--components--image` (after the parent), not
+`…--image--block`, and why it lands in `blocks/` rather than `snippets/`. The
+face's anchor files are named after the **parent** component (`image.liquid`,
+`image.schema.ts`), so the source basename still equals the output token, as
+everywhere else.
+
+> Note the singular/plural distinction: `block/` (one face) vs `blocks/` (many
+> private children). They can nest — see the `tabs` example below.
+
+The face's schema is authored exactly like any block schema — a sibling
+`image.schema.ts` exporting `schema` (via `defineSchemaBlock`). It needs no new
+concepts; the `block/` directory is the only signal.
+
+**Mechanical vs. override.** Two ways to author the face body:
+
+- **Mechanical (schema only).** With just `block/<name>.schema.ts` and no
+  `block/<name>.liquid`, the engine **synthesizes** the wrapper: it renders the
+  underlying component, mapping each schema setting to a render arg of the same
+  name (`id == arg`) and passing `shopify_attributes` through. This covers the
+  common case where every setting maps 1:1 to a prop.
+
+  ```liquid
+  {%- comment -%} GENERATED … {%- endcomment -%}
+  {% render 'built--components--image',
+  	src: block.settings.src,
+  	shopify_attributes: block.shopify_attributes
+  %}
+  {% schema %}…{% endschema %}
+  ```
+
+  Because the mechanism is `id == arg`, **name the component's props to match
+  the setting ids.** There is no mapping table.
+
+- **Override (`block/<name>.liquid`).** When the wrapper isn't mechanical —
+  derived props, conditional logic, or passing `children: block.blocks` — drop a
+  `block/<name>.liquid` and the engine uses it as the body verbatim (rewriting
+  its `@/...` renders, stamping the banner, injecting the schema). The face is
+  then just a normal block component living in `block/`, so it may also carry
+  its own `block/<name>.ts` / `block/<name>.css`.
+
+**Private children of a face.** Because private children belong to the block —
+not the snippet — they nest under the face via the plural `blocks/` marker:
+
+```
+src/components/tabs/
+├── tabs.liquid
+└── block/
+    ├── tabs.liquid           # override — renders children: block.blocks
+    ├── tabs.schema.ts
+    └── blocks/
+        └── tab/
+            ├── tab.liquid
+            └── tab.schema.ts
+```
+
+The singular `block/` adds no segment and the plural `blocks/` adds `blocks`, so
+the child resolves to `_built--components--tabs--blocks--tab` and auto-merges
+into the face's `blocks: [...]` — the existing private-block machinery,
+unchanged.
+
+A mechanical face requires the underlying snippet to exist (it renders it); if
+the snippet is missing the render won't resolve. A thing that is purely a block
+with no reusable-snippet angle should just live in `src/blocks/`.
+
 ## Build Pipeline
 
 The engine lives in `lib/build/build.ts` and is invoked by `lib/cli.ts` (a citty
@@ -266,8 +358,11 @@ rebuilds the bin and `npm run test:all` runs the full integration chain against
    `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.
+3. **For each component** (anything with a `.liquid`, plus mechanical block
+   faces anchored on a schema alone — see
+   [Block faces](#block-faces--nested-block)):
+   - Prepend a `{%- comment -%}` banner naming the source file (the `.liquid`,
+     or for a mechanical face its `.schema.ts`), 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()`,
@@ -277,7 +372,10 @@ rebuilds the bin and `npm run test:all` runs the full integration chain against
    - Auto-merge any immediate private `blocks/` children into the loaded
      schema's `blocks: [...]` array (see
      [Private blocks](#private-blocks--nested-blocks)).
-   - Transform `<name>.liquid`:
+   - Produce the body — either the source `<name>.liquid`, or, for a mechanical
+     block face (no `.liquid`), a synthesized wrapper that renders the
+     underlying component with each schema setting mapped to a render arg and
+     `shopify_attributes` passed through. Then:
      - **Error** if the source `.liquid` contains an inline `{% schema %}` block
        — schemas must live in `<name>.schema.ts`.
      - Rewrite `{% render '@/...' %}` and `{% render './...' %}` to namespaced