@o-a/cms-agent 0.1.0

package/dist/create-site/template/vhost/Dockerfile

@@ -0,0 +1,33 @@
+# Generic and site-content-agnostic - this file never needs to change
+# per site. Runs identically via plain `docker build`/`docker run` on a
+# bare VPS, Fly, ECS, or any PaaS - nothing platform-specific is baked
+# in here (see docs/hosting.md for platform-specific deploy config,
+# which always layers on top of this, never inside it).
+#
+# Lives in vhost/, not the site root, alongside the rest of the site's
+# own serving config (package.json, server.js, site.config.json) - the
+# build context is still the site root, so build with:
+#   docker build -f vhost/Dockerfile -t my-site .
+FROM node:22-alpine
+
+# git is a hard runtime requirement (services/startup-checks.ts fails
+# fast without it) - content, drafts and publishes are all real git
+# operations, not a database.
+RUN apk add --no-cache git
+
+# Build-time install happens against the image-baked copy of the site
+# ("/seed"), never directly against "/site" - "/site" is where a
+# persistent volume gets mounted at runtime, and anything written there
+# during the build would simply be shadowed by that mount.
+WORKDIR /seed
+COPY . .
+RUN cd vhost && npm install --omit=dev
+
+WORKDIR /site
+COPY vhost/docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+# Must match vhost/site.config.json's own "port" field.
+EXPOSE 3000
+
+ENTRYPOINT ["/docker-entrypoint.sh"]

package/dist/create-site/template/vhost/docker-entrypoint.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+set -e
+
+# First boot against an empty mounted volume: seed it from the
+# image-baked copy at /seed (content, theme, the already-`npm
+# install`ed vhost/node_modules). A later boot finds /site/vhost
+# already populated and skips this, so the same image works
+# identically with a real persistent volume mounted at /site
+# (production) or with nothing mounted at all (a quick local trial,
+# where content just lives in the ephemeral container layer).
+if [ ! -d /site/vhost ]; then
+  cp -r /seed/. /site/
+fi
+
+# The site root must be a real git repository (services/startup-checks.ts) -
+# a plain `docker build` from a full local checkout preserves .git, but
+# some platforms (Railway's `railway up` included) build from a
+# git-archive-style upload of tracked file contents only, which never
+# includes .git at all. Recovered here rather than assumed away: if
+# it's missing, start a fresh repo over the already-seeded content.
+if [ ! -d /site/.git ]; then
+  git -C /site init --quiet
+  git -C /site add -A
+  GIT_AUTHOR_NAME="cms-agent" GIT_AUTHOR_EMAIL="cms-agent@localhost" \
+    GIT_COMMITTER_NAME="cms-agent" GIT_COMMITTER_EMAIL="cms-agent@localhost" \
+    git -C /site commit --quiet -m "chore: initial scaffold (recovered - .git was not part of the deploy upload)"
+fi
+
+cd /site/vhost
+exec node server.js

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { startServer, buildServer } from './server.ts';
+export type { BuildServerOptions } from './server.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+// The package's public entry point (package.json's "main"): a site's
+// real server.js ("import the agent, point it at this directory,
+// start", per the build plan) imports startServer from here.
+export { startServer, buildServer } from "./server.js";

package/dist/media/drivers/driver.d.ts

@@ -0,0 +1,11 @@
+export interface MediaListEntry {
+    name: string;
+    size: number;
+    mtimeMs: number;
+}
+export interface MediaStorageDriver {
+    list(): Promise<MediaListEntry[]>;
+    put(filename: string, bytes: Buffer): Promise<void>;
+    get(filename: string): Promise<Buffer | null>;
+    delete(filename: string): Promise<boolean>;
+}

package/dist/media/drivers/driver.js

@@ -0,0 +1 @@
+export {};

package/dist/media/drivers/local-fs-driver.d.ts

@@ -0,0 +1,3 @@
+import type { MediaStorageDriver } from './driver.ts';
+export declare const DRIVER_NAME = "local-fs";
+export declare function openLocalFsMediaDriver(root: string): MediaStorageDriver;

package/dist/media/drivers/local-fs-driver.js

@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { PathSafetyError, sanitisePath } from "../../services/path-safety.js";
+// A plain string constant, matching node-sqlite-driver.ts's own
+// DRIVER_NAME convention - safe for the capabilities endpoint to
+// report without needing to import anything fs-touching.
+export const DRIVER_NAME = 'local-fs';
+// The default (and, for this build increment, only) MediaStorageDriver
+// implementation. No driver-containment static-analysis test exists
+// for this yet, unlike search/drivers' own G5 check for node:sqlite -
+// node:fs is a single already-pervasive Node builtin, not a swappable
+// third-party library the way node:sqlite/better-sqlite3 are, so
+// there's no "which alternative" question to fence off yet. The
+// natural trigger for that kind of test is a future object-storage
+// driver's own third-party SDK import.
+//
+// Every method resolves filename through sanitisePath itself before
+// touching disk - this file importing both node:fs and sanitisePath
+// is what satisfies the B7 static-analysis rule with no allowlist
+// entry needed, matching assets.ts/content.ts's own pattern of the
+// fs-touching file being the one that calls it.
+export function openLocalFsMediaDriver(root) {
+    return {
+        async list() {
+            mkdirSync(root, { recursive: true });
+            return readdirSync(root, { withFileTypes: true })
+                .filter((entry) => entry.isFile())
+                .map((entry) => {
+                const stats = statSync(sanitisePath(root, entry.name));
+                return { name: entry.name, size: stats.size, mtimeMs: stats.mtimeMs };
+            });
+        },
+        async put(filename, bytes) {
+            const resolved = sanitisePath(root, filename);
+            // Harmless no-op for a flat, content-addressed namespace (media
+            // filenames never contain subdirectories) - matches
+            // manage-menus.ts's own defensive precedent of creating the
+            // parent directory before a write rather than assuming it
+            // already exists.
+            mkdirSync(dirname(resolved), { recursive: true });
+            // No existence check first: content-addressed naming means an
+            // identical re-upload writes identical bytes over identical
+            // bytes - a harmless idempotent overwrite, not something that
+            // needs special-casing.
+            writeFileSync(resolved, bytes);
+        },
+        async get(filename) {
+            let resolved;
+            try {
+                resolved = sanitisePath(root, filename);
+            }
+            catch (error) {
+                // An invalid/traversal-shaped filename reads as "not found"
+                // from this method's own contract - the route layer is what
+                // decides whether that's a 404 or something else, the driver
+                // itself stays mechanical.
+                if (error instanceof PathSafetyError) {
+                    return null;
+                }
+                throw error;
+            }
+            if (!existsSync(resolved) || !statSync(resolved).isFile()) {
+                return null;
+            }
+            return readFileSync(resolved);
+        },
+        async delete(filename) {
+            // Unlike get(), a malformed delete path is let through
+            // uncaught - worth surfacing distinctly rather than silently
+            // reading as "already didn't exist", matching
+            // manage-redirects.ts's own not-found-is-a-distinct-reason
+            // precedent.
+            const resolved = sanitisePath(root, filename);
+            if (!existsSync(resolved)) {
+                return false;
+            }
+            unlinkSync(resolved);
+            return true;
+        },
+    };
+}

package/dist/media/filename.d.ts

@@ -0,0 +1 @@
+export declare function buildMediaFilename(originalFilename: string, bytes: Buffer): string;

package/dist/media/filename.js

@@ -0,0 +1,31 @@
+import { createHash } from 'node:crypto';
+import { basename, extname } from 'node:path';
+// Content-addressed: the filename is derived from a hash of the
+// file's own bytes, so two uploads can never collide, and an
+// identical re-upload naturally produces the identical filename (a
+// harmless overwrite in local-fs-driver.ts's put(), not a duplicate).
+// No separate manifest/index recording original filenames - this
+// codebase avoids a second source of truth on principle (the same
+// reasoning that keeps the SQLite search index disposable rather than
+// authoritative), so the original name is folded into the filename
+// itself instead of tracked anywhere else.
+//
+// Truncated to 12 hex chars (48 bits), not the full 64-char digest -
+// git itself only shows short hashes for the same reason. At this
+// length a collision between two different files stays astronomically
+// unlikely (well past a 1-in-a-trillion chance even at tens of
+// thousands of uploads to one site), while keeping filenames/URLs/git
+// history actually readable.
+//
+// Slug regex matches generate-site.ts's own sanitisePackageName -
+// lowercase, non [a-z0-9-] runs collapsed to a single "-", trimmed -
+// not a second, independently-invented convention.
+const HASH_LENGTH = 12;
+export function buildMediaFilename(originalFilename, bytes) {
+    const hash = createHash('sha256').update(bytes).digest('hex').slice(0, HASH_LENGTH);
+    const base = basename(originalFilename, extname(originalFilename));
+    const cleaned = base.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+    const slug = cleaned.length > 0 ? cleaned : 'file';
+    const extension = extname(originalFilename).toLowerCase();
+    return `${hash}-${slug}${extension}`;
+}

package/dist/media/manage-media.d.ts

@@ -0,0 +1,19 @@
+import type { SiteConfig } from '../config.ts';
+export type ManageMediaReason = 'not-found' | 'invalid-file-type';
+export declare class ManageMediaError extends Error {
+    readonly reason: ManageMediaReason;
+    constructor(reason: ManageMediaReason, message: string);
+}
+export interface MediaEntry {
+    name: string;
+    size: number;
+    mtimeMs: number;
+    url: string;
+}
+export declare function listMedia(config: SiteConfig): Promise<MediaEntry[]>;
+export declare function putMedia(config: SiteConfig, originalFilename: string, bytes: Buffer): Promise<{
+    name: string;
+    size: number;
+    url: string;
+}>;
+export declare function deleteMedia(config: SiteConfig, filename: string): Promise<void>;

package/dist/media/manage-media.js

@@ -0,0 +1,45 @@
+import { enqueue } from "../services/write-queue.js";
+import { openLocalFsMediaDriver } from "./drivers/local-fs-driver.js";
+import { buildMediaFilename } from "./filename.js";
+export class ManageMediaError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'ManageMediaError';
+        this.reason = reason;
+    }
+}
+function mediaUrl(name) {
+    return `/media/${name}`;
+}
+// Opens a fresh driver per call rather than threading one long-lived
+// instance through BootedSite - unlike DatabaseSync, plain fs calls
+// have no connection/handle to reuse, so there's no driver-lifecycle
+// wiring needed. The only call site that decides which driver to open
+// is here, hardcoded, matching how rebuild-index.ts hardcodes
+// openNodeSqliteDriver today with no config-driven selection either -
+// this is where a future config-driven driver choice would go.
+function driverFor(config) {
+    return openLocalFsMediaDriver(config.mediaRoot);
+}
+// Not enqueued - reads bypass the write queue, matching
+// handleListRedirects' own precedent of only serialising mutations.
+export async function listMedia(config) {
+    const entries = await driverFor(config).list();
+    return entries.map((entry) => ({ ...entry, url: mediaUrl(entry.name) }));
+}
+export function putMedia(config, originalFilename, bytes) {
+    return enqueue(async () => {
+        const name = buildMediaFilename(originalFilename, bytes);
+        await driverFor(config).put(name, bytes);
+        return { name, size: bytes.length, url: mediaUrl(name) };
+    });
+}
+export function deleteMedia(config, filename) {
+    return enqueue(async () => {
+        const existed = await driverFor(config).delete(filename);
+        if (!existed) {
+            throw new ManageMediaError('not-found', `No media file at "${filename}"`);
+        }
+    });
+}

package/dist/migrations/index.d.ts

@@ -0,0 +1,3 @@
+import type { MigrationMap } from '../services/migration-runner.ts';
+export declare const CURRENT_SCHEMA_VERSION = 5;
+export declare const migrations: MigrationMap;

package/dist/migrations/index.js

@@ -0,0 +1,49 @@
+// The current content schema version. Bumping this and adding a new
+// migrations[N] entry is the only way a content shape may change
+// (constraint 4) - never a manual edit convention.
+export const CURRENT_SCHEMA_VERSION = 5;
+// A trivial identity migration, proving the mechanism (per the build
+// plan's Phase 1 scope): no shape change, only the version bump. Safe
+// against page.schema.json's schemaVersion: { minimum: 1 } (not an
+// exact/enum check), so nothing else needs updating for this bump to
+// keep validating.
+function migrateV1ToV2(content) {
+    return { ...content, schemaVersion: 2 };
+}
+// page.schema.json now requires "type" (Phase 2 Group D, backing the
+// GET /v1/content list endpoint's type filter). Every page authored
+// before this migration is a generic page, not any newer distinct
+// kind, so "page" is a safe, honest default for existing content -
+// never invented per-file, always this one fixed value.
+function migrateV2ToV3(content) {
+    return { ...content, schemaVersion: 3, type: 'page' };
+}
+// page.schema.json now requires "layout" (theme layouts group), naming
+// which theme/layouts/*.liquid file wraps this page's rendered
+// content. Every page authored before this migration used the only
+// layout that existed at the time, so "theme" (theme/layouts/theme.liquid)
+// is the correct default, not an invented placeholder - render-page.ts's
+// own read path applies this exact same default defensively too, since
+// migrations aren't wired to run automatically anywhere yet.
+function migrateV3ToV4(content) {
+    return { ...content, schemaVersion: 4, layout: 'theme' };
+}
+// page.schema.json now requires "name" (the admin's own page tree
+// label, distinct from "title" - the same content can now be called
+// "Home Page" in the tree while still rendering a different <title>).
+// Every page authored before this migration has never had a name of
+// its own, so its existing title is the only honest default - not an
+// invented placeholder, and not the file's own path/slug, which is a
+// separate concept again. content-read.ts's listContent applies this
+// exact same title fallback defensively too, since migrations aren't
+// wired to run automatically anywhere yet.
+function migrateV4ToV5(content) {
+    const title = typeof content.title === 'string' ? content.title : '';
+    return { ...content, schemaVersion: 5, name: title };
+}
+export const migrations = {
+    1: migrateV1ToV2,
+    2: migrateV2ToV3,
+    3: migrateV3ToV4,
+    4: migrateV4ToV5,
+};

package/dist/renderer/engine.d.ts

@@ -0,0 +1,2 @@
+import { Liquid } from 'liquidjs';
+export declare function createEngine(snippets: Record<string, string>): Liquid;

package/dist/renderer/engine.js

@@ -0,0 +1,48 @@
+import { Liquid } from 'liquidjs';
+// Called exactly once, inside bootSite - never a setter invoked again
+// mid-process. This is what keeps "every theme file read once at
+// boot" a structural guarantee rather than a convention: a mutable
+// singleton with a snippets setter would let a future caller silently
+// reload snippets without a restart, exactly what this design exists
+// to avoid.
+//
+// Nothing beyond these constructor options is ever configured: no
+// registerTag, no registerFilter, no plugin() - ever (constraint: no
+// dynamically registered Liquid tags or filters). fs and
+// relativeReference are stock constructor options, not registered
+// tags/filters - confirmed empirically that the built-in `render` tag
+// resolves purely against the in-memory `snippets` map below, with no
+// disk access at all, and that a snippet rendered this way is still
+// bounded by renderLimit (see test/renderer/engine.test.ts, D8, and
+// test/renderer/snippets.test.ts).
+//
+// outputEscape: 'escape' makes {{ value }} escape HTML by default (a
+// stock constructor option, not a registered filter/tag), with an
+// explicit `| raw` as the only opt-out - used for pre-rendered block
+// HTML that was already safely rendered by an earlier parseAndRender
+// call (see render-page.ts), and for content_for_layout in a layout
+// template for the same reason.
+//
+// renderLimit: 50 (ms) is the only reliable defence against a runaway
+// template: an external Promise.race/setTimeout wrapper cannot abort a
+// synchronous-only render (LiquidJS's drive loop only yields to the
+// event loop when it awaits an actual Promise), confirmed empirically.
+// This bounds a single parseAndRender call, not a whole page: a page
+// with many sections/blocks each individually finishing just under
+// budget has no aggregate ceiling. A page-level wall-clock guard is a
+// Phase 2 route-handler concern, once there is an actual request to
+// bound - not solved here.
+export function createEngine(snippets) {
+    return new Liquid({
+        outputEscape: 'escape',
+        renderLimit: 50,
+        relativeReference: false,
+        fs: {
+            exists: async (file) => file in snippets,
+            existsSync: (file) => file in snippets,
+            readFile: async (file) => snippets[file],
+            readFileSync: (file) => snippets[file],
+            resolve: (_root, file) => file,
+        },
+    });
+}

package/dist/renderer/render-page.d.ts

@@ -0,0 +1,28 @@
+import type { Liquid } from 'liquidjs';
+import type { SiteConfig } from '../config.ts';
+import type { ThemeTemplates } from './theme-templates.ts';
+export type PageRenderReason = 'page-not-found' | 'missing-section-type' | 'missing-block-type' | 'missing-layout' | 'template-error';
+export declare class PageRenderError extends Error {
+    readonly reason: PageRenderReason;
+    constructor(reason: PageRenderReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface SectionOrBlockInstance {
+    id: string;
+    type: string;
+    settings: Record<string, unknown>;
+    blocks?: SectionOrBlockInstance[];
+}
+export interface PageContent {
+    schemaVersion: number;
+    title: string;
+    published: boolean;
+    layout: string;
+    sections: SectionOrBlockInstance[];
+}
+export declare function renderSections(page: PageContent, themeTemplates: ThemeTemplates, engine: Liquid): Promise<string>;
+export type RenderMode = 'public' | 'preview';
+export declare function parsePageContent(raw: string): PageContent;
+export declare function renderLoadedPage(page: PageContent, config: SiteConfig, themeTemplates: ThemeTemplates, layouts: Record<string, string>, engine: Liquid): Promise<string>;
+export declare function renderPage(config: SiteConfig, themeTemplates: ThemeTemplates, layouts: Record<string, string>, engine: Liquid, relativePath: string, mode: RenderMode): Promise<string>;

package/dist/renderer/render-page.js

@@ -0,0 +1,143 @@
+import { readFileSync } from 'node:fs';
+import { loadMenus } from "../services/menus.js";
+import { sanitisePath } from "../services/path-safety.js";
+export class PageRenderError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'PageRenderError';
+        this.reason = reason;
+    }
+}
+// Renders one section or block, recursively rendering any nested blocks
+// first (instance.schema.json is self-referential, so a block can carry
+// its own nested blocks). Never uses {% include %}/{% render %}: block
+// HTML is pre-rendered here in JS and handed to the parent template as
+// a plain array, which sidesteps LiquidJS's own filesystem include
+// resolution entirely.
+async function renderInstance(instance, kind, themeTemplates, engine) {
+    const templates = kind === 'section' ? themeTemplates.sections : themeTemplates.blocks;
+    const template = templates[instance.type];
+    if (!template) {
+        throw new PageRenderError(kind === 'section' ? 'missing-section-type' : 'missing-block-type', `${kind === 'section' ? 'Section' : 'Block'} type "${instance.type}" is missing from the theme (${kind} id: "${instance.id}")`);
+    }
+    const blocksHtml = [];
+    for (const block of instance.blocks ?? []) {
+        blocksHtml.push(await renderInstance(block, 'block', themeTemplates, engine));
+    }
+    // Shopify-style scope shape: settings nested under the instance, not
+    // flattened, so templates read section.settings.x / block.settings.x.
+    const scope = kind === 'section'
+        ? { section: { id: instance.id, type: instance.type, settings: instance.settings }, blocksHtml }
+        : { block: { id: instance.id, type: instance.type, settings: instance.settings }, blocksHtml };
+    try {
+        return (await engine.parseAndRender(template, scope));
+    }
+    catch (error) {
+        if (error instanceof PageRenderError) {
+            throw error;
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new PageRenderError('template-error', `Failed to render ${kind} "${instance.id}" (type "${instance.type}"): ${detail}`, { cause: error });
+    }
+}
+// Renders a page's top-level sections, in declared order, concatenated.
+// No page-level layout/wrapper concept in Phase 1 - this is the whole
+// output.
+export async function renderSections(page, themeTemplates, engine) {
+    const html = [];
+    for (const section of page.sections) {
+        html.push(await renderInstance(section, 'section', themeTemplates, engine));
+    }
+    return html.join('');
+}
+// The layout a page with no layout field (or an invalid one) gets
+// defaulted to. boot.ts never auto-migrates content, so a real site
+// can have pre-existing pages that predate this field entirely - this
+// default must match migrateV3ToV4's own default exactly, so render
+// behaviour is identical whether or not a site has ever run its
+// migrations (content-read.ts established this same defensive-read
+// pattern for the "type" field).
+const DEFAULT_LAYOUT = 'theme';
+// Throws on invalid JSON rather than swallowing to null - callers reading
+// a specific historical revision (preview-revision.ts) want to know "the
+// JSON at this ref is broken" as a distinct, reportable case, whereas
+// tryReadPage's null return means "nothing here, try the next root".
+export function parsePageContent(raw) {
+    const parsed = JSON.parse(raw);
+    const layout = typeof parsed.layout === 'string' && parsed.layout.length > 0 ? parsed.layout : DEFAULT_LAYOUT;
+    return { ...parsed, layout };
+}
+function tryReadPage(root, relativePath) {
+    const fullPath = sanitisePath(root, relativePath);
+    try {
+        return parsePageContent(readFileSync(fullPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// Public mode reads /content/ only, and treats published: false the same
+// as "doesn't exist" - this is what makes unpublish actually take a
+// page offline (checklist C8: the renderer skips unpublished pages).
+// Preview mode overlays /drafts/ over /content/, falling back to live
+// when no draft exists, and deliberately does NOT filter on published:
+// an editor needs to see a currently-unpublished page to review it
+// before republishing.
+function loadPageForRender(config, relativePath, mode) {
+    if (mode === 'preview') {
+        const draft = tryReadPage(config.draftsRoot, relativePath);
+        if (draft) {
+            return draft;
+        }
+        const live = tryReadPage(config.contentRoot, relativePath);
+        if (live) {
+            return live;
+        }
+        throw new PageRenderError('page-not-found', `No page found at "${relativePath}"`);
+    }
+    const live = tryReadPage(config.contentRoot, relativePath);
+    if (!live || live.published === false) {
+        throw new PageRenderError('page-not-found', `No publicly reachable page found at "${relativePath}"`);
+    }
+    return live;
+}
+// The shared back half of rendering: takes a page already loaded from
+// wherever (current draft/live disk state via loadPageForRender, or a
+// historical git blob via readFileAtRevision + parsePageContent) and runs
+// it through the identical layout/section/menu pipeline - so "render
+// what's on disk" and "render this specific historical revision" never
+// duplicate this logic.
+export async function renderLoadedPage(page, config, themeTemplates, layouts, engine) {
+    // Checked before rendering any sections, matching the fail-fast
+    // ordering missing-section-type/missing-block-type already
+    // establish - no point rendering a page's whole body just to
+    // discover its layout doesn't exist.
+    const layoutTemplate = layouts[page.layout];
+    if (!layoutTemplate) {
+        throw new PageRenderError('missing-layout', `Layout "${page.layout}" is missing from the theme`);
+    }
+    const bodyHtml = await renderSections(page, themeTemplates, engine);
+    // Menus are content, not theme data - loaded fresh here rather than
+    // once at boot, same freshness guarantee as the page itself. Scoped
+    // to the layout only (not threaded into renderSections/renderInstance
+    // above), matching the confirmed requirement: a layout renders nav,
+    // sections/blocks don't need it in this pass. No mode distinction:
+    // menus have no draft state (Group N), always the live file. This
+    // also means a historical page preview always shows today's menus,
+    // never a menu as it existed at that revision - an accepted limitation.
+    const menus = loadMenus(config);
+    // content_for_layout is already-rendered, already-safe HTML (like
+    // blocksHtml handed to a section template) - the layout template
+    // itself must use `{{ content_for_layout | raw }}`, or engine.ts's
+    // outputEscape: 'escape' double-escapes it into literal text.
+    return (await engine.parseAndRender(layoutTemplate, {
+        content_for_layout: bodyHtml,
+        page: { title: page.title },
+        menus,
+    }));
+}
+export async function renderPage(config, themeTemplates, layouts, engine, relativePath, mode) {
+    const page = loadPageForRender(config, relativePath, mode);
+    return renderLoadedPage(page, config, themeTemplates, layouts, engine);
+}

package/dist/renderer/theme-templates.d.ts

@@ -0,0 +1,7 @@
+export interface ThemeTemplates {
+    sections: Record<string, string>;
+    blocks: Record<string, string>;
+}
+export declare function loadThemeTemplates(themeRoot: string): ThemeTemplates;
+export declare function loadSnippets(themeRoot: string): Record<string, string>;
+export declare function loadLayouts(themeRoot: string): Record<string, string>;

package/dist/renderer/theme-templates.js

@@ -0,0 +1,82 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseThemeComponentFile } from "../services/theme-component-file.js";
+// themeRoot is agent configuration (the configured site's theme
+// directory), not a request-supplied :path parameter. This walk is
+// deliberately NOT the Group B path-sanitisation helper and must
+// never be reused for untrusted request paths.
+//
+// Flat *.liquid files, one per type, named directly (e.g. hero.liquid,
+// media-text.liquid) - no subfolder per type, no separate schema.json.
+// Mirrors loadFlatTemplates below exactly, extended to strip the
+// embedded {% schema %} block (via theme-component-file.ts's shared
+// parser - the same parse theme-schemas.ts uses for the other half of
+// the same file) before handing the remaining markup to the Liquid
+// engine, since {% schema %} is never a real, live Liquid tag.
+function loadTypeTemplates(typesDir) {
+    const templates = {};
+    let entries;
+    try {
+        entries = readdirSync(typesDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.liquid'))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return templates;
+    }
+    for (const fileName of entries) {
+        const type = fileName.slice(0, -'.liquid'.length);
+        let source;
+        try {
+            source = readFileSync(join(typesDir, fileName), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseThemeComponentFile(source);
+        if (!parsed) {
+            continue;
+        }
+        templates[type] = parsed.markup;
+    }
+    return templates;
+}
+export function loadThemeTemplates(themeRoot) {
+    return {
+        sections: loadTypeTemplates(join(themeRoot, 'sections')),
+        blocks: loadTypeTemplates(join(themeRoot, 'blocks')),
+    };
+}
+// Flat *.liquid files, one per name, no subdirectory-per-name and no
+// co-located schema.json - unlike sections/blocks, snippets and
+// layouts are theme-author code with no user-facing settings to
+// declare, matching Shopify's own flat snippets/layouts convention.
+// Same agent-configuration-not-request-path caveat as loadTypeTemplates.
+function loadFlatTemplates(dir) {
+    const templates = {};
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.liquid'))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return templates;
+    }
+    for (const fileName of entries) {
+        const name = fileName.slice(0, -'.liquid'.length);
+        try {
+            templates[name] = readFileSync(join(dir, fileName), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+    }
+    return templates;
+}
+export function loadSnippets(themeRoot) {
+    return loadFlatTemplates(join(themeRoot, 'snippets'));
+}
+export function loadLayouts(themeRoot) {
+    return loadFlatTemplates(join(themeRoot, 'layouts'));
+}