mechanica-shared 2.0.0-alpha.8 → 2.0.1

package/README.md

@@ -1,10 +1,13 @@
 # mechanica-shared
 
-Internal support package for [mechanica](https://www.npmjs.com/package/mechanica) — DOM-free types, the field-type registry, schema/default helpers, the page-generation (SSG) core, and the `.page.md` page-format codec.
+Internal support package for [mechanica](https://www.npmjs.com/package/mechanica): DOM-free types, the field-type registry, schema/default helpers, the page-generation (SSG) core, SEO helpers, and the codecs for Mechanica's on-disk formats.
 
-You normally don't install this directly; it comes with `mechanica`. It is published separately so server-side renderers can consume it without the editor/runtime.
+You normally don't install this directly; it comes with `mechanica`. It's published separately so server-side renderers can use it without the editor or the runtime. Keep its version in step with `mechanica`'s.
 
 Entry points:
 
-- `mechanica-shared` — types, field registry, schema helpers, `generatePage` and the `{{ }}` HTML templating engine. DOM-free by contract.
-- `mechanica-shared/page-format` — `parsePage` / `serializePage` for the `.page.md` on-disk format. A separate entry point on purpose: it pulls in a YAML parser that must never reach a client bundle.
+- `mechanica-shared`: types, the field registry, schema helpers, `generatePage` and the `{{ }}` HTML templating engine, the query engine, locale and translation-overlay helpers, and the SEO helpers (`applySeoTags`, `auditPageHtml`, `buildSitemap`, `buildRobotsTxt`). DOM-free by contract.
+- `mechanica-shared/page-format`: `parsePage` / `serializePage` for `.page.md` page files.
+- `mechanica-shared/block-format`: `parseComposedBlock` / `serializeComposedBlock` for the Block Composer's `.block.yml` files.
+
+The two codecs are separate entry points on purpose: they pull in a YAML parser that must never reach a client bundle.

package/dist/block-format.js

@@ -65,6 +65,8 @@ function parseComposedBlock(text, fallbackId) {
 	};
 	if (typeof doc.icon === "string") def.icon = doc.icon;
 	if (typeof doc.category === "string") def.category = doc.category;
+	if (doc.hidden === true) def.hidden = true;
+	if (doc.standalone === true) def.standalone = true;
 	if (isPlainObject(doc.props)) def.props = doc.props;
 	if (isPlainObject(doc.previewData)) def.previewData = doc.previewData;
 	return def;
@@ -77,6 +79,8 @@ function serializeComposedBlock(def) {
 	};
 	if (def.icon) ordered.icon = def.icon;
 	if (def.category) ordered.category = def.category;
+	if (def.hidden) ordered.hidden = true;
+	if (def.standalone) ordered.standalone = true;
 	if (def.props && Object.keys(def.props).length) ordered.props = def.props;
 	if (def.previewData && Object.keys(def.previewData).length) ordered.previewData = def.previewData;
 	ordered.template = def.template ?? [];

package/dist/index.js

@@ -122,18 +122,34 @@ function localeLabel(config, code) {
 */
 /** Reserved data keys the composer engine consumes (never passed as props). */
 var IF_KEY = "$if";
+var EACH_KEY = "$each";
 /** Whether a value is a prop binding (`{ $bind: 'name' }`). */
 function isBinding(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.$bind === "string";
 }
 /**
+* Look up a binding name in a prop scope. Supports dot paths (`$item.title`,
+* `cta.url`) so a repeated subtree can bind fields of the current `$item` and a
+* binding can reach into an object prop without exposing each leaf separately.
+*/
+function lookupBinding(name, props) {
+	if (name in props) return props[name];
+	if (!name.includes(".")) return void 0;
+	let value = props;
+	for (const part of name.split(".")) {
+		if (value === null || typeof value !== "object") return void 0;
+		value = value[part];
+	}
+	return value;
+}
+/**
 * Deep-resolve a data value: substitute every `{ $bind: name }` with the named
 * prop, recursing through arrays and plain objects (so a bound value nested in
 * e.g. a `smartLink` object resolves too). Non-binding scalars pass through;
 * everything is cloned, so the returned value never aliases the template.
 */
 function resolveBindings(value, props) {
-	if (isBinding(value)) return props[value.$bind];
+	if (isBinding(value)) return lookupBinding(value.$bind, props);
 	if (Array.isArray(value)) return value.map((item) => resolveBindings(item, props));
 	if (value !== null && typeof value === "object") {
 		const out = {};
@@ -143,15 +159,15 @@ function resolveBindings(value, props) {
 	return value;
 }
 /** Resolve one template node, or `null` when a falsy `$if` binding drops it. */
-function resolveNode(node, props, prefix, index) {
+function resolveNode(node, props, prefix, index, idSuffix = "") {
 	const raw = node.data ?? {};
 	if (IF_KEY in raw && !resolveBindings(raw[IF_KEY], props)) return null;
 	const data = {};
 	for (const [key, value] of Object.entries(raw)) {
-		if (key === IF_KEY) continue;
+		if (key === IF_KEY || key === EACH_KEY) continue;
 		data[key] = resolveBindings(value, props);
 	}
-	const id = `${prefix}:${node.id ?? index}`;
+	const id = `${prefix}:${node.id ?? index}${idSuffix}`;
 	const resolved = {
 		id,
 		blockId: node.blockId,
@@ -164,6 +180,20 @@ function resolveNode(node, props, prefix, index) {
 function resolveList(list, props, prefix) {
 	const out = [];
 	list.forEach((child, index) => {
+		const each = child.data?.[EACH_KEY];
+		if (typeof each === "string") {
+			const items = lookupBinding(each, props);
+			if (!Array.isArray(items)) return;
+			items.forEach((item, i) => {
+				const resolved = resolveNode(child, {
+					...props,
+					$item: item,
+					$index: i
+				}, prefix, index, `@${i}`);
+				if (resolved) out.push(resolved);
+			});
+			return;
+		}
 		const resolved = resolveNode(child, props, prefix, index);
 		if (resolved) out.push(resolved);
 	});
@@ -177,9 +207,10 @@ function resolveChildren(children, props, prefix) {
 }
 /**
 * Expand a composed block's template into a concrete content tree: substitute
-* `$bind` values from `props`, drop `$if`-hidden nodes, and namespace every
-* node id under `instanceId` (the placed block's id — stable across renders).
-* The result is rendered by the normal block-render pipeline.
+* `$bind` values from `props`, repeat `$each` nodes per array item, drop
+* `$if`-hidden nodes, and namespace every node id under `instanceId` (the
+* placed block's id — stable across renders). The result is rendered by the
+* normal block-render pipeline.
 */
 function resolveComposedTemplate(def, props, instanceId) {
 	return resolveList(def.template ?? [], props ?? {}, instanceId);
@@ -479,7 +510,10 @@ async function generatePage(options) {
 	index = index.slice(0, start) + rendered + index.slice(end);
 	const links = options.pageLinks?.(options.state.content) ?? [];
 	if (links.length) index = index.replace("</head>", `${links.join("\n")}\n</head>`);
-	if (options.assetsUrl) index = index.replace(/\/assets\//g, options.assetsUrl);
+	if (options.assetsUrl) {
+		const base = options.assetsUrl.replace(/\/+$/, "");
+		index = index.replace(/(["'(=])\/assets\//g, (_, edge) => `${edge}${base}/assets/`);
+	}
 	const stateScript = `<script>window.state=${serializeState(state)}<\/script>`;
 	return {
 		html: index.replace("</body>", `${stateScript}\n</body>`),
@@ -968,4 +1002,4 @@ async function resolveQueryKey(source, key, context = {}) {
 	return {};
 }
 //#endregion
-export { applySeoTags, areFieldSchemasRegistered, auditPageHtml, buildPreviewData, buildRobotsTxt, buildSitemap, builtinFields, collectInternalLinks, deepEqual, diffBlocks, diffTranslation, diffValue, findUnknownBlocks, generatePage, generateProject, getDefaultValue, getFieldDefault, getValueByPath, isBinding, isLocale, isPaginatedQuery, localeLabel, localePath, mergeBlocks, mergePreviewData, mergeTranslation, mergeValue, migrateContent, normalizeClassManifest, normalizeInternalUrl, normalizeLocales, pageUrl, paginationVariantPath, parseLocalePath, parseQueryKey, passDataToHTML, passDefaultValue, registerFieldSchemas, resolveBindings, resolveComposedTemplate, resolvePagesQuery, resolveQueryKey, serializeState, templateBlockIds, validateLinks, walkSchema, walkTree };
+export { applySeoTags, areFieldSchemasRegistered, auditPageHtml, buildPreviewData, buildRobotsTxt, buildSitemap, builtinFields, collectInternalLinks, deepEqual, diffBlocks, diffTranslation, diffValue, findUnknownBlocks, generatePage, generateProject, getDefaultValue, getFieldDefault, getValueByPath, isBinding, isLocale, isPaginatedQuery, localeLabel, localePath, lookupBinding, mergeBlocks, mergePreviewData, mergeTranslation, mergeValue, migrateContent, normalizeClassManifest, normalizeInternalUrl, normalizeLocales, pageUrl, paginationVariantPath, parseLocalePath, parseQueryKey, passDataToHTML, passDefaultValue, registerFieldSchemas, resolveBindings, resolveComposedTemplate, resolvePagesQuery, resolveQueryKey, serializeState, templateBlockIds, validateLinks, walkSchema, walkTree };

package/dist/page-format.js

@@ -171,6 +171,7 @@ function parsePage(text, options) {
 	return {
 		...typeof envelope.name === "string" ? { name: envelope.name } : {},
 		...envelope.draft === true ? { draft: true } : {},
+		...typeof envelope.layout === "string" && envelope.layout !== "" ? { layout: envelope.layout } : {},
 		...envelope.meta !== void 0 ? { meta: envelope.meta } : {},
 		...typeof envelope.order === "number" ? { order: envelope.order } : {},
 		...envelope.orderAfter != null ? { orderAfter: envelope.orderAfter } : {},
@@ -215,6 +216,7 @@ function serializePage(doc, options) {
 	const envelope = {};
 	if (doc.name !== void 0) envelope.name = doc.name;
 	if (doc.draft) envelope.draft = true;
+	if (doc.layout) envelope.layout = doc.layout;
 	if (doc.meta !== void 0) envelope.meta = doc.meta;
 	envelope.data = doc.data ?? {};
 	if (doc.order !== void 0) envelope.order = doc.order;

package/dist/types/compose.d.ts

@@ -1,6 +1,12 @@
 import type { ComposedBlockDefinition, ContentBlock, PropBinding } from './types';
 /** Whether a value is a prop binding (`{ $bind: 'name' }`). */
 export declare function isBinding(value: unknown): value is PropBinding;
+/**
+ * Look up a binding name in a prop scope. Supports dot paths (`$item.title`,
+ * `cta.url`) so a repeated subtree can bind fields of the current `$item` and a
+ * binding can reach into an object prop without exposing each leaf separately.
+ */
+export declare function lookupBinding(name: string, props: Record<string, unknown>): unknown;
 /**
  * Deep-resolve a data value: substitute every `{ $bind: name }` with the named
  * prop, recursing through arrays and plain objects (so a bound value nested in
@@ -10,9 +16,10 @@ export declare function isBinding(value: unknown): value is PropBinding;
 export declare function resolveBindings(value: unknown, props: Record<string, unknown>): unknown;
 /**
  * Expand a composed block's template into a concrete content tree: substitute
- * `$bind` values from `props`, drop `$if`-hidden nodes, and namespace every
- * node id under `instanceId` (the placed block's id — stable across renders).
- * The result is rendered by the normal block-render pipeline.
+ * `$bind` values from `props`, repeat `$each` nodes per array item, drop
+ * `$if`-hidden nodes, and namespace every node id under `instanceId` (the
+ * placed block's id — stable across renders). The result is rendered by the
+ * normal block-render pipeline.
  */
 export declare function resolveComposedTemplate(def: ComposedBlockDefinition, props: Record<string, unknown> | undefined, instanceId: string): ContentBlock[];
 /**

package/dist/types/generate-page.d.ts

@@ -16,6 +16,8 @@ export interface PageState {
         title?: string;
         path?: string;
         meta?: Record<string, unknown>;
+        /** The page's layout (key into the app's `layouts` map). */
+        layout?: string;
         /** Set on paginated variants: which chunk of the page's paginated query this is. */
         pagination?: {
             page: number;
@@ -56,7 +58,14 @@ export interface GeneratePageOptions {
     locales?: LocalesConfig;
     baseUrl?: string;
     path?: string;
-    /** Rewrite `/assets/` to this base when set. */
+    /**
+     * Serve build assets from this base URL (a CDN origin like
+     * `https://cdn.example.com`). Root-relative `/assets/…` references in the
+     * HTML are prefixed with it — `/assets/x.js` → `<assetsUrl>/assets/x.js` — so
+     * the built `assets/` folder can live on a CDN. A trailing slash is ignored,
+     * and an already-absolute `https://…/assets/` URL is left untouched. Uploaded
+     * media (`/media/…`) is rewritten by the export's `onFile`, not here.
+     */
     assetsUrl?: string;
     /**
      * Extra `<link>` tags for this page's content, injected before `</head>` —

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
 export type { Block, ContentBlock, ComposedBlockDefinition, ComposerComponentDefinition, ComposerComponentEntry, ComposerManifest, ComposerClassDefinition, ComposerClassEntry, ComposerClassDef, ComposerElementKind, ComposerBreakpoints, PropBinding, DataEntry, DataScope, PageMeta, State, PageLink, VirtualPage, } from './types';
 export { normalizeClassManifest } from './composer-manifest';
 export { normalizeLocales, isLocale, parseLocalePath, localePath, localeLabel, type LocalesConfig, type LocalesOption, } from './locale';
-export { resolveComposedTemplate, resolveBindings, templateBlockIds, isBinding, } from './compose';
+export { resolveComposedTemplate, resolveBindings, lookupBinding, templateBlockIds, isBinding, } from './compose';
 export { type FieldType, type ImageCropConfig, type RegisterAlias, builtinFields, registerFieldSchemas, getFieldDefault, areFieldSchemasRegistered, } from './fields';
 export { getDefaultValue, passDefaultValue, buildPreviewData, mergePreviewData, walkTree, walkSchema, getValueByPath, } from './schema';
 export { generatePage, generateProject, passDataToHTML, serializeState, type GeneratePageOptions, type GenerateProjectOptions, type PageState, type RenderResult, } from './generate-page';

package/dist/types/page-format.d.ts

@@ -12,6 +12,11 @@ export interface PageDoc {
      * static export. Absent/false for published pages.
      */
     draft?: boolean;
+    /**
+     * The page's layout — a key into the app's `layouts` map. Absent = the
+     * default layout. Base-owned: translation files never carry it.
+     */
+    layout?: string;
     meta?: Record<string, unknown>;
     /** Page-scoped data overrides (defineData). */
     data: Record<string, unknown>;

package/dist/types/types.d.ts

@@ -11,6 +11,13 @@ export interface PageMeta {
     title?: string;
     path?: string;
     meta?: Record<string, unknown>;
+    /**
+     * The page's layout — a key into the app's `layouts` map (`defineMechanicaApp`).
+     * Authored as top-level `layout:` frontmatter in the `.page.md`. Absent = the
+     * default layout (the map's first entry). Base-owned on multi-language sites:
+     * translations always inherit it.
+     */
+    layout?: string;
     /**
      * Set on paginated variants of a page (`/blog/2`, …): which chunk of its
      * paginated query this URL shows. Page 1 is the base path and carries none.
@@ -49,6 +56,19 @@ export interface Block {
     hidden?: boolean;
     /** Available only in dev, stripped from production output. */
     devOnly?: boolean;
+    /**
+     * A block that *is* a whole page (a feedback form, a 404, a legal page).
+     * Offered under a "Pages" palette group only while the page is still empty,
+     * and never on a page that already has content — so page-shaped blocks stop
+     * polluting the palette everywhere else. Placed blocks always keep rendering.
+     */
+    standalone?: boolean;
+    /**
+     * Restrict the block to pages using these layouts (keys of the app's
+     * `layouts` map). Omitted = offered on every layout. Like `folders`, this
+     * only filters the palette — placed blocks always render.
+     */
+    layouts?: string[];
     /**
      * Restrict the block to pages under these folders (folder paths relative to
      * `pages/`, e.g. `'docs'`; nested folders match by prefix). Omitted = offered
@@ -192,6 +212,20 @@ export interface ComposedBlockDefinition {
     icon?: string;
     /** Palette grouping; defaults to a "Site blocks" group in the editor. */
     category?: string;
+    /**
+     * Hidden from the palette (like `Block.hidden`). Set on one-off blocks —
+     * e.g. a block created to design a single page in the composer — so they
+     * don't appear under "Site blocks" on every other page. Placed instances
+     * keep rendering; untick in the composer settings to promote it to reusable.
+     */
+    hidden?: boolean;
+    /**
+     * A whole-page block (like `Block.standalone`): offered in the empty page's
+     * "Start this page" palette group and the Page setup pane's Page-block
+     * select, never alongside content blocks. Toggled in the composer settings —
+     * a designer-built 404 or coming-soon page.
+     */
+    standalone?: boolean;
     /**
      * compact-json-schema for the props exposed out of the template (§ prop
      * bindings). Placed instances get an auto-generated settings form from this,
@@ -233,6 +267,14 @@ export interface DataEntry {
     title?: string;
     /** compact-json-schema describing the data shape. */
     props?: Record<string, unknown>;
+    /**
+     * Restrict the entry to pages under this folder (a folder path relative to
+     * `pages/`, e.g. `'examples'`; nested folders match by prefix). Omitted =
+     * offered on every page. This only filters what the editor's Data dialog
+     * *draws* — the value's scope (site / folder / page) and where it is stored
+     * are unaffected, so a page-scoped value still lives in the page file.
+     */
+    folder?: string;
     /**
      * Translate this entry per locale (multi-language sites). Its site/folder
      * value is stored per locale (with fallback to the default locale) instead of
@@ -296,10 +338,12 @@ export interface VirtualPage {
     path: string;
     /** The block tree to render — usually one template block parameterized by `data`. */
     content: ContentBlock[];
-    /** Page-scoped data (head, layout, block props). Site data still merges under it. */
+    /** Page-scoped data (head, block props). Site data still merges under it. */
     data?: Record<string, unknown>;
     /** Page meta: `title` (breadcrumb / SEO name), `noindex`, and `{{ page.meta.* }}` hints. */
     meta?: Record<string, unknown>;
+    /** The page's layout (key into the app's `layouts` map); absent = default. */
+    layout?: string;
     /** The locale this page renders in. Omit for the default locale. */
     locale?: string;
     /** Every locale this logical page exists in — for hreflang alternates + language switchers. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mechanica-shared",
-  "version": "2.0.0-alpha.8",
+  "version": "2.0.1",
   "description": "DOM-free types, schema helpers and page-generation core shared across Mechanica",
   "license": "MIT",
   "repository": {
@@ -9,27 +9,22 @@
   },
   "type": "module",
   "publishConfig": {
-    "access": "public",
-    "tag": "next"
+    "access": "public"
   },
   "files": [
-    "src",
     "dist"
   ],
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "bun": "./src/index.ts",
       "import": "./dist/index.js"
     },
     "./page-format": {
       "types": "./dist/types/page-format.d.ts",
-      "bun": "./src/page-format.ts",
       "import": "./dist/page-format.js"
     },
     "./block-format": {
       "types": "./dist/types/block-format.d.ts",
-      "bun": "./src/block-format.ts",
       "import": "./dist/block-format.js"
     }
   },

package/src/block-format.ts

@@ -1,100 +0,0 @@
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
-import type { ComposedBlockDefinition, ContentBlock } from './types'
-
-/**
- * Codec for the composed-block file format (`.mech/blocks/<id>.block.yml`) — a
- * single YAML document holding a {@link ComposedBlockDefinition}. Kept a
- * separate entry point (`mechanica-shared/block-format`), deliberately NOT
- * re-exported from the barrel: it pulls in the YAML parser, and the barrel is
- * imported by the client runtime, which never parses these files (only the dev
- * store, the plugin's collect step, and the CLI do). Mirrors the `page-format`
- * rule. See PLAN.md § 3.
- */
-
-/** Thrown by {@link parseComposedBlock} with a human-readable reason. */
-export class ComposedBlockParseError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'ComposedBlockParseError'
-    Object.setPrototypeOf(this, ComposedBlockParseError.prototype)
-  }
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-/** Validate the minimal shape of a content node (recurses into children). */
-function assertContentBlock(node: unknown, where: string): asserts node is ContentBlock {
-  if (!isPlainObject(node)) throw new ComposedBlockParseError(`${where}: expected a mapping`)
-  if (typeof node.blockId !== 'string' || node.blockId === '') {
-    throw new ComposedBlockParseError(`${where}: missing "blockId"`)
-  }
-  if (node.data !== undefined && !isPlainObject(node.data)) {
-    throw new ComposedBlockParseError(`${where}: "data" must be a mapping`)
-  }
-  const children = node.children
-  if (children === undefined) return
-  if (Array.isArray(children)) {
-    children.forEach((child, i) => assertContentBlock(child, `${where} › child ${i}`))
-  } else if (isPlainObject(children)) {
-    for (const [slot, list] of Object.entries(children)) {
-      if (!Array.isArray(list)) throw new ComposedBlockParseError(`${where}: slot "${slot}" must be a list`)
-      list.forEach((child, i) => assertContentBlock(child, `${where} › ${slot}[${i}]`))
-    }
-  } else {
-    throw new ComposedBlockParseError(`${where}: "children" must be a list or a slot mapping`)
-  }
-}
-
-/**
- * Parse a `.block.yml` document into a {@link ComposedBlockDefinition}.
- *
- * @param fallbackId Used as the id when the document omits one — the store and
- *                   plugin pass the filename base, so a hand-authored file may
- *                   omit `id` and be identified by its filename.
- */
-export function parseComposedBlock(text: string, fallbackId?: string): ComposedBlockDefinition {
-  let doc: unknown
-  try {
-    doc = parseYaml(text)
-  } catch (error) {
-    throw new ComposedBlockParseError(`invalid YAML: ${error instanceof Error ? error.message : error}`)
-  }
-  if (doc == null) doc = {}
-  if (!isPlainObject(doc)) throw new ComposedBlockParseError('expected a top-level mapping')
-
-  const id = typeof doc.id === 'string' && doc.id !== '' ? doc.id : fallbackId
-  if (!id) throw new ComposedBlockParseError('missing "id"')
-  if (typeof doc.name !== 'string' || doc.name === '') throw new ComposedBlockParseError('missing "name"')
-
-  const template = doc.template ?? []
-  if (!Array.isArray(template)) throw new ComposedBlockParseError('"template" must be a list')
-  template.forEach((node, i) => assertContentBlock(node, `template[${i}]`))
-
-  if (doc.props !== undefined && !isPlainObject(doc.props)) {
-    throw new ComposedBlockParseError('"props" must be a mapping')
-  }
-  if (doc.previewData !== undefined && !isPlainObject(doc.previewData)) {
-    throw new ComposedBlockParseError('"previewData" must be a mapping')
-  }
-
-  const def: ComposedBlockDefinition = { id, name: doc.name, template: template as ContentBlock[] }
-  if (typeof doc.icon === 'string') def.icon = doc.icon
-  if (typeof doc.category === 'string') def.category = doc.category
-  if (isPlainObject(doc.props)) def.props = doc.props
-  if (isPlainObject(doc.previewData)) def.previewData = doc.previewData
-  return def
-}
-
-/** Serialize a {@link ComposedBlockDefinition} to a `.block.yml` document. */
-export function serializeComposedBlock(def: ComposedBlockDefinition): string {
-  // Build an ordered object so the file reads header-first, tree-last.
-  const ordered: Record<string, unknown> = { id: def.id, name: def.name }
-  if (def.icon) ordered.icon = def.icon
-  if (def.category) ordered.category = def.category
-  if (def.props && Object.keys(def.props).length) ordered.props = def.props
-  if (def.previewData && Object.keys(def.previewData).length) ordered.previewData = def.previewData
-  ordered.template = def.template ?? []
-  return stringifyYaml(ordered, { lineWidth: 0 })
-}

package/src/compose.ts

@@ -1,120 +0,0 @@
-import type { ComposedBlockDefinition, ContentBlock, PropBinding } from './types'
-
-/**
- * Expansion of composed blocks into a concrete content tree. DOM- and
- * framework-free so the render side (client, SSR, export) shares one
- * implementation. See PLAN.md § 2.3 / § 4.4.
- */
-
-/** Reserved data keys the composer engine consumes (never passed as props). */
-const IF_KEY = '$if'
-
-/** Whether a value is a prop binding (`{ $bind: 'name' }`). */
-export function isBinding(value: unknown): value is PropBinding {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    !Array.isArray(value) &&
-    typeof (value as { $bind?: unknown }).$bind === 'string'
-  )
-}
-
-/**
- * Deep-resolve a data value: substitute every `{ $bind: name }` with the named
- * prop, recursing through arrays and plain objects (so a bound value nested in
- * e.g. a `smartLink` object resolves too). Non-binding scalars pass through;
- * everything is cloned, so the returned value never aliases the template.
- */
-export function resolveBindings(value: unknown, props: Record<string, unknown>): unknown {
-  if (isBinding(value)) return props[value.$bind]
-  if (Array.isArray(value)) return value.map((item) => resolveBindings(item, props))
-  if (value !== null && typeof value === 'object') {
-    const out: Record<string, unknown> = {}
-    for (const [key, item] of Object.entries(value)) out[key] = resolveBindings(item, props)
-    return out
-  }
-  return value
-}
-
-/** Resolve one template node, or `null` when a falsy `$if` binding drops it. */
-function resolveNode(
-  node: ContentBlock,
-  props: Record<string, unknown>,
-  prefix: string,
-  index: number,
-): ContentBlock | null {
-  const raw = node.data ?? {}
-  // `$if` gates the node's presence — resolve it before anything else so a
-  // hidden element costs nothing downstream.
-  if (IF_KEY in raw && !resolveBindings(raw[IF_KEY], props)) return null
-
-  const data: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(raw)) {
-    if (key === IF_KEY) continue
-    data[key] = resolveBindings(value, props)
-  }
-
-  // Namespace ids under the placed instance so two placements of the same
-  // composed block produce distinct, stable vnode keys.
-  const id = `${prefix}:${node.id ?? index}`
-  const resolved: ContentBlock = { id, blockId: node.blockId, data }
-  if (node.v != null) resolved.v = node.v
-  if (node.children) resolved.children = resolveChildren(node.children, props, id)
-  return resolved
-}
-
-function resolveList(list: ContentBlock[], props: Record<string, unknown>, prefix: string): ContentBlock[] {
-  const out: ContentBlock[] = []
-  list.forEach((child, index) => {
-    const resolved = resolveNode(child, props, prefix, index)
-    if (resolved) out.push(resolved)
-  })
-  return out
-}
-
-function resolveChildren(
-  children: NonNullable<ContentBlock['children']>,
-  props: Record<string, unknown>,
-  prefix: string,
-): ContentBlock['children'] {
-  if (Array.isArray(children)) return resolveList(children, props, `${prefix}/d`)
-  const map: Record<string, ContentBlock[]> = {}
-  for (const [name, list] of Object.entries(children)) {
-    map[name] = resolveList(list, props, `${prefix}/${name}`)
-  }
-  return map
-}
-
-/**
- * Expand a composed block's template into a concrete content tree: substitute
- * `$bind` values from `props`, drop `$if`-hidden nodes, and namespace every
- * node id under `instanceId` (the placed block's id — stable across renders).
- * The result is rendered by the normal block-render pipeline.
- */
-export function resolveComposedTemplate(
-  def: ComposedBlockDefinition,
-  props: Record<string, unknown> | undefined,
-  instanceId: string,
-): ContentBlock[] {
-  return resolveList(def.template ?? [], props ?? {}, instanceId)
-}
-
-/**
- * Block ids referenced anywhere in a composed template (recursing into slot
- * children). Used to expand a page's used-block set so the underlying compiled
- * blocks' chunks load before a composed block mounts. Element blocks (`mech:*`)
- * ship with the runtime; they need no loader but are harmless to include.
- */
-export function templateBlockIds(def: ComposedBlockDefinition): Set<string> {
-  const ids = new Set<string>()
-  const walk = (list: ContentBlock[]): void => {
-    for (const node of list) {
-      ids.add(node.blockId)
-      if (!node.children) continue
-      if (Array.isArray(node.children)) walk(node.children)
-      else for (const inner of Object.values(node.children)) walk(inner)
-    }
-  }
-  walk(def.template ?? [])
-  return ids
-}

package/src/composer-manifest.ts

@@ -1,45 +0,0 @@
-import type {
-  ComposerClassDef,
-  ComposerClassEntry,
-  ComposerElementKind,
-} from './types'
-
-/**
- * Normalize the Block Composer manifest's `classes` record into the flat list
- * the composer consumes — unfolding the string / array shorthands and defaulting
- * each title to its class name. Pure and DOM-free (the barrel is client-safe);
- * called from the generated `virtual:mechanica/components` module at runtime.
- * See COMPOSER-MANIFEST.md § 2.
- *
- * Shorthands:
- *  - `'text'`               → `{ on: ['text'] }`
- *  - `['frame', 'image']`   → `{ on: ['frame', 'image'] }`
- *  - `{ title?, on, group? }` → as written (only the full form carries a group)
- */
-export function normalizeClassManifest(
-  classes: Record<string, ComposerClassEntry> | undefined,
-): ComposerClassDef[] {
-  if (!classes) return []
-  const out: ComposerClassDef[] = []
-  for (const cls in classes) {
-    const entry = classes[cls]
-    if (entry == null) continue
-    const kinds = classKinds(entry)
-    if (!kinds.length) continue
-    const full = typeof entry === 'object' && !Array.isArray(entry) ? entry : null
-    const def: ComposerClassDef = { cls, title: full?.title || cls, kinds }
-    if (full?.group) def.group = full.group
-    out.push(def)
-  }
-  return out
-}
-
-const KINDS: readonly ComposerElementKind[] = ['frame', 'text', 'image']
-const isKind = (v: unknown): v is ComposerElementKind => KINDS.includes(v as ComposerElementKind)
-
-/** The element kinds a `classes` entry applies to (any shorthand), deduped. */
-function classKinds(entry: ComposerClassEntry): ComposerElementKind[] {
-  const raw = isKind(entry) ? [entry] : Array.isArray(entry) ? entry : entry.on
-  const list = Array.isArray(raw) ? raw : [raw]
-  return [...new Set(list.filter(isKind))]
-}