@pantheon-systems/p1-content-validator 1.0.0 → 2.1.0

package/dist/authority-enforcement.d.ts

@@ -0,0 +1,5 @@
+import type { AuthorityDiagnostic, ValidateTranslationAuthorityInput } from './types.js';
+export declare function validateTranslationAuthority(input: ValidateTranslationAuthorityInput): {
+    diagnostics: AuthorityDiagnostic[];
+};
+//# sourceMappingURL=authority-enforcement.d.ts.map

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

@@ -0,0 +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"}

package/dist/authority-enforcement.js

@@ -0,0 +1,85 @@
+import { isAuthority, resolveSlotAuthority } 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 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 };
+}
+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))),
+    ]));
+    const slotDefaults = new Map(Object.entries(slotAuthority).filter((entry) => isAuthority(entry[1])));
+    const effectiveAuthority = (slotId, propName) => overrides.get(slotId)?.get(propName) ??
+        slotDefaults.get(slotId) ??
+        resolveSlotAuthority(templateSnapshot, slotId);
+    const flag = (opIndex, path, slotId, propName) => {
+        diagnostics.push({
+            opIndex,
+            path,
+            code: 'canonical_authority_write',
+            severity,
+            slotId,
+            propName,
+            authority: 'canonical',
+            message: `Write to canonical-authority prop "${propName}" on slot "${slotId}" of a translation. ` +
+                `This prop is owned by the canonical; edit it there and let sync propagate the value.`,
+        });
+    };
+    operations.forEach((op, opIndex) => {
+        if (op.type !== 'add' && op.type !== 'replace')
+            return;
+        if (op.content === undefined)
+            return;
+        const resolved = resolveSlot(op.path, currentSnapshot);
+        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')
+                    continue;
+                if (effectiveAuthority(slotId, propName) === 'canonical') {
+                    flag(opIndex, `${op.path}.${propName}`, slotId, propName);
+                }
+            }
+            return;
+        }
+        // Case B: the path targets a single prop — `.props.<name>`.
+        const propName = parts[propsIdx + 1];
+        if (propName === 'id')
+            return;
+        if (effectiveAuthority(slotId, propName) === 'canonical') {
+            flag(opIndex, op.path, slotId, propName);
+        }
+    });
+    return { diagnostics };
+}

package/dist/guards.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shape guards and path reads shared by the validators. Every entry point takes
+ * `unknown` — snapshots, templates, and operations all arrive as parsed JSON.
+ */
+/** A component in a content-shaped snapshot: a type and a props bag. */
+export interface ComponentShape {
+    type: string;
+    props: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Whether a value is a non-null, non-array object. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Whether a value has the shape of a component: a string `type` and a props object. */
+export declare function isComponentShape(value: unknown): value is ComponentShape;
+/**
+ * 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 declare function getAtPath(obj: unknown, path: string): unknown;
+/** The component a prop-path op targets, and where its props begin in the path. */
+export interface ResolvedPropPath {
+    component: ComponentShape;
+    componentPath: string;
+    propsIdx: number;
+    parts: string[];
+}
+/**
+ * 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 declare function resolvePropPath(path: string, snapshot: unknown): ResolvedPropPath | undefined;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,uDAAuD;AACvD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAW7D;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,cAAc,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAa7F"}

package/dist/guards.js

@@ -0,0 +1,56 @@
+/**
+ * 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;
+    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];
+        }
+        if (typeof cur !== 'object')
+            return undefined;
+        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;
+    }
+    const componentPath = parts.slice(0, propsIdx).join('.');
+    const component = getAtPath(snapshot, componentPath);
+    if (!isComponentShape(component)) {
+        return undefined;
+    }
+    return { component, componentPath, propsIdx, parts };
+}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export { validateOps } from './validator.js';
-export { fetchRegistry, listRegistryVersions, snapshotToComponentSchema } from './registry.js';
-export type { EditOperation, ComponentSchema, ComponentField, FieldOption, ValidationError, ValidateInput, FetchRegistryOpts, } from './types.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 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,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"}
+{"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"}

package/dist/index.js

@@ -1,2 +1,5 @@
 export { validateOps } from './validator.js';
-export { fetchRegistry, listRegistryVersions, snapshotToComponentSchema } from './registry.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';

package/dist/localization.d.ts

@@ -0,0 +1,43 @@
+import type { Authority } from './types.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 declare const AUTHORITIES: readonly ["canonical", "locale"];
+/** The authority a slot falls back to when the template declares none. */
+export declare const DEFAULT_AUTHORITY: Authority;
+/** Whether a value is one of the two authorities. */
+export declare function isAuthority(value: unknown): value is Authority;
+/**
+ * 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 declare function resolveTranslatable(snapshot: unknown, slotId: string, propName: string): boolean;
+/**
+ * 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 declare function resolveSlotAuthority(templateSnapshot: unknown, slotId: string): 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 declare function resolveSlotAuthorityMap(templateSnapshot: unknown): Record<string, Authority>;
+//# sourceMappingURL=localization.d.ts.map

package/dist/localization.d.ts.map

@@ -0,0 +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"}

package/dist/localization.js

@@ -0,0 +1,71 @@
+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 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 {};
+    }
+    const root = snapshot.root;
+    if (!isPlainObject(root) || !isPlainObject(root.props)) {
+        return {};
+    }
+    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)) {
+        return true;
+    }
+    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

@@ -1,5 +1,27 @@
 import type { ComponentSchema, FetchRegistryOpts } from './types.js';
-export declare function snapshotToComponentSchema(name: string, snapshot: Record<string, unknown>): ComponentSchema;
+export declare function registryComponentKey(name: string): string;
+/**
+ * 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 declare function componentNameFromPath(path: string): string;
+/**
+ * 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 declare function snapshotToComponentSchema(snapshot: Record<string, unknown>): ComponentSchema | null;
 /**
  * Fetch and cache all component schemas from the CSS registry.
  *

package/dist/registry.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAkB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAiBrF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAID;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,eAAe,GAAG,IAAI,CAiBxB;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,CA4D1C;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

@@ -1,11 +1,55 @@
 // ---------------------------------------------------------------------------
+// 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.
 // ---------------------------------------------------------------------------
-export function snapshotToComponentSchema(name, snapshot) {
+/**
+ * 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;
+    }
     return {
-        name,
+        name: snapshot.name,
         defaultProps: snapshot.defaultProps ?? {},
         allowedAdditionalProps: Array.isArray(snapshot.allowedAdditionalProps)
             ? snapshot.allowedAdditionalProps
@@ -61,14 +105,20 @@ export async function fetchRegistry(cssBaseUrl, siteId, branchId, opts) {
     }
     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);
+            const schema = snapshotToComponentSchema(snapshot);
+            if (schema === null) {
+                console.warn(`[p1-content-validator] Registry descriptor at "${doc.path}" has no "name" — ` +
+                    'skipping. Its component cannot be validated until the descriptor is rewritten ' +
+                    '(reopen the editor or rerun the registry sync).');
+                return;
+            }
+            schemas[registryComponentKey(schema.name)] = schema;
         }
         catch {
             // Skip components that fail to fetch — don't block the rest
@@ -100,7 +150,7 @@ export async function listRegistryVersions(cssBaseUrl, siteId, branchId, opts) {
     }
     const { documents } = (await res.json());
     return documents.map((doc) => ({
-        name: doc.path.slice('_registry/components/'.length),
+        name: componentNameFromPath(doc.path),
         versionId: doc.id, // document id as proxy until backend exposes versionId
     }));
 }

package/dist/structure-validator.d.ts

@@ -0,0 +1,30 @@
+import type { StructuralConformanceError, ValidateStructureInput } from './types.js';
+/**
+ * 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 declare function validateDocumentStructure(input: ValidateStructureInput): {
+    errors: StructuralConformanceError[];
+};
+//# sourceMappingURL=structure-validator.d.ts.map

package/dist/structure-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure-validator.d.ts","sourceRoot":"","sources":["../src/structure-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,sBAAsB,EACvB,MAAM,YAAY,CAAC;AA+HpB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,sBAAsB,GAC5B;IAAE,MAAM,EAAE,0BAA0B,EAAE,CAAA;CAAE,CAyD1C"}

package/dist/structure-validator.js

@@ -0,0 +1,177 @@
+import { isPlainObject } from './guards.js';
+function asComponentList(value) {
+    return Array.isArray(value) ? value : [];
+}
+function componentId(component) {
+    if (!isPlainObject(component)) {
+        return undefined;
+    }
+    const props = component.props;
+    if (!isPlainObject(props)) {
+        return undefined;
+    }
+    return typeof props.id === 'string' ? props.id : undefined;
+}
+function componentType(component) {
+    if (isPlainObject(component) && typeof component.type === 'string') {
+        return component.type;
+    }
+    return '';
+}
+function zonesOf(snapshot) {
+    if (!isPlainObject(snapshot)) {
+        return {};
+    }
+    return isPlainObject(snapshot.zones) ? snapshot.zones : {};
+}
+function pinMapOf(template) {
+    const root = template.root;
+    if (!isPlainObject(root)) {
+        return {};
+    }
+    const props = root.props;
+    if (!isPlainObject(props)) {
+        return {};
+    }
+    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) {
+        const id = componentId(component);
+        if (id !== undefined && pinMap[id] === true) {
+            slots.push({ id, type: componentType(component) });
+        }
+    }
+    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 [];
+    }
+    if (Array.isArray(documentSnapshot.content)) {
+        return documentSnapshot.content;
+    }
+    const root = documentSnapshot.root;
+    if (!isPlainObject(root)) {
+        return [];
+    }
+    const props = root.props;
+    if (!isPlainObject(props)) {
+        return [];
+    }
+    return asComponentList(props.content);
+}
+function collectIds(list, ids) {
+    for (const component of list) {
+        const id = componentId(component);
+        if (id !== undefined) {
+            ids.add(id);
+        }
+    }
+}
+function indexOfId(list, id) {
+    for (let i = 0; i < list.length; i++) {
+        if (componentId(list[i]) === id) {
+            return i;
+        }
+    }
+    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) => {
+        const actualIndex = indexOfId(documentList, slot.id);
+        if (actualIndex === -1) {
+            return;
+        }
+        if (actualIndex < lastFoundIndex) {
+            errors.push({
+                code: 'pinned_component_out_of_order',
+                componentType: slot.type,
+                expectedIndex,
+                actualIndex,
+                message: `Pinned component "${slot.type}" appears out of order. ` +
+                    `Expected after index ${lastFoundIndex} but found at index ${actualIndex}.`,
+            });
+            return;
+        }
+        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 };
+    }
+    const pinMap = pinMapOf(templateSnapshot);
+    const contentSlots = pinnedSlots(templateSnapshot.content, pinMap);
+    const templateZones = zonesOf(templateSnapshot);
+    const zoneSlots = [];
+    for (const key of Object.keys(templateZones)) {
+        zoneSlots.push({
+            key,
+            slots: pinnedSlots(asComponentList(templateZones[key]), pinMap),
+        });
+    }
+    const allSlots = [...contentSlots, ...zoneSlots.flatMap((zone) => zone.slots)];
+    if (allSlots.length === 0) {
+        return { errors };
+    }
+    const documentContent = documentContentOf(documentSnapshot);
+    const documentZones = zonesOf(documentSnapshot);
+    const documentIds = new Set();
+    collectIds(documentContent, documentIds);
+    for (const key of Object.keys(documentZones)) {
+        collectIds(asComponentList(documentZones[key]), documentIds);
+    }
+    for (const slot of allSlots) {
+        if (!documentIds.has(slot.id)) {
+            errors.push({
+                code: 'missing_pinned_component',
+                componentType: slot.type,
+                message: `Required component "${slot.type}" is missing from the document.`,
+            });
+        }
+    }
+    checkListOrder(contentSlots, documentContent, errors);
+    for (const zone of zoneSlots) {
+        checkListOrder(zone.slots, asComponentList(documentZones[zone.key]), errors);
+    }
+    return { errors };
+}

package/dist/types.d.ts

@@ -10,6 +10,12 @@ export interface FieldOption {
     label: string;
     value: string | number | boolean;
 }
+/**
+ * Whether a translation prop's value is owned by the canonical it derives from
+ * (`canonical` — inherited/propagated down) or by the translation itself
+ * (`locale` — sovereign). A property of the relationship, not of the field.
+ */
+export type Authority = 'canonical' | 'locale';
 export interface ComponentField {
     name: string;
     type: string;
@@ -26,7 +32,7 @@ export interface ComponentSchema {
 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';
+    code: 'unknown_component_type' | 'component_type_case_mismatch' | 'invalid_prop_key' | 'invalid_prop_value' | 'missing_required_prop' | 'invalid_readonly_key' | 'deprecated_zones_usage';
     message: string;
 }
 export interface FetchRegistryOpts {
@@ -44,4 +50,80 @@ export interface ValidateInput {
         warnOnZonesUsage?: boolean;
     };
 }
+export interface TemplateComponent {
+    type: string;
+    props: {
+        id?: string;
+        [key: string]: unknown;
+    };
+}
+export interface TemplateSnapshot {
+    content: TemplateComponent[];
+    root: {
+        props: {
+            _pinMap?: Record<string, boolean>;
+            /**
+             * Per-slot authority default, keyed by slot id (a component's `props.id`).
+             * A slot absent from the map defaults to `canonical`. An individual
+             * translation may override this per prop in its localization edge metadata.
+             */
+            _localeAuthority?: Record<string, Authority>;
+            [key: string]: unknown;
+        };
+    };
+    zones?: Record<string, TemplateComponent[]>;
+}
+export interface StructuralConformanceError {
+    code: 'missing_pinned_component' | 'pinned_component_out_of_order' | 'unexpected_component_at_pinned_slot';
+    message: string;
+    componentType: string;
+    expectedIndex?: number;
+    actualIndex?: number;
+}
+export interface ValidateStructureInput {
+    documentSnapshot: Record<string, unknown>;
+    templateSnapshot: unknown;
+}
+/**
+ * Severity stamped on an authority diagnostic. `warning` surfaces a
+ * canonical-authority write without blocking it; `error` marks it a violation.
+ */
+export type AuthoritySeverity = 'warning' | 'error';
+/**
+ * Per-prop authority overrides on a translation's localization edge, nested by
+ * slot id then prop name. An entry breaks that prop's inheritance from the
+ * slot's template default.
+ */
+export type AuthorityOverrideMap = Record<string, Record<string, Authority>>;
+/**
+ * A diagnostic raised when a write targets a prop whose effective authority is
+ * `canonical` — a prop the translation does not own. `authority` carries that
+ * resolved authority, so a consumer branches on it without re-deriving it.
+ */
+export interface AuthorityDiagnostic {
+    opIndex: number;
+    path: string;
+    code: 'canonical_authority_write';
+    severity: AuthoritySeverity;
+    slotId: string;
+    propName: string;
+    authority: Authority;
+    message: string;
+}
+export interface ValidateTranslationAuthorityInput {
+    operations: EditOperation[];
+    currentSnapshot: Record<string, unknown>;
+    /** Template snapshot supplying each slot's `_localeAuthority` default. */
+    templateSnapshot: unknown;
+    /**
+     * Per-slot defaults for a caller holding the resolved map rather than the
+     * template it came from. Consulted before `templateSnapshot`; a slot named by
+     * neither defaults to `canonical`.
+     */
+    slotAuthority?: Record<string, Authority>;
+    /** Per-prop overrides from the localization edge; absent props follow the default. */
+    authorityOverrides?: AuthorityOverrideMap;
+    /** Severity to stamp on emitted diagnostics. Defaults to `warning`. */
+    severity?: AuthoritySeverity;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/validator.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,aAAa,EAAE,eAAe,EAAmC,MAAM,YAAY,CAAC;AA+UjH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG;IAAE,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CA2D/E"}

package/dist/validator.js

@@ -1,24 +1,8 @@
-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);
-}
+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}
@@ -95,14 +79,45 @@ function validateComponent(comp, registry, opIndex, path, errors, zonesKey, warn
             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];
+    const schema = registry[registryComponentKey(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(', ')}.`,
+                `Use list_components to see available types: ${Object.entries(registry).map(([key, s]) => s.name ?? key).join(', ')}.`,
+        });
+        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,
+            path,
+            code: 'component_type_case_mismatch',
+            message: `Component type "${comp.type}" at "${path}" does not match the registered ` +
+                `casing "${schema.name}". Component types are case-sensitive — use "${schema.name}".`,
         });
         return;
     }
@@ -129,7 +144,7 @@ function validateComponent(comp, registry, opIndex, path, errors, zonesKey, warn
     for (const [key, val] of Object.entries(comp.props)) {
         if (opaqueProps.has(key) || key === 'id')
             continue;
-        if (Array.isArray(val) && val.some(isPuckComponentShape)) {
+        if (Array.isArray(val) && val.some(isComponentShape)) {
             validateContent(val, registry, opIndex, `${path}.props.${key}`, errors, zonesKey, warnOnZonesUsage);
         }
     }
@@ -143,7 +158,7 @@ function validateContent(value, registry, opIndex, path, errors, zonesKey, warnO
         });
         return;
     }
-    if (isPuckComponentShape(value)) {
+    if (isComponentShape(value)) {
         validateComponent(value, registry, opIndex, path, errors, zonesKey, warnOnZonesUsage);
         return;
     }
@@ -169,19 +184,19 @@ function validateContent(value, registry, opIndex, path, errors, zonesKey, warnO
  * 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))
+    const resolved = resolvePropPath(op.path, snapshot);
+    if (resolved === undefined)
         return;
-    const schema = registry[val.type];
+    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 }
     if (propsIdx === parts.length - 1) {
@@ -266,6 +281,16 @@ export function validateOps(input) {
     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;
+    }
     const zonesKey = config.zonesKey ?? 'zones';
     const warnOnZonesUsage = config.warnOnZonesUsage ?? true;
     const errors = [];
@@ -295,10 +320,10 @@ export function validateOps(input) {
         // 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);
+            validatePropPathOp(op, opIndex, currentSnapshot, normalizedRegistry, errors);
         }
         // Content-shape validation: catches component replacements and slot content.
-        validateContent(op.content, registry, opIndex, op.path, errors, zonesKey, warnOnZonesUsage);
+        validateContent(op.content, normalizedRegistry, opIndex, op.path, errors, zonesKey, warnOnZonesUsage);
     }
     return { errors };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantheon-systems/p1-content-validator",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "description": "Validates Puck component edit operations against the CSS component registry",
   "repository": {
     "type": "git",
@@ -28,13 +28,19 @@
   "engines": {
     "node": ">=20.0.0"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": false
+  },
   "license": "MIT",
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist *.tsbuildinfo",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src tests"
+    "typecheck": "tsc --noEmit"
   }
 }