@pantheon-systems/p1-content-validator 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { validateOps } from './validator.js';
+export { fetchRegistry, listRegistryVersions, snapshotToComponentSchema } from './registry.js';
+export type { EditOperation, ComponentSchema, ComponentField, FieldOption, ValidationError, ValidateInput, FetchRegistryOpts, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC/F,YAAY,EACV,aAAa,EACb,eAAe,EACf,cAAc,EACd,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { validateOps } from './validator.js';
+export { fetchRegistry, listRegistryVersions, snapshotToComponentSchema } from './registry.js';

package/dist/registry.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentSchema, FetchRegistryOpts } from './types.js';
+export declare function snapshotToComponentSchema(name: string, snapshot: Record<string, unknown>): ComponentSchema;
+/**
+ * Fetch and cache all component schemas from the CSS registry.
+ *
+ * Makes two types of requests:
+ *   1. GET /api/sites/{siteId}/branches/{branchId}/documents?pathPrefix=_registry%2Fcomponents%2F
+ *   2. GET .../versions/latest  for each component document
+ *
+ * Results are cached per (cssBaseUrl, siteId, branchId) with a 5-minute TTL.
+ * If the cache is fresh, no network calls are made.
+ */
+export declare function fetchRegistry(cssBaseUrl: string, siteId: string, branchId: string, opts: FetchRegistryOpts): Promise<Record<string, ComponentSchema>>;
+/**
+ * Metadata-only listing: returns one entry per component with its document ID.
+ * Useful for cache invalidation checks — compare IDs against a local cache
+ * to detect which component schemas have been updated without fetching bodies.
+ *
+ * Note: the CSS list endpoint does not currently expose versionId; the document
+ * id is returned as a stable identifier. Full version-id tracking requires a
+ * backend extension (tracked separately).
+ */
+export declare function listRegistryVersions(cssBaseUrl: string, siteId: string, branchId: string, opts: FetchRegistryOpts): Promise<{
+    name: string;
+    versionId: string;
+}[]>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAkB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAQrF,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,eAAe,CAcjB;AAsBD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAoD1C;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAwBhD"}

package/dist/registry.js

@@ -0,0 +1,106 @@
+// ---------------------------------------------------------------------------
+// Shared snapshot → ComponentSchema transformation
+// Used by both fetchRegistry (raw fetch path) and McpApiClient.fetchRegistrySchemas
+// (circuit-breaker-wrapped path) to ensure consistent extraction logic.
+// ---------------------------------------------------------------------------
+export function snapshotToComponentSchema(name, snapshot) {
+    return {
+        name,
+        defaultProps: snapshot.defaultProps ?? {},
+        allowedAdditionalProps: Array.isArray(snapshot.allowedAdditionalProps)
+            ? snapshot.allowedAdditionalProps
+            : undefined,
+        opaqueProps: Array.isArray(snapshot.opaqueProps)
+            ? snapshot.opaqueProps
+            : undefined,
+        fields: Array.isArray(snapshot.fields)
+            ? snapshot.fields
+            : undefined,
+    };
+}
+const cache = new Map();
+const TTL_MS = 5 * 60 * 1000; // 5 minutes
+function cacheKey(cssBaseUrl, siteId, branchId) {
+    return `${cssBaseUrl}:${siteId}:${branchId}`;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Fetch and cache all component schemas from the CSS registry.
+ *
+ * Makes two types of requests:
+ *   1. GET /api/sites/{siteId}/branches/{branchId}/documents?pathPrefix=_registry%2Fcomponents%2F
+ *   2. GET .../versions/latest  for each component document
+ *
+ * Results are cached per (cssBaseUrl, siteId, branchId) with a 5-minute TTL.
+ * If the cache is fresh, no network calls are made.
+ */
+export async function fetchRegistry(cssBaseUrl, siteId, branchId, opts) {
+    const key = cacheKey(cssBaseUrl, siteId, branchId);
+    const cached = cache.get(key);
+    if (cached !== undefined && Date.now() - cached.cachedAt < TTL_MS) {
+        return cached.schemas;
+    }
+    const base = cssBaseUrl.replace(/\/$/, '');
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-API-Key': opts.token,
+    };
+    const listUrl = `${base}/api/sites/${siteId}/branches/${branchId}/documents` +
+        `?pathPrefix=${encodeURIComponent('_registry/components/')}`;
+    const listRes = await fetch(listUrl, { method: 'GET', headers, signal: opts.signal });
+    if (!listRes.ok) {
+        throw new Error(`fetchRegistry: list failed with ${String(listRes.status)}`);
+    }
+    const { documents } = (await listRes.json());
+    if (documents.length === 0) {
+        // Cache the empty result so we don't re-hit listDocuments on every call within the TTL
+        cache.set(key, { cachedAt: Date.now(), schemas: {} });
+        return {};
+    }
+    const schemas = {};
+    await Promise.all(documents.map(async (doc) => {
+        const name = doc.path.slice('_registry/components/'.length);
+        const versionUrl = `${base}/api/sites/${siteId}/branches/${branchId}/documents/${doc.id}/versions/latest`;
+        try {
+            const vRes = await fetch(versionUrl, { method: 'GET', headers, signal: opts.signal });
+            if (!vRes.ok)
+                return;
+            const { snapshot } = (await vRes.json());
+            schemas[name] = snapshotToComponentSchema(name, snapshot);
+        }
+        catch {
+            // Skip components that fail to fetch — don't block the rest
+        }
+    }));
+    cache.set(key, { cachedAt: Date.now(), schemas });
+    return schemas;
+}
+/**
+ * Metadata-only listing: returns one entry per component with its document ID.
+ * Useful for cache invalidation checks — compare IDs against a local cache
+ * to detect which component schemas have been updated without fetching bodies.
+ *
+ * Note: the CSS list endpoint does not currently expose versionId; the document
+ * id is returned as a stable identifier. Full version-id tracking requires a
+ * backend extension (tracked separately).
+ */
+export async function listRegistryVersions(cssBaseUrl, siteId, branchId, opts) {
+    const base = cssBaseUrl.replace(/\/$/, '');
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-API-Key': opts.token,
+    };
+    const listUrl = `${base}/api/sites/${siteId}/branches/${branchId}/documents` +
+        `?pathPrefix=${encodeURIComponent('_registry/components/')}`;
+    const res = await fetch(listUrl, { method: 'GET', headers, signal: opts.signal });
+    if (!res.ok) {
+        throw new Error(`listRegistryVersions: list failed with ${String(res.status)}`);
+    }
+    const { documents } = (await res.json());
+    return documents.map((doc) => ({
+        name: doc.path.slice('_registry/components/'.length),
+        versionId: doc.id, // document id as proxy until backend exposes versionId
+    }));
+}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export interface EditOperation {
+    type: 'add' | 'remove' | 'replace' | 'move' | 'reorder';
+    path: string;
+    content?: unknown;
+    index?: number;
+    fromIndex?: number;
+    toIndex?: number;
+}
+export interface FieldOption {
+    label: string;
+    value: string | number | boolean;
+}
+export interface ComponentField {
+    name: string;
+    type: string;
+    options?: FieldOption[];
+}
+export interface ComponentSchema {
+    name: string;
+    defaultProps: Record<string, unknown>;
+    allowedAdditionalProps?: string[];
+    opaqueProps?: string[];
+    /** Field definitions from the registry, used for enum value validation. */
+    fields?: ComponentField[];
+}
+export interface ValidationError {
+    opIndex: number;
+    path: string;
+    code: 'unknown_component_type' | 'invalid_prop_key' | 'invalid_prop_value' | 'missing_required_prop' | 'invalid_readonly_key' | 'deprecated_zones_usage';
+    message: string;
+}
+export interface FetchRegistryOpts {
+    token: string;
+    signal?: AbortSignal;
+}
+export interface ValidateInput {
+    operations: EditOperation[];
+    currentSnapshot?: Record<string, unknown>;
+    registry: Record<string, ComponentSchema>;
+    config?: {
+        rootKey?: string;
+        contentKey?: string;
+        zonesKey?: string;
+        warnOnZonesUsage?: boolean;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EACA,wBAAwB,GACxB,kBAAkB,GAClB,oBAAoB,GACpB,uBAAuB,GACvB,sBAAsB,GACtB,wBAAwB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC1C,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH"}

package/dist/types.js

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

package/dist/validator.d.ts

@@ -0,0 +1,5 @@
+import type { ValidateInput, ValidationError } from './types.js';
+export declare function validateOps(input: ValidateInput): {
+    errors: ValidationError[];
+};
+//# sourceMappingURL=validator.d.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,aAAa,EAAE,eAAe,EAAmC,MAAM,YAAY,CAAC;AAyUjH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG;IAAE,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAgD/E"}

package/dist/validator.js

@@ -0,0 +1,304 @@
+function isPuckComponentShape(v) {
+    return (v !== null &&
+        typeof v === 'object' &&
+        !Array.isArray(v) &&
+        typeof v.type === 'string' &&
+        typeof v.props === 'object' &&
+        v.props !== null);
+}
+function getAtPath(obj, path) {
+    if (path === '')
+        return obj;
+    return path.split('.').reduce((cur, key) => {
+        if (cur === null || cur === undefined)
+            return undefined;
+        if (Array.isArray(cur)) {
+            const idx = parseInt(key, 10);
+            return isNaN(idx) ? undefined : cur[idx];
+        }
+        return cur[key];
+    }, obj);
+}
+// UUID v4:             xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+// Puck type-prefixed:  {ComponentType}-{uuid-v4}
+const PREFIXED_UUID_RE = /^[A-Za-z][A-Za-z0-9]*-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+// ULID:                26 Crockford base32 chars (legacy — MCP server previously generated these)
+const ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+function isValidPuckId(value) {
+    if (typeof value !== 'string' || value === '')
+        return false;
+    return UUID_V4_RE.test(value) || PREFIXED_UUID_RE.test(value) || ULID_RE.test(value);
+}
+function allowedPropsForSchema(schema) {
+    return new Set([
+        'id',
+        ...Object.keys(schema.defaultProps),
+        ...(schema.fields?.map((f) => f.name) ?? []),
+        ...(schema.allowedAdditionalProps ?? []),
+    ]);
+}
+/** Returns the field definition for a prop key, or undefined if not found. */
+function findField(schema, propKey) {
+    return schema.fields?.find((f) => f.name === propKey);
+}
+/**
+ * Validates a prop value against a select/radio field's allowed options.
+ * Only fires when the field has options defined and the value is a string.
+ */
+function validateEnumValue(field, value, componentType, propKey, opIndex, path, errors) {
+    if ((field.type !== 'select' && field.type !== 'radio') ||
+        field.options === undefined ||
+        field.options.length === 0) {
+        return;
+    }
+    // Only validate primitives — skip array/object values (e.g. stats array items)
+    if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
+        return;
+    const allowedValues = field.options.map((o) => o.value);
+    if (!allowedValues.includes(value)) {
+        errors.push({
+            opIndex,
+            path,
+            code: 'invalid_prop_value',
+            message: `Invalid value ${JSON.stringify(value)} for ${field.type} prop "${propKey}" on "${componentType}". ` +
+                `Allowed values: ${allowedValues.map((v) => JSON.stringify(v)).join(', ')}.`,
+        });
+    }
+}
+function validateComponent(comp, registry, opIndex, path, errors, zonesKey, warnOnZonesUsage) {
+    // readOnly is a Puck runtime-managed sibling — writers must not set it
+    if ('readOnly' in comp) {
+        errors.push({
+            opIndex,
+            path: `${path}.readOnly`,
+            code: 'invalid_readonly_key',
+            message: `"readOnly" at "${path}" is a Puck runtime field and must not be set by writers.`,
+        });
+    }
+    // Every Puck component must have a valid id in its props — it is how the
+    // editor tracks the component instance. Accept UUID v4, type-prefixed UUID v4,
+    // or ULID; reject arbitrary strings like "roger".
+    if (!('id' in comp.props)) {
+        errors.push({
+            opIndex,
+            path: `${path}.props`,
+            code: 'missing_required_prop',
+            message: `Component "${comp.type}" at "${path}" is missing required prop "id". Every Puck component must have an id (UUID v4, {Type}-{uuid-v4}, or ULID).`,
+        });
+    }
+    else if (!isValidPuckId(comp.props.id)) {
+        errors.push({
+            opIndex,
+            path: `${path}.props.id`,
+            code: 'invalid_prop_value',
+            message: `Invalid id "${String(comp.props.id)}" on "${comp.type}" at "${path}". Must be UUID v4, type-prefixed UUID v4 (e.g. Hero-{uuid}), or ULID.`,
+        });
+    }
+    const schema = registry[comp.type];
+    if (!schema) {
+        errors.push({
+            opIndex,
+            path,
+            code: 'unknown_component_type',
+            message: `Unknown component type "${comp.type}" at "${path}". ` +
+                `Use list_components to see available types: ${Object.keys(registry).join(', ')}.`,
+        });
+        return;
+    }
+    const allowedKeys = allowedPropsForSchema(schema);
+    for (const [key, value] of Object.entries(comp.props)) {
+        if (!allowedKeys.has(key)) {
+            errors.push({
+                opIndex,
+                path: `${path}.props.${key}`,
+                code: 'invalid_prop_key',
+                message: `Unknown prop "${key}" on "${comp.type}" at "${path}.props". ` +
+                    `Allowed: ${[...allowedKeys].join(', ')}.`,
+            });
+            continue; // no point checking value if key is invalid
+        }
+        // Validate enum values for select/radio fields
+        const field = findField(schema, key);
+        if (field !== undefined) {
+            validateEnumValue(field, value, comp.type, key, opIndex, `${path}.props.${key}`, errors);
+        }
+    }
+    // Recurse into slot props: non-opaque array props containing component shapes
+    const opaqueProps = new Set(schema.opaqueProps ?? []);
+    for (const [key, val] of Object.entries(comp.props)) {
+        if (opaqueProps.has(key) || key === 'id')
+            continue;
+        if (Array.isArray(val) && val.some(isPuckComponentShape)) {
+            validateContent(val, registry, opIndex, `${path}.props.${key}`, errors, zonesKey, warnOnZonesUsage);
+        }
+    }
+}
+function validateContent(value, registry, opIndex, path, errors, zonesKey, warnOnZonesUsage) {
+    if (value === null || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => {
+            validateContent(item, registry, opIndex, `${path}.${i}`, errors, zonesKey, warnOnZonesUsage);
+        });
+        return;
+    }
+    if (isPuckComponentShape(value)) {
+        validateComponent(value, registry, opIndex, path, errors, zonesKey, warnOnZonesUsage);
+        return;
+    }
+    // Plain object (e.g., whole-document or sub-document): walk its keys
+    for (const [key, val] of Object.entries(value)) {
+        const childPath = path !== '' ? `${path}.${key}` : key;
+        if (warnOnZonesUsage && key === zonesKey) {
+            errors.push({
+                opIndex,
+                path: childPath,
+                code: 'deprecated_zones_usage',
+                message: `"${zonesKey}" is deprecated. Use slot props instead.`,
+            });
+        }
+        validateContent(val, registry, opIndex, childPath, errors, zonesKey, warnOnZonesUsage);
+    }
+}
+/**
+ * Validates a targeted prop write (e.g. content.2.props.background = "roger")
+ * using the current document snapshot to resolve the component type at the
+ * parent path. Checks both the prop key and the value against the registry schema.
+ *
+ * Only fires when the op path contains ".props." and a snapshot is available.
+ */
+function validatePropPathOp(op, opIndex, snapshot, registry, errors) {
+    const parts = op.path.split('.');
+    const propsIdx = parts.indexOf('props');
+    // Must have at least one segment before 'props'
+    if (propsIdx <= 0)
+        return;
+    // Resolve the component from the snapshot using the path prefix before 'props'
+    const componentPath = parts.slice(0, propsIdx).join('.');
+    const val = getAtPath(snapshot, componentPath);
+    if (!isPuckComponentShape(val))
+        return;
+    const schema = registry[val.type];
+    if (!schema)
+        return; // unknown type — caught elsewhere when the component is replaced
+    // Case A: path ends exactly at .props — content is the full props object
+    // e.g. replace content.0.props { id, label, visible }
+    if (propsIdx === parts.length - 1) {
+        if (op.content === null || typeof op.content !== 'object' || Array.isArray(op.content))
+            return;
+        const propsObj = op.content;
+        const allowedKeys = allowedPropsForSchema(schema);
+        if (!('id' in propsObj)) {
+            errors.push({
+                opIndex,
+                path: op.path,
+                code: 'missing_required_prop',
+                message: `Component "${val.type}" at "${componentPath}" is missing required prop "id".`,
+            });
+        }
+        else if (!isValidPuckId(propsObj.id)) {
+            errors.push({
+                opIndex,
+                path: `${op.path}.id`,
+                code: 'invalid_prop_value',
+                message: `Invalid id "${String(propsObj.id)}" at "${op.path}.id". Must be UUID v4, type-prefixed UUID v4, or ULID.`,
+            });
+        }
+        for (const [key, value] of Object.entries(propsObj)) {
+            if (key === 'id')
+                continue;
+            if (!allowedKeys.has(key)) {
+                errors.push({
+                    opIndex,
+                    path: `${op.path}.${key}`,
+                    code: 'invalid_prop_key',
+                    message: `Unknown prop "${key}" on "${val.type}" at "${op.path}". ` +
+                        `Allowed: ${[...allowedKeys].join(', ')}.`,
+                });
+            }
+            else {
+                const field = findField(schema, key);
+                if (field !== undefined) {
+                    validateEnumValue(field, value, val.type, key, opIndex, `${op.path}.${key}`, errors);
+                }
+            }
+        }
+        return;
+    }
+    // Case B: path goes through .props.KEY — targeted single-prop write
+    // e.g. replace content.0.props.background "roger"
+    const propKey = parts[propsIdx + 1];
+    // id is always an allowed key but validate its value format
+    if (propKey === 'id') {
+        if (!isValidPuckId(op.content)) {
+            errors.push({
+                opIndex,
+                path: op.path,
+                code: 'invalid_prop_value',
+                message: `Invalid id value "${String(op.content)}" at "${op.path}". Must be UUID v4, type-prefixed UUID v4, or ULID.`,
+            });
+        }
+        return;
+    }
+    const allowedKeys = allowedPropsForSchema(schema);
+    if (!allowedKeys.has(propKey)) {
+        errors.push({
+            opIndex,
+            path: op.path,
+            code: 'invalid_prop_key',
+            message: `Unknown prop "${propKey}" on "${val.type}" at "${componentPath}.props". ` +
+                `Allowed: ${[...allowedKeys].join(', ')}.`,
+        });
+        return;
+    }
+    const field = findField(schema, propKey);
+    if (field !== undefined) {
+        validateEnumValue(field, op.content, val.type, propKey, opIndex, op.path, errors);
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function validateOps(input) {
+    const { operations, registry, currentSnapshot, config = {} } = input;
+    // Graceful degradation: if registry is empty skip all validation.
+    if (Object.keys(registry).length === 0) {
+        return { errors: [] };
+    }
+    const zonesKey = config.zonesKey ?? 'zones';
+    const warnOnZonesUsage = config.warnOnZonesUsage ?? true;
+    const errors = [];
+    for (let opIndex = 0; opIndex < operations.length; opIndex++) {
+        const op = operations[opIndex];
+        if (op.type !== 'add' && op.type !== 'replace')
+            continue;
+        if (op.content === undefined)
+            continue;
+        if (op.path.split('.').includes('readOnly')) {
+            errors.push({
+                opIndex,
+                path: op.path,
+                code: 'invalid_readonly_key',
+                message: `Path "${op.path}" targets "readOnly" which is a Puck runtime field and must not be written to.`,
+            });
+            continue;
+        }
+        if (warnOnZonesUsage && (op.path === zonesKey || op.path.startsWith(`${zonesKey}.`))) {
+            errors.push({
+                opIndex,
+                path: op.path,
+                code: 'deprecated_zones_usage',
+                message: `"${zonesKey}" is deprecated. Use slot props instead.`,
+            });
+        }
+        // Snapshot-based validation: catches targeted prop writes where the content
+        // is a primitive and the component type must be resolved from the live document.
+        if (currentSnapshot !== undefined) {
+            validatePropPathOp(op, opIndex, currentSnapshot, registry, errors);
+        }
+        // Content-shape validation: catches component replacements and slot content.
+        validateContent(op.content, registry, opIndex, op.path, errors, zonesKey, warnOnZonesUsage);
+    }
+    return { errors };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@pantheon-systems/p1-content-validator",
+  "version": "1.0.0",
+  "description": "Validates Puck component edit operations against the CSS component registry",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pantheon-systems/collaborative-state-system.git",
+    "directory": "packages/p1-content-validator"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "eslint": "^9.27.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@pantheon-systems/eslint-config": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests"
+  }
+}