@wocart/theme 0.0.0-stage → 1.0.0

package/dist/manifest.js

@@ -0,0 +1,308 @@
+/**
+ * The serializable half of the theme contract: a `ThemeDefinition` as data, for
+ * tooling that must read a theme without executing its modules.
+ *
+ * `themeManifest` derives the manifest from the code (one source of truth).
+ * `validateThemeManifest` is the boundary for a manifest that arrives as JSON:
+ * serializability is checked on the raw input, structure by `ThemeManifestSchema`
+ * (which also normalizes), and relational rules by `validateThemeDefinition` —
+ * so the manifest and assembly validators cannot disagree.
+ */
+import { z } from "zod";
+import { validateThemeDefinition } from "./definitions.js";
+/** Version of the manifest schema and its interpretation (not the theme's). */
+export const THEME_MANIFEST_CONTRACT_VERSION = 1;
+const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+// ── Derivation ───────────────────────────────────────────────────────────────
+/** Derive the data-only manifest from a theme. `component` and `load` are dropped. */
+export function themeManifest(theme) {
+    return {
+        contractVersion: THEME_MANIFEST_CONTRACT_VERSION,
+        key: theme.key,
+        version: theme.version,
+        surfaces: (theme.surfaces ?? []).map((surface) => ({
+            key: surface.key,
+            label: copyData(surface.label),
+        })),
+        locales: [...(theme.locales ?? [])],
+        components: Object.fromEntries(Object.entries(theme.components).map(([key, definition]) => [
+            key,
+            componentSpec(definition),
+        ])),
+    };
+}
+function componentSpec(definition) {
+    return {
+        type: definition.type,
+        label: copyData(definition.label),
+        ...(definition.group === undefined ? {} : { group: copyData(definition.group) }),
+        fields: (definition.fields ?? []).map((field) => copyData(field)),
+        slots: (definition.slots ?? []).map((slot) => copyData(slot)),
+        ...(definition.capabilities === undefined
+            ? {}
+            : { capabilities: copyData(definition.capabilities) }),
+    };
+}
+/**
+ * A deep copy of authored data (labels, fields, slots), so the manifest never
+ * aliases the theme. These values are JSON by definition; anything that is not
+ * is exactly what `validateThemeManifest` reports.
+ */
+function copyData(value) {
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+// ── Schema (structure + normalization) ───────────────────────────────────────
+/** A label or text value: the same in every language, or one per language. */
+const LocalizedTextSchema = z.union([z.string(), z.record(z.string(), z.string())]);
+const FieldCommonSchema = {
+    key: z.string(),
+    label: LocalizedTextSchema,
+    description: z.exactOptional(LocalizedTextSchema),
+    required: z.exactOptional(z.boolean()),
+};
+const TextFieldSchema = z.object({
+    ...FieldCommonSchema,
+    contentKey: z.exactOptional(z.string()),
+    default: z.exactOptional(LocalizedTextSchema),
+});
+const FieldSchema = z.discriminatedUnion("kind", [
+    TextFieldSchema.extend({ kind: z.literal("text") }),
+    TextFieldSchema.extend({ kind: z.literal("textarea") }),
+    z.object({
+        ...FieldCommonSchema,
+        kind: z.literal("number"),
+        default: z.exactOptional(z.number()),
+        min: z.exactOptional(z.number()),
+        max: z.exactOptional(z.number()),
+    }),
+    z.object({
+        ...FieldCommonSchema,
+        kind: z.literal("boolean"),
+        default: z.exactOptional(z.boolean()),
+    }),
+    z.object({
+        ...FieldCommonSchema,
+        kind: z.literal("select"),
+        options: z.array(z.string()),
+        default: z.exactOptional(z.string()),
+    }),
+    z.object({
+        ...FieldCommonSchema,
+        kind: z.literal("url"),
+        default: z.exactOptional(z.string()),
+    }),
+]);
+const ComponentSpecSchema = z.object({
+    type: z.string(),
+    label: LocalizedTextSchema,
+    group: z.exactOptional(LocalizedTextSchema),
+    fields: z.array(FieldSchema).default([]),
+    slots: z
+        .array(z.object({
+        name: z.string(),
+        multiple: z.exactOptional(z.boolean()),
+        allow: z.exactOptional(z.array(z.string())),
+    }))
+        .default([]),
+    capabilities: z.exactOptional(z.object({ insertable: z.exactOptional(z.boolean()) })),
+});
+/**
+ * The manifest's structural shape. Unknown keys are stripped (the forward-compat
+ * tradeoff documented in the README); absent `fields`/`slots` normalize to `[]`.
+ * Rules that span fields are not here — `validateThemeManifest` applies them.
+ */
+export const ThemeManifestSchema = z.object({
+    contractVersion: z.literal(THEME_MANIFEST_CONTRACT_VERSION),
+    key: z.string(),
+    version: z.string(),
+    surfaces: z
+        .array(z.object({ key: z.string(), label: LocalizedTextSchema }))
+        .default([]),
+    locales: z.array(z.string()).default([]),
+    components: z.record(z.string(), ComponentSpecSchema),
+});
+// ── Validation ───────────────────────────────────────────────────────────────
+/**
+ * Validate a manifest that arrived from outside the code. A structural failure
+ * returns `{ manifest: null, issues }`; a non-semver `version` is advisory and
+ * returns the manifest with an `invalid-version` issue.
+ */
+export function validateThemeManifest(input) {
+    if (!isRecord(input)) {
+        return fatal("", "invalid-manifest", "manifest must be an object");
+    }
+    if (input.contractVersion !== THEME_MANIFEST_CONTRACT_VERSION) {
+        return fatal("contractVersion", "unsupported-contract", `unsupported manifest contractVersion ${JSON.stringify(input.contractVersion ?? null)}; this SDK understands version ${THEME_MANIFEST_CONTRACT_VERSION}`);
+    }
+    const serializability = [];
+    inspectSerializable(input, serializability);
+    if (serializability.length > 0) {
+        return { manifest: null, issues: serializability };
+    }
+    const parsed = ThemeManifestSchema.safeParse(input);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => {
+            const path = toPath(issue.path);
+            return { path, code: codeAt(path), message: issue.message };
+        });
+        return { manifest: null, issues };
+    }
+    const manifest = parsed.data;
+    const issues = validateThemeDefinition(probeOf(manifest)).map((issue) => ({
+        path: issue.path,
+        code: issue.code === "type-mismatch" ? "type-mismatch" : codeAt(issue.path),
+        message: issue.message,
+    }));
+    if (issues.length > 0) {
+        return { manifest: null, issues };
+    }
+    if (!SEMVER_PATTERN.test(manifest.version)) {
+        issues.push({
+            path: "version",
+            code: "invalid-version",
+            message: `theme version "${manifest.version}" is not semver; the manifest is still valid`,
+        });
+    }
+    return { manifest, issues };
+}
+function fatal(path, code, message) {
+    return { manifest: null, issues: [{ path, code, message }] };
+}
+/** Maps a path into the manifest to the issue code its section owns. */
+function codeAt(path) {
+    if (path === "key")
+        return "invalid-identity";
+    if (path === "version")
+        return "invalid-version";
+    if (path === "surfaces" || path.startsWith("surfaces["))
+        return "invalid-surface";
+    if (path.startsWith("components."))
+        return "invalid-component";
+    return "invalid-manifest";
+}
+function toPath(segments) {
+    return segments.reduce((path, segment) => {
+        if (typeof segment === "number")
+            return `${path}[${segment}]`;
+        const name = String(segment);
+        return path === "" ? name : `${path}.${name}`;
+    }, "");
+}
+/**
+ * The manifest as a `ThemeDefinition` with a placeholder component, so the
+ * assembly validator checks the relational rules without a real component.
+ */
+function probeOf(manifest) {
+    return {
+        key: manifest.key,
+        version: manifest.version,
+        surfaces: manifest.surfaces,
+        locales: manifest.locales,
+        components: Object.fromEntries(Object.entries(manifest.components).map(([key, spec]) => [
+            key,
+            { ...spec, component: null },
+        ])),
+    };
+}
+// ── Serializability ──────────────────────────────────────────────────────────
+function inspectSerializable(input, issues) {
+    for (const [key, value] of Object.entries(input)) {
+        if (key === "components")
+            continue;
+        if (rejectPrototypeKey(key, key, issues))
+            continue;
+        inspectValue(value, key, issues, new Set());
+    }
+    const components = input.components;
+    if (components === undefined)
+        return;
+    if (!isRecord(components)) {
+        inspectValue(components, "components", issues, new Set());
+        return;
+    }
+    for (const [key, entry] of Object.entries(components)) {
+        const path = `components.${key}`;
+        if (rejectPrototypeKey(key, path, issues))
+            continue;
+        if (!isRecord(entry)) {
+            inspectValue(entry, path, issues, new Set());
+            continue;
+        }
+        for (const [field, value] of Object.entries(entry)) {
+            const fieldPath = `${path}.${field}`;
+            if (field === "component" || field === "load") {
+                issues.push({
+                    path: fieldPath,
+                    code: "non-serializable",
+                    message: `\`${field}\` is runtime-only and does not belong in a manifest`,
+                });
+            }
+            else if (!rejectPrototypeKey(field, fieldPath, issues)) {
+                inspectValue(value, fieldPath, issues, new Set());
+            }
+        }
+    }
+}
+/**
+ * `__proto__` is valid JSON but never valid data: as a record key it would set a
+ * prototype instead of a field, so the entry would vanish without a report.
+ */
+function rejectPrototypeKey(key, path, issues) {
+    if (key !== "__proto__")
+        return false;
+    issues.push({
+        path,
+        code: codeAt(path),
+        message: "`__proto__` cannot be a key in a manifest",
+    });
+    return true;
+}
+function inspectValue(value, path, issues, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            issues.push(nonSerializable(path, `${value} is not a finite JSON number`));
+        }
+        return;
+    }
+    if (typeof value !== "object") {
+        issues.push(nonSerializable(path, `${typeof value} values cannot be serialized`));
+        return;
+    }
+    if (ancestors.has(value)) {
+        issues.push(nonSerializable(path, "circular references cannot be serialized"));
+        return;
+    }
+    if (!Array.isArray(value) && !isPlainObject(value)) {
+        issues.push(nonSerializable(path, "only plain objects, arrays and JSON primitives can be serialized"));
+        return;
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            inspectValue(item, `${path}[${index}]`, issues, ancestors);
+        });
+    }
+    else {
+        for (const [key, child] of Object.entries(value)) {
+            const childPath = `${path}.${key}`;
+            if (!rejectPrototypeKey(key, childPath, issues)) {
+                inspectValue(child, childPath, issues, ancestors);
+            }
+        }
+    }
+    ancestors.delete(value);
+}
+/**
+ * A plain object's prototype is `Object.prototype` (or none). Date, Map and
+ * class instances fail this: they do not survive a JSON round trip.
+ */
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === null || Object.getPrototypeOf(prototype) === null;
+}
+function nonSerializable(path, message) {
+    return { path, code: "non-serializable", message };
+}

package/dist/messages.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Content-pack messages: placeholders and plurals.
+ *
+ * Shopify's locale-file model, on the platform's own CLDR data
+ * (`Intl.PluralRules`) instead of a message-format library:
+ *
+ * - A placeholder is `{name}`; every occurrence is filled, numbers are
+ *   formatted for the language, and a placeholder without a value stays
+ *   visible rather than vanishing.
+ * - A plural message is a family of flat pack keys, one per CLDR category:
+ *   `cartItems_one`, `cartItems_few`, `cartItems_other`… The `count` value
+ *   picks the form its language's rules select; `_other` is the fallback.
+ *   As in Shopify, an explicit `_zero` form is used for a count of 0 in any
+ *   language ("Your cart is empty" rather than "0 items").
+ *
+ * Keys stay flat strings, so packs, merchant overrides and editors keep
+ * treating content as a plain `Record<string, string>`.
+ */
+/** The CLDR plural categories, in CLDR order. */
+export declare const PLURAL_CATEGORIES: readonly ["zero", "one", "two", "few", "many", "other"];
+export type PluralCategory = (typeof PLURAL_CATEGORIES)[number];
+export type MessageValues = Readonly<Record<string, string | number>>;
+export interface MessageOptions {
+    /** The language whose plural rules pick a form (BCP 47). */
+    locale: string;
+    /**
+     * How numbers are written. Defaults to `Intl.NumberFormat(locale)`; a theme
+     * whose market writes Latin digits in Arabic passes its own rule.
+     */
+    formatNumber?: (value: number) => string;
+}
+type Pack = Readonly<Record<string, string>>;
+/** The plural categories a language distinguishes, per CLDR. */
+export declare function pluralCategories(locale: string): PluralCategory[];
+/**
+ * The template for `key` with `count`: `_zero` for 0 when the pack has one,
+ * then the category the language's rules select, then `_other`, then the
+ * plain key. Without a count, the plain key.
+ */
+export declare function messageTemplate(pack: Pack, key: string, count: number | undefined, locale: string): string | undefined;
+/** Fill every `{name}` placeholder; numbers are formatted, unknown names stay visible. */
+export declare function fillPlaceholders(template: string, values: MessageValues, formatNumber: (value: number) => string): string;
+/**
+ * The message `key` from `pack`, with its plural form chosen by
+ * `values.count` and its placeholders filled. A key the pack does not carry
+ * renders as the key itself, so a missing string is visible, never blank.
+ */
+export declare function formatMessage(pack: Pack, key: string, values: MessageValues | undefined, options: MessageOptions): string;
+/** The keys of every plural message in a pack (`cartItems` for `cartItems_other`). */
+export declare function pluralMessageKeys(pack: Pack): string[];
+/**
+ * A pack's plural messages checked against its language: the forms CLDR says
+ * the language needs but the pack lacks, and forms it carries that the
+ * language never selects (`_zero` is always allowed — it is the explicit
+ * empty-state form). Empty when the pack is complete.
+ */
+export declare function pluralFormIssues(pack: Pack, locale: string): string[];
+/** One message's keys — the plain key and every plural form present — to ship to a browser script. */
+export declare function messageForms(pack: Pack, key: string): Record<string, string>;
+export {};

package/dist/messages.js

@@ -0,0 +1,100 @@
+/**
+ * Content-pack messages: placeholders and plurals.
+ *
+ * Shopify's locale-file model, on the platform's own CLDR data
+ * (`Intl.PluralRules`) instead of a message-format library:
+ *
+ * - A placeholder is `{name}`; every occurrence is filled, numbers are
+ *   formatted for the language, and a placeholder without a value stays
+ *   visible rather than vanishing.
+ * - A plural message is a family of flat pack keys, one per CLDR category:
+ *   `cartItems_one`, `cartItems_few`, `cartItems_other`… The `count` value
+ *   picks the form its language's rules select; `_other` is the fallback.
+ *   As in Shopify, an explicit `_zero` form is used for a count of 0 in any
+ *   language ("Your cart is empty" rather than "0 items").
+ *
+ * Keys stay flat strings, so packs, merchant overrides and editors keep
+ * treating content as a plain `Record<string, string>`.
+ */
+/** The CLDR plural categories, in CLDR order. */
+export const PLURAL_CATEGORIES = ["zero", "one", "two", "few", "many", "other"];
+const rulesCache = new Map();
+function pluralRules(locale) {
+    let rules = rulesCache.get(locale);
+    if (!rules) {
+        rules = new Intl.PluralRules(locale);
+        rulesCache.set(locale, rules);
+    }
+    return rules;
+}
+/** The plural categories a language distinguishes, per CLDR. */
+export function pluralCategories(locale) {
+    const used = new Set(pluralRules(locale).resolvedOptions().pluralCategories);
+    return PLURAL_CATEGORIES.filter((category) => used.has(category));
+}
+const own = (pack, key) => (Object.hasOwn(pack, key) ? pack[key] : undefined);
+/**
+ * The template for `key` with `count`: `_zero` for 0 when the pack has one,
+ * then the category the language's rules select, then `_other`, then the
+ * plain key. Without a count, the plain key.
+ */
+export function messageTemplate(pack, key, count, locale) {
+    if (count === undefined)
+        return own(pack, key);
+    if (count === 0 && own(pack, `${key}_zero`) !== undefined)
+        return own(pack, `${key}_zero`);
+    return own(pack, `${key}_${pluralRules(locale).select(count)}`) ?? own(pack, `${key}_other`) ?? own(pack, key);
+}
+/** Fill every `{name}` placeholder; numbers are formatted, unknown names stay visible. */
+export function fillPlaceholders(template, values, formatNumber) {
+    return template.replace(/\{(\w+)\}/g, (placeholder, name) => {
+        if (!Object.hasOwn(values, name))
+            return placeholder;
+        const value = values[name];
+        return typeof value === "number" ? formatNumber(value) : value;
+    });
+}
+/**
+ * The message `key` from `pack`, with its plural form chosen by
+ * `values.count` and its placeholders filled. A key the pack does not carry
+ * renders as the key itself, so a missing string is visible, never blank.
+ */
+export function formatMessage(pack, key, values = {}, options) {
+    const count = typeof values.count === "number" ? values.count : undefined;
+    const template = messageTemplate(pack, key, count, options.locale) ?? key;
+    const formatNumber = options.formatNumber ?? ((value) => new Intl.NumberFormat(options.locale).format(value));
+    return fillPlaceholders(template, values, formatNumber);
+}
+/** The keys of every plural message in a pack (`cartItems` for `cartItems_other`). */
+export function pluralMessageKeys(pack) {
+    const suffix = new RegExp(`_(?:${PLURAL_CATEGORIES.join("|")})$`);
+    return [...new Set(Object.keys(pack).filter((key) => suffix.test(key)).map((key) => key.replace(suffix, "")))];
+}
+/**
+ * A pack's plural messages checked against its language: the forms CLDR says
+ * the language needs but the pack lacks, and forms it carries that the
+ * language never selects (`_zero` is always allowed — it is the explicit
+ * empty-state form). Empty when the pack is complete.
+ */
+export function pluralFormIssues(pack, locale) {
+    const needed = new Set(pluralCategories(locale));
+    const issues = [];
+    for (const base of pluralMessageKeys(pack)) {
+        for (const category of PLURAL_CATEGORIES) {
+            const present = own(pack, `${base}_${category}`) !== undefined;
+            if (needed.has(category) && !present)
+                issues.push(`${base}_${category} is missing`);
+            if (!needed.has(category) && present && category !== "zero")
+                issues.push(`${base}_${category} is never used in ${locale}`);
+        }
+        if (own(pack, base) !== undefined)
+            issues.push(`${base} is both a plural message and a plain key`);
+    }
+    return issues;
+}
+/** One message's keys — the plain key and every plural form present — to ship to a browser script. */
+export function messageForms(pack, key) {
+    return Object.fromEntries([key, ...PLURAL_CATEGORIES.map((category) => `${key}_${category}`)]
+        .filter((candidate) => own(pack, candidate) !== undefined)
+        .map((candidate) => [candidate, own(pack, candidate)]));
+}

package/dist/page-data.d.ts

@@ -0,0 +1,9 @@
+import type { PageDataResult, ResolutionScope, ThemeDefinition } from "./types.js";
+/** Structural boundary: envelope + recursive instance shape + id uniqueness. */
+export declare function parsePageData(input: unknown): PageDataResult;
+/**
+ * Catalog conformance on top of the parse: unknown types, props and slots are
+ * reported (`resolveInstance` decides the same degradations the renderer will
+ * apply). Read-only.
+ */
+export declare function validatePageData(theme: ThemeDefinition, input: unknown, scope?: ResolutionScope): PageDataResult;

package/dist/page-data.js

@@ -0,0 +1,154 @@
+/**
+ * The read boundary. Structural parse-and-degrade (`parsePageData`) and
+ * catalog conformance (`validatePageData`).
+ *
+ * Policy: parse, degrade, report — never throw the page
+ * away, never mutate the input. `page` is null only when the envelope itself
+ * failed; a structurally invalid section is dropped with an issue; the
+ * document itself is not rewritten by `validatePageData`.
+ */
+import { resolveInstance } from "./instances.js";
+import { ComponentInstanceSchema, SURFACE_KEY_PATTERN } from "./schemas.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const envelopeFailure = (message) => ({
+    page: null,
+    issues: [{ path: "", code: "envelope-invalid", message }],
+});
+/** Structural boundary: envelope + recursive instance shape + id uniqueness. */
+export function parsePageData(input) {
+    if (!isRecord(input)) {
+        return envelopeFailure("page data must be a JSON object");
+    }
+    if (input.version !== 1) {
+        return envelopeFailure(`unsupported page-data version ${JSON.stringify(input.version ?? null)}; this SDK understands version 1`);
+    }
+    const surface = input.surface;
+    if (typeof surface !== "string" || !SURFACE_KEY_PATTERN.test(surface)) {
+        return envelopeFailure(`\`surface\` must be a surface key (lowercase, starting alphanumeric, kebab/dot/colon/underscore) — got ${JSON.stringify(surface ?? null)}`);
+    }
+    if (!Array.isArray(input.sections)) {
+        return envelopeFailure("`sections` must be an array of component instances");
+    }
+    const issues = [];
+    const seenIds = new Set();
+    const sections = [];
+    input.sections.forEach((raw, index) => {
+        const instance = sanitizeInstance(raw, `sections[${index}]`, seenIds, issues);
+        if (instance !== null) {
+            sections.push(instance);
+        }
+    });
+    // The envelope is forward-compatible: unknown top-level keys are
+    // carried through verbatim so a later writer can record metadata without a
+    // `version` bump. `PageData` deliberately does not declare them — see its
+    // doc comment. `__proto__` is never carried: a document names data, it cannot
+    // name a prototype.
+    const page = { version: 1, surface, sections };
+    for (const key of Object.keys(input)) {
+        if (key === "version" || key === "surface" || key === "sections")
+            continue;
+        if (key === "__proto__")
+            continue;
+        page[key] = input[key];
+    }
+    return { page, issues };
+}
+/**
+ * Catalog conformance on top of the parse: unknown types, props and slots are
+ * reported (`resolveInstance` decides the same degradations the renderer will
+ * apply). Read-only.
+ */
+export function validatePageData(theme, input, scope = {}) {
+    const parsed = parsePageData(input);
+    if (parsed.page === null) {
+        return parsed;
+    }
+    const issues = [...parsed.issues];
+    const walk = (instance, path) => {
+        const definition = Object.hasOwn(theme.components, instance.type)
+            ? theme.components[instance.type]
+            : undefined;
+        if (definition === undefined) {
+            issues.push({
+                path: `${path}.type`,
+                code: "unknown-type",
+                message: `"${instance.type}" is not in the theme catalog; this instance renders nothing`,
+            });
+            return;
+        }
+        const resolved = resolveInstance(definition, instance, scope);
+        for (const issue of resolved.issues) {
+            issues.push({ ...issue, path: `${path}.${issue.path}` });
+        }
+        resolved.children.forEach((child, index) => {
+            walk(child, `${path}.children[${index}]`);
+        });
+        for (const [name, list] of Object.entries(resolved.slots)) {
+            list.forEach((child, index) => {
+                walk(child, `${path}.slots.${name}[${index}]`);
+            });
+        }
+    };
+    parsed.page.sections.forEach((section, index) => {
+        walk(section, `sections[${index}]`);
+    });
+    return { page: parsed.page, issues };
+}
+function sanitizeInstance(raw, path, seenIds, issues) {
+    const parsed = ComponentInstanceSchema.safeParse(raw);
+    if (!parsed.success) {
+        const detail = parsed.error.issues[0]?.message ?? "invalid shape";
+        issues.push({
+            path,
+            code: "instance-dropped",
+            message: `instance failed structural validation: ${detail}`,
+        });
+        return null;
+    }
+    return pruneDuplicateIds(parsed.data, path, seenIds, issues);
+}
+/**
+ * Deterministic rebuild with duplicate ids pruned (depth-first, first wins).
+ * Property presence is preserved — a valid document round-trips unchanged;
+ * pruning to empty (all duplicates dropped) keeps the empty container.
+ */
+function pruneDuplicateIds(instance, path, seenIds, issues) {
+    if (seenIds.has(instance.id)) {
+        issues.push({
+            path: `${path}.id`,
+            code: "duplicate-id",
+            message: `duplicate instance id "${instance.id}"; the later instance is dropped`,
+        });
+        return null;
+    }
+    seenIds.add(instance.id);
+    const pruned = { id: instance.id, type: instance.type };
+    if (instance.props !== undefined) {
+        pruned.props = instance.props;
+    }
+    if (instance.children !== undefined) {
+        const children = [];
+        instance.children.forEach((child, index) => {
+            const sane = pruneDuplicateIds(child, `${path}.children[${index}]`, seenIds, issues);
+            if (sane !== null) {
+                children.push(sane);
+            }
+        });
+        pruned.children = children;
+    }
+    if (instance.slots !== undefined) {
+        const slots = {};
+        for (const [name, list] of Object.entries(instance.slots)) {
+            const saneList = [];
+            list.forEach((child, index) => {
+                const sane = pruneDuplicateIds(child, `${path}.slots.${name}[${index}]`, seenIds, issues);
+                if (sane !== null) {
+                    saneList.push(sane);
+                }
+            });
+            slots[name] = saneList;
+        }
+        pruned.slots = slots;
+    }
+    return pruned;
+}

package/dist/schemas.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Zod schemas for the persistence boundary — the only place runtime input is
+ * validated. Definitions are typechecked code; page data is parsed data.
+ */
+import { z } from "zod";
+import type { ComponentInstance, JsonValue } from "./types.js";
+/**
+ * A theme's key: lowercase kebab-case, at most 64 characters. The platform
+ * stores a merchant's text edits under it, so it is the theme's identity on the
+ * platform, and the server applies the same rule.
+ */
+export declare const THEME_KEY_PATTERN: RegExp;
+/** Type keys are lowercase kebab-case. */
+export declare const TYPE_KEY_PATTERN: RegExp;
+/**
+ * The page-document **surface** key — the address of a composed page
+ * (`home` today; `page:<slug>` / `lp:<slug>` are reserved conventions).
+ *
+ * The server applies the same pattern. Module-level on purpose: it is part of
+ * the persisted-data contract,
+ * not of the package's curated public surface (`src/index.ts`).
+ */
+export declare const SURFACE_KEY_PATTERN: RegExp;
+export declare function isLocaleTag(value: string): boolean;
+/**
+ * Whether `value` is a per-language map (`{ ar: "…", fr: "…" }`): a plain
+ * object with at least one entry, every key a locale tag, every value a string.
+ */
+export declare function isLocaleMap(value: unknown): value is Readonly<Record<string, string>>;
+/**
+ * Whether a `url` field value is safe to render as an `href`: a site path,
+ * fragment or query, or an `http(s)`, `mailto` or `tel` URL. Rejects
+ * `javascript:`/`data:` and every other scheme, protocol-relative `//host`,
+ * backslashes (browsers read `/\host` as `//host`), whitespace and control
+ * characters, and anything over 2048 characters.
+ */
+export declare function isSafeLinkTarget(value: string): boolean;
+export declare const JsonValueSchema: z.ZodType<JsonValue>;
+export declare const ComponentInstanceSchema: z.ZodType<ComponentInstance>;
+/**
+ * The envelope schema. **Loose on purpose**: unknown top-level keys
+ * survive `.parse`, matching `parsePageData` — a writer that records metadata
+ * must not have it stripped by whichever reader runs first.
+ */
+export declare const PageDataSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    surface: z.ZodString;
+    sections: z.ZodArray<z.ZodType<ComponentInstance, unknown, z.core.$ZodTypeInternals<ComponentInstance, unknown>>>;
+}, z.core.$loose>;