@pantheon-systems/p1-content-validator 2.1.2 → 2.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @pantheon-systems/p1-content-validator
 
-Validates Puck component edit operations against a Collaborative State System (CSS) component
+Validates Puck component edit operations against Pantheon's P1 component
 registry, so writes that don't match a component's registered prop shape are rejected before
 they reach a document.
 
@@ -25,7 +25,7 @@ const result = validateOps(ops, registry);
 
 Operations are checked against the registry entry for each component — unknown components,
 unknown props, and type mismatches are reported rather than silently written. This is the same
-validation the CSS backend applies to AI-assisted and API-driven edits.
+validation the backend applies to AI-assisted and API-driven edits.
 
 Also exported:
 

package/dist/authority-enforcement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authority-enforcement.d.ts","sourceRoot":"","sources":["../src/authority-enforcement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,mBAAmB,EACnB,iCAAiC,EAClC,MAAM,YAAY,CAAC;AAgCpB,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,iCAAiC,GACvC;IAAE,WAAW,EAAE,mBAAmB,EAAE,CAAA;CAAE,CA4ExC"}
+{"version":3,"file":"authority-enforcement.d.ts","sourceRoot":"","sources":["../src/authority-enforcement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,mBAAmB,EACnB,iCAAiC,EAClC,MAAM,YAAY,CAAC;AAgDpB,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,iCAAiC,GACvC;IAAE,WAAW,EAAE,mBAAmB,EAAE,CAAA;CAAE,CA4ExC"}

package/dist/authority-enforcement.js

@@ -1,35 +1,22 @@
-import { isAuthority, resolveSlotAuthority } from './localization.js';
+import { isAuthority, resolveSlotAuthority, ROOT_SLOT_ID } from './localization.js';
 import { isPlainObject, resolvePropPath } from './guards.js';
-/**
- * Authority enforcement for writes against a translation document.
- *
- * A translation owns its `locale`-authority props and inherits its
- * `canonical`-authority props from the canonical it derives from. Writing a
- * `canonical`-authority prop outside the sync/reconcile workflow is reported as a
- * diagnostic at the caller's severity, never rejected here.
- *
- * This module is pure: the caller resolves the template snapshot and the
- * localization edge's per-prop overrides and passes them in.
- */
-/**
- * Resolves the component a prop-path op targets and returns its slot id, or
- * `undefined` when the path does not target a prop on a resolvable component.
- * Authority is keyed by slot id, so a component without one is not judged.
- */
 function resolveSlot(path, snapshot) {
+    const parts = path.split('.');
+    if (parts[0] === 'root' && parts.lastIndexOf('props') === 1) {
+        return { slotId: ROOT_SLOT_ID, propsIdx: 1, parts };
+    }
     const resolved = resolvePropPath(path, snapshot);
     if (resolved === undefined || typeof resolved.component.props.id !== 'string') {
         return undefined;
     }
     return { slotId: resolved.component.props.id, propsIdx: resolved.propsIdx, parts: resolved.parts };
 }
+function isContentProp(propName) {
+    return propName !== 'id' && !propName.startsWith('_');
+}
 export function validateTranslationAuthority(input) {
     const { operations, currentSnapshot, templateSnapshot, authorityOverrides = {}, slotAuthority = {}, severity = 'warning', } = input;
     const diagnostics = [];
-    // Slot ids and prop names are caller-chosen keys arriving as parsed JSON, so both
-    // maps are read through a Map: a missing key stays missing instead of resolving to
-    // an Object.prototype member. A stored value that is not an authority is dropped,
-    // leaving its prop on `canonical`.
     const overrides = new Map(Object.entries(authorityOverrides).map(([slotId, props]) => [
         slotId,
         new Map(Object.entries(props).filter(([, value]) => isAuthority(value))),
@@ -60,12 +47,11 @@ export function validateTranslationAuthority(input) {
         if (resolved === undefined)
             return;
         const { slotId, propsIdx, parts } = resolved;
-        // Case A: the path ends at `.props` — the content is the whole props object.
         if (propsIdx === parts.length - 1) {
             if (!isPlainObject(op.content))
                 return;
             for (const propName of Object.keys(op.content)) {
-                if (propName === 'id')
+                if (!isContentProp(propName))
                     continue;
                 if (effectiveAuthority(slotId, propName) === 'canonical') {
                     flag(opIndex, `${op.path}.${propName}`, slotId, propName);
@@ -73,9 +59,8 @@ export function validateTranslationAuthority(input) {
             }
             return;
         }
-        // Case B: the path targets a single prop — `.props.<name>`.
         const propName = parts[propsIdx + 1];
-        if (propName === 'id')
+        if (!isContentProp(propName))
             return;
         if (effectiveAuthority(slotId, propName) === 'canonical') {
             flag(opIndex, op.path, slotId, propName);

package/dist/guards.js

@@ -1,20 +1,9 @@
-/**
- * Shape guards and path reads shared by the validators. Every entry point takes
- * `unknown` — snapshots, templates, and operations all arrive as parsed JSON.
- */
-/** Whether a value is a non-null, non-array object. */
 export function isPlainObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-/** Whether a value has the shape of a component: a string `type` and a props object. */
 export function isComponentShape(value) {
     return isPlainObject(value) && typeof value.type === 'string' && isPlainObject(value.props);
 }
-/**
- * Reads the value at a dot-notation path (`content.0.props.title`), treating a
- * numeric segment as an array index. An empty path reads the root. Resolves to
- * undefined when a segment is absent or the path runs into a non-object.
- */
 export function getAtPath(obj, path) {
     if (path === '')
         return obj;
@@ -30,20 +19,9 @@ export function getAtPath(obj, path) {
         return cur[key];
     }, obj);
 }
-/**
- * Resolves the component whose prop a path writes to.
- *
- * Components nest through their slot props, so a path can carry several `props`
- * segments (`content.0.props.items.1.props.title`). The last one belongs to the
- * component being written; the earlier ones are its ancestors.
- *
- * Resolves to undefined when the path names no component before its props, or when
- * the snapshot holds something other than a component there.
- */
 export function resolvePropPath(path, snapshot) {
     const parts = path.split('.');
     const propsIdx = parts.lastIndexOf('props');
-    // A prop write has at least one segment before 'props' (the component path).
     if (propsIdx <= 0) {
         return undefined;
     }

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { validateOps } from './validator.js';
 export { fetchRegistry, listRegistryVersions, snapshotToComponentSchema, registryComponentKey, componentNameFromPath, } from './registry.js';
 export { validateDocumentStructure } from './structure-validator.js';
 export { validateTranslationAuthority } from './authority-enforcement.js';
-export { resolveTranslatable, resolveSlotAuthority, resolveSlotAuthorityMap, isAuthority, AUTHORITIES, DEFAULT_AUTHORITY, } from './localization.js';
+export { resolveTranslatable, resolveSlotAuthority, resolveSlotAuthorityMap, isAuthority, AUTHORITIES, DEFAULT_AUTHORITY, ROOT_SLOT_ID, } from './localization.js';
 export type { EditOperation, Authority, ComponentSchema, ComponentField, FieldOption, ValidationError, ValidateInput, FetchRegistryOpts, TemplateComponent, TemplateSnapshot, StructuralConformanceError, ValidateStructureInput, AuthoritySeverity, AuthorityOverrideMap, AuthorityDiagnostic, ValidateTranslationAuthorityInput, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,WAAW,EACX,WAAW,EACX,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,aAAa,EACb,SAAS,EACT,eAAe,EACf,cAAc,EACd,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,0BAA0B,EAC1B,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,iCAAiC,GAClC,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,aAAa,EACb,SAAS,EACT,eAAe,EACf,cAAc,EACd,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,0BAA0B,EAC1B,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,iCAAiC,GAClC,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -2,4 +2,4 @@ export { validateOps } from './validator.js';
 export { fetchRegistry, listRegistryVersions, snapshotToComponentSchema, registryComponentKey, componentNameFromPath, } from './registry.js';
 export { validateDocumentStructure } from './structure-validator.js';
 export { validateTranslationAuthority } from './authority-enforcement.js';
-export { resolveTranslatable, resolveSlotAuthority, resolveSlotAuthorityMap, isAuthority, AUTHORITIES, DEFAULT_AUTHORITY, } from './localization.js';
+export { resolveTranslatable, resolveSlotAuthority, resolveSlotAuthorityMap, isAuthority, AUTHORITIES, DEFAULT_AUTHORITY, ROOT_SLOT_ID, } from './localization.js';

package/dist/localization.d.ts

@@ -15,6 +15,11 @@ import type { Authority } from './types.js';
 export declare const AUTHORITIES: readonly ["canonical", "locale"];
 /** The authority a slot falls back to when the template declares none. */
 export declare const DEFAULT_AUTHORITY: Authority;
+/**
+ * The slot id root props are keyed by. Authority and translatability are keyed by
+ * the slot id of the component owning a prop; root props belong to no component.
+ */
+export declare const ROOT_SLOT_ID = "__root__";
 /** Whether a value is one of the two authorities. */
 export declare function isAuthority(value: unknown): value is Authority;
 /**

package/dist/localization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"localization.d.ts","sourceRoot":"","sources":["../src/localization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;;;;;;;;GAWG;AAEH,gDAAgD;AAChD,eAAO,MAAM,WAAW,kCAAmC,CAAC;AAE5D,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,EAAE,SAAuB,CAAC;AAExD,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAmBD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,OAAO,EACjB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAGzF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAM5F"}
+{"version":3,"file":"localization.d.ts","sourceRoot":"","sources":["../src/localization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;;;;;;;;GAWG;AAEH,gDAAgD;AAChD,eAAO,MAAM,WAAW,kCAAmC,CAAC;AAE5D,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,EAAE,SAAuB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,YAAY,aAAa,CAAC;AAEvC,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAmBD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,OAAO,EACjB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAGzF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAM5F"}

package/dist/localization.js

@@ -1,29 +1,10 @@
 import { isPlainObject } from './guards.js';
-/**
- * Localization resolvers — the single source of truth for two independent
- * properties of the localization model:
- *
- *  - `translatable`: whether a prop holds natural-language text a human would
- *    translate. A per-(slotId, propName) flag that defaults to true, stored once
- *    on the canonical page (it applies to every language variant) and resolved
- *    via `resolveTranslatable`.
- *  - `authority`: a property of the RELATIONSHIP between a translation and its
- *    canonical. The per-slot default is declared on the template's
- *    `_localeAuthority` map and resolved via `resolveSlotAuthority`.
- */
-/** Every authority a slot or prop can carry. */
 export const AUTHORITIES = ['canonical', 'locale'];
-/** The authority a slot falls back to when the template declares none. */
 export const DEFAULT_AUTHORITY = 'canonical';
-/** Whether a value is one of the two authorities. */
+export const ROOT_SLOT_ID = '__root__';
 export function isAuthority(value) {
     return AUTHORITIES.includes(value);
 }
-/**
- * Reads one of the localization config maps off a snapshot's `root.props`. Absent
- * maps and malformed snapshots read as an empty map, so a resolver's fallback is
- * the same whether the map is missing or the snapshot is not content-shaped.
- */
 function localeConfigMap(snapshot, key) {
     if (!isPlainObject(snapshot)) {
         return {};
@@ -35,14 +16,6 @@ function localeConfigMap(snapshot, key) {
     const map = root.props[key];
     return isPlainObject(map) ? map : {};
 }
-/**
- * Resolves whether a prop is translatable from the canonical page snapshot's
- * `root.props._localeTranslatable` map, keyed by slot id then prop name. The flag
- * applies to every language variant, so it lives on the canonical only. A prop is
- * translatable unless an entry is explicitly stored as `false`; absent entries,
- * absent maps, malformed snapshots, and non-boolean stored values all resolve to
- * true.
- */
 export function resolveTranslatable(snapshot, slotId, propName) {
     const slot = localeConfigMap(snapshot, '_localeTranslatable')[slotId];
     if (!isPlainObject(slot)) {
@@ -50,22 +23,10 @@ export function resolveTranslatable(snapshot, slotId, propName) {
     }
     return slot[propName] !== false;
 }
-/**
- * Resolves the per-slot authority default from a template snapshot's
- * `root.props._localeAuthority` map, keyed by slot id. Slots with no declared
- * authority, absent maps, malformed snapshots, and unrecognized stored values
- * all resolve to `canonical`.
- */
 export function resolveSlotAuthority(templateSnapshot, slotId) {
     const value = localeConfigMap(templateSnapshot, '_localeAuthority')[slotId];
     return isAuthority(value) ? value : DEFAULT_AUTHORITY;
 }
-/**
- * Resolves a template's whole `root.props._localeAuthority` map, keyed by slot id.
- * Slots storing an unrecognized value are omitted, so a slot present in the result
- * carries a declared authority and a slot absent from it falls back to
- * `DEFAULT_AUTHORITY`. Absent maps and malformed snapshots resolve to no slots.
- */
 export function resolveSlotAuthorityMap(templateSnapshot) {
     return Object.fromEntries(Object.entries(localeConfigMap(templateSnapshot, '_localeAuthority')).filter((entry) => isAuthority(entry[1])));
 }

package/dist/registry.d.ts

@@ -23,26 +23,26 @@ export declare function componentNameFromPath(path: string): string;
  */
 export declare function snapshotToComponentSchema(snapshot: Record<string, unknown>): ComponentSchema | null;
 /**
- * Fetch and cache all component schemas from the CSS registry.
+ * Fetch and cache all component schemas from the 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.
+ * Results are cached per (ccrBaseUrl, 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>>;
+export declare function fetchRegistry(ccrBaseUrl: 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
+ * Note: the 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<{
+export declare function listRegistryVersions(ccrBaseUrl: string, siteId: string, branchId: string, opts: FetchRegistryOpts): Promise<{
     name: string;
     versionId: string;
 }[]>;

package/dist/registry.js

@@ -1,49 +1,10 @@
-// ---------------------------------------------------------------------------
-// Registry key normalization
-//
-// Document paths (including "_registry/components/{Name}") are lowercased
-// server-side on write (see workers/src/services/document-types.ts
-// normalizePath), but the component's real, original-case name is preserved
-// in the descriptor snapshot body's own `name` field. Lookups against the
-// registry must therefore be case-insensitive, while the schema's `name`
-// (what's stored/displayed to callers) stays the true original case.
-//
-// Mirrors the `registryComponentKey` pattern established in p1-chatbot /
-// puck-css-integration#122 for the client-side registry — same name, same
-// approach, so both sides of the registry stay consistent.
-// ---------------------------------------------------------------------------
 export function registryComponentKey(name) {
     return name.toLowerCase();
 }
 const REGISTRY_COMPONENTS_PATH_PREFIX = '_registry/components/';
-/**
- * Derives a component's fallback name from its registry document path
- * (e.g. "_registry/components/leadcapture" -> "leadcapture"). This is a
- * fallback only — paths are lowercased server-side, so the result does not
- * reflect the component's real casing (e.g. "LeadCapture"). The descriptor
- * snapshot's own `name` field (see `snapshotToComponentSchema`) is the
- * source of truth for the real, original-case name.
- */
 export function componentNameFromPath(path) {
     return path.slice(REGISTRY_COMPONENTS_PATH_PREFIX.length);
 }
-// ---------------------------------------------------------------------------
-// Shared snapshot → ComponentSchema transformation
-// Used by both fetchRegistry (raw fetch path) and McpApiClient.fetchRegistrySchemas
-// (circuit-breaker-wrapped path) to ensure consistent extraction logic.
-// ---------------------------------------------------------------------------
-/**
- * Returns null when the descriptor carries no usable `name`.
- *
- * There used to be a fallback to the path-derived name here. A document path
- * cannot carry a component's casing reliably, so that fallback invented one and
- * advertised it as a valid component type — teaching every consumer (and every
- * agent calling list_components) a casing Puck may not resolve. A descriptor
- * with no `name` is corrupt; callers must skip and log it rather than guess.
- *
- * This holds however paths are stored: the descriptor body is the source of
- * truth for casing, so the path is never the place to recover it from.
- */
 export function snapshotToComponentSchema(snapshot) {
     if (typeof snapshot.name !== 'string' || snapshot.name === '') {
         return null;
@@ -63,30 +24,17 @@ export function snapshotToComponentSchema(snapshot) {
     };
 }
 const cache = new Map();
-const TTL_MS = 5 * 60 * 1000; // 5 minutes
-function cacheKey(cssBaseUrl, siteId, branchId) {
-    return `${cssBaseUrl}:${siteId}:${branchId}`;
+const TTL_MS = 5 * 60 * 1000;
+function cacheKey(ccrBaseUrl, siteId, branchId) {
+    return `${ccrBaseUrl}:${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);
+export async function fetchRegistry(ccrBaseUrl, siteId, branchId, opts) {
+    const key = cacheKey(ccrBaseUrl, siteId, branchId);
     const cached = cache.get(key);
     if (cached !== undefined && Date.now() - cached.cachedAt < TTL_MS) {
         return cached.schemas;
     }
-    const base = cssBaseUrl.replace(/\/$/, '');
+    const base = ccrBaseUrl.replace(/\/$/, '');
     const headers = {
         'Content-Type': 'application/json',
         'X-API-Key': opts.token,
@@ -99,7 +47,6 @@ export async function fetchRegistry(cssBaseUrl, siteId, branchId, opts) {
     }
     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 {};
     }
@@ -121,23 +68,13 @@ export async function fetchRegistry(cssBaseUrl, siteId, branchId, opts) {
             schemas[registryComponentKey(schema.name)] = schema;
         }
         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(/\/$/, '');
+export async function listRegistryVersions(ccrBaseUrl, siteId, branchId, opts) {
+    const base = ccrBaseUrl.replace(/\/$/, '');
     const headers = {
         'Content-Type': 'application/json',
         'X-API-Key': opts.token,
@@ -151,6 +88,6 @@ export async function listRegistryVersions(cssBaseUrl, siteId, branchId, opts) {
     const { documents } = (await res.json());
     return documents.map((doc) => ({
         name: componentNameFromPath(doc.path),
-        versionId: doc.id, // document id as proxy until backend exposes versionId
+        versionId: doc.id,
     }));
 }

package/dist/structure-validator.js

@@ -35,7 +35,6 @@ function pinMapOf(template) {
     }
     return isPlainObject(props._pinMap) ? props._pinMap : {};
 }
-// A pinned slot is a component with a string props.id whose _pinMap entry is strictly true.
 function pinnedSlots(list, pinMap) {
     const slots = [];
     for (const component of list) {
@@ -46,7 +45,6 @@ function pinnedSlots(list, pinMap) {
     }
     return slots;
 }
-// Document content is the top-level content[]; when absent it falls back to root.props.content.
 function documentContentOf(documentSnapshot) {
     if (!isPlainObject(documentSnapshot)) {
         return [];
@@ -80,8 +78,6 @@ function indexOfId(list, id) {
     }
     return -1;
 }
-// Within one list, pinned slots must keep their template-relative order. A slot absent
-// from this document list (present elsewhere or missing) neither errors nor advances the chain.
 function checkListOrder(slots, documentList, errors) {
     let lastFoundIndex = -1;
     slots.forEach((slot, expectedIndex) => {
@@ -103,39 +99,10 @@ function checkListOrder(slots, documentList, errors) {
         lastFoundIndex = actualIndex;
     });
 }
-/**
- * Validates a document snapshot against a content-shaped template by slot-id membership.
- *
- * A template component is a pinned slot when it has a string `props.id` and
- * `root.props._pinMap[id]` is strictly `true`. Slots are read from the template's
- * `content[]` and each `zones[key][]`. A document conforms when:
- *
- * 1. Presence: every pinned slot id appears among the document's component ids,
- *    collected from the top-level `content[]` (or `root.props.content` when the
- *    top-level array is absent) and every `zones[key][]`.
- * 2. Order: within each list, the pinned slots found in that list keep the template's
- *    relative order. A pinned slot found in a different list than the template placed it
- *    in raises no order error and does not advance that list's order chain.
- *
- * Matching is by id, so a same-typed local component never satisfies a pinned slot and a
- * duplicated type cannot mask a missing one. A template that is not a content-shaped
- * snapshot (missing `content` array, malformed `root`/`_pinMap`, or the legacy
- * `{ components }` manifest) pins nothing, and every document conforms.
- *
- * Never throws: every property access is type-guarded, and malformed input yields an
- * empty error list rather than an exception.
- *
- * @param input - Document snapshot and the template snapshot to validate against
- * @returns Object with an array of structural conformance errors (empty when valid)
- */
 export function validateDocumentStructure(input) {
     const { documentSnapshot, templateSnapshot } = input;
     const errors = [];
-    // Only a content-shaped snapshot pins slots; anything else conforms unconditionally.
     if (!isPlainObject(templateSnapshot) || !Array.isArray(templateSnapshot.content)) {
-        // A template bound to live documents that is not content-shaped disables
-        // structural validation for all of them; surface it so operators can catch
-        // a broken template deployment rather than have every document silently pass.
         console.warn('[p1-content-validator] Template snapshot is not content-shaped; skipping structural validation and treating the document as conforming.');
         return { errors };
     }

package/dist/validator.js

@@ -1,13 +1,7 @@
 import { registryComponentKey } from './registry.js';
 import { isComponentShape, resolvePropPath } from './guards.js';
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-// 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 === '')
@@ -22,21 +16,15 @@ function allowedPropsForSchema(schema) {
         ...(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);
@@ -51,7 +39,6 @@ function validateEnumValue(field, value, componentType, propKey, opIndex, path,
     }
 }
 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,
@@ -60,9 +47,6 @@ function validateComponent(comp, registry, opIndex, path, errors, zonesKey, warn
             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,
@@ -90,27 +74,6 @@ function validateComponent(comp, registry, opIndex, path, errors, zonesKey, warn
         });
         return;
     }
-    // The descriptor's own `name` is the source of truth for a component type's
-    // casing. The lookup above is case-insensitive on purpose, and must stay that
-    // way: it is how a mis-cased type gets *found* so the error below can name the
-    // casing the writer should have used. Making it exact would degrade this into
-    // a bare unknown_component_type and lose the actionable hint.
-    //
-    // Matching loosely is not licence to write loosely. Puck resolves `type` by
-    // exact key lookup into config.components with no normalisation and no guard
-    // (verified in @puckeditor/core@0.21.1 — chunk-EBISZQTK.mjs:4124 reads
-    // `config.components[item.type]` then dereferences `.fields` unguarded, so a
-    // miss throws), which means a document holding "quoteblock" against a config
-    // keyed "QuoteBlock" breaks the editor and the published page even though
-    // every prop on it validated fine.
-    //
-    // Reject rather than silently canonicalise: a writer that meant a different
-    // component should hear about it, and naming the expected casing makes the fix
-    // mechanical.
-    //
-    // `schema.name` is required for in-repo callers but validateOps is a public
-    // boundary — a hand-built registry may omit it, and there is no canonical
-    // casing to hold the writer to in that case.
     if (typeof schema.name === 'string' && schema.name !== '' && comp.type !== schema.name) {
         errors.push({
             opIndex,
@@ -131,15 +94,13 @@ function validateComponent(comp, registry, opIndex, path, errors, zonesKey, warn
                 message: `Unknown prop "${key}" on "${comp.type}" at "${path}.props". ` +
                     `Allowed: ${[...allowedKeys].join(', ')}.`,
             });
-            continue; // no point checking value if key is invalid
+            continue;
         }
-        // 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')
@@ -162,7 +123,6 @@ function validateContent(value, registry, opIndex, path, errors, zonesKey, warnO
         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) {
@@ -176,13 +136,6 @@ function validateContent(value, registry, opIndex, path, errors, zonesKey, warnO
         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 resolved = resolvePropPath(op.path, snapshot);
     if (resolved === undefined)
@@ -190,15 +143,7 @@ function validatePropPathOp(op, opIndex, snapshot, registry, errors) {
     const { component: val, componentPath, propsIdx, parts } = resolved;
     const schema = registry[registryComponentKey(val.type)];
     if (!schema)
-        return; // unknown type — caught elsewhere when the component is replaced
-    // Deliberately no case-mismatch check here: `val.type` is read from the
-    // stored snapshot, not from this op. A mis-cased type in the document is
-    // damage some earlier write already did, and erroring on it would make the
-    // document unrepairable — the prop edits that fix it would themselves be
-    // rejected. Casing is enforced where a type actually enters the document
-    // (validateComponent).
-    // Case A: path ends exactly at .props — content is the full props object
-    // e.g. replace content.0.props { id, label, visible }
+        return;
     if (propsIdx === parts.length - 1) {
         if (op.content === null || typeof op.content !== 'object' || Array.isArray(op.content))
             return;
@@ -241,10 +186,7 @@ function validatePropPathOp(op, opIndex, snapshot, registry, 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({
@@ -272,21 +214,11 @@ function validatePropPathOp(op, opIndex, snapshot, registry, errors) {
         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: [] };
     }
-    // Defense-in-depth: re-key the registry by its case-insensitive lookup key,
-    // regardless of what casing the caller's keys already use. Registry
-    // producers (fetchRegistry / McpApiClient.fetchRegistrySchemas) already key
-    // by registryComponentKey, but validateOps normalizes independently so a
-    // caller-supplied registry (e.g. a hand-built one, or one that changes its
-    // convention later) can't silently reintroduce case-sensitive misses.
     const normalizedRegistry = {};
     for (const [key, schema] of Object.entries(registry)) {
         normalizedRegistry[registryComponentKey(key)] = schema;
@@ -317,12 +249,9 @@ export function validateOps(input) {
                 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, normalizedRegistry, errors);
         }
-        // Content-shape validation: catches component replacements and slot content.
         validateContent(op.content, normalizedRegistry, opIndex, op.path, errors, zonesKey, warnOnZonesUsage);
     }
     return { errors };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pantheon-systems/p1-content-validator",
-  "version": "2.1.2",
-  "description": "Validates Puck component edit operations against the CSS component registry",
+  "version": "2.2.0",
+  "description": "Validates Puck component edit operations against the P1 component registry",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pantheon-systems/p1-platform.git",
@@ -36,7 +36,7 @@
   "license": "UNLICENSED",
   "homepage": "https://github.com/pantheon-systems/p1-platform/tree/main/packages/p1-content-validator",
   "scripts": {
-    "build": "tsc",
+    "build": "pnpm run clean && tsc --emitDeclarationOnly && tsc --declaration false --declarationMap false --removeComments",
     "clean": "rm -rf dist *.tsbuildinfo",
     "lint": "eslint src tests",
     "lint:fix": "eslint src tests --fix",