@pantheon-systems/p1-content-validator 2.2.2-canary-20260928152900 → 2.3.0

package/dist/component-descriptor.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The stored shape of a registered component and of the registry index, and
+ * the content hash both are compared by.
+ */
+/**
+ * Where a component's definition comes from: the site itself, an upstream it
+ * inherits from unchanged, or an upstream component the site redefines.
+ */
+export type ComponentProvenance = 'site' | 'upstream' | 'overridden';
+export interface FieldAiMeta {
+    instructions?: string;
+    required?: boolean;
+    schema?: unknown;
+    exclude?: boolean;
+    /** Set to false to disable streaming for this field (e.g., image URLs, hrefs — streaming partial URLs causes broken values) */
+    stream?: boolean;
+    /** Connects this field to the output of an inline AI tool (Puck AI plugin feature) */
+    bind?: string;
+}
+interface FieldBase {
+    name: string;
+    label?: string;
+    ai?: FieldAiMeta;
+}
+interface FieldOption {
+    label: string;
+    value: string | number | boolean;
+}
+interface TextField extends FieldBase {
+    type: 'text';
+}
+interface TextAreaField extends FieldBase {
+    type: 'textarea';
+}
+interface NumberField extends FieldBase {
+    type: 'number';
+    min?: number;
+    max?: number;
+}
+interface SelectField extends FieldBase {
+    type: 'select';
+    options: FieldOption[];
+}
+interface RadioField extends FieldBase {
+    type: 'radio';
+    options: FieldOption[];
+}
+interface ArrayField extends FieldBase {
+    type: 'array';
+    arrayFields: SerializedField[];
+}
+interface ObjectField extends FieldBase {
+    type: 'object';
+    objectFields: SerializedField[];
+}
+interface CustomField extends FieldBase {
+    type: 'custom';
+}
+export type SerializedField = TextField | TextAreaField | NumberField | SelectField | RadioField | ArrayField | ObjectField | CustomField;
+export interface ComponentDescriptor {
+    name: string;
+    label: string;
+    fields: SerializedField[];
+    defaultProps: Record<string, unknown>;
+    ai?: {
+        instructions?: string;
+        defaultZone?: string;
+        exclude?: boolean;
+    };
+    slots?: Record<string, {
+        allowedComponents?: string[];
+        minItems?: number;
+        maxItems?: number;
+    }>;
+    provenance: ComponentProvenance;
+    descriptorHash: string;
+    upstreamHash?: string;
+    registeredAt: string;
+}
+export interface RegistryIndex {
+    siteId: string;
+    branchId: string;
+    updatedAt: string;
+    componentNames: string[];
+    provenance: Record<string, ComponentProvenance>;
+    /**
+     * Map of componentName → descriptorHash for fast change detection on startup.
+     * When present, the registry hook reads all hashes from this single index version
+     * instead of fetching each component document individually (N requests → 1).
+     */
+    hashes?: Record<string, string>;
+    /**
+     * Timestamp of the last full, per-component verification of every hash in
+     * `hashes` against its component document's own stored content.
+     * Once `verifiedAt` is older than REGISTRY_VERIFICATION_INTERVAL_MS, the
+     * hook forces a real per-component check instead of trusting `hashes`.
+     * Carried forward unchanged on fast-path runs; only refreshed
+     * when a full per-component verification actually just ran.
+     */
+    verifiedAt?: string;
+}
+/**
+ * djb2 hash over the canonical JSON of a descriptor.
+ *
+ * The following fields are intentionally excluded from the hash input:
+ * - `descriptorHash`: the hash itself must not feed into its own computation.
+ * - `registeredAt`: a timestamp that changes on every registration run; including
+ *   it would make every component appear "changed" on every editor open.
+ * - `provenance`: a classification artifact derived from comparing site vs upstream
+ *   schemas; it does not describe the component's own shape and should not affect
+ *   whether a write is triggered.
+ * - `upstreamHash`: similarly a comparative artifact, not part of the schema identity.
+ */
+export declare function hashDescriptor(descriptor: Omit<ComponentDescriptor, 'descriptorHash'> & {
+    descriptorHash?: string;
+}): string;
+export {};

package/dist/component-descriptor.js

@@ -0,0 +1,20 @@
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => [k, sortKeys(v)]));
+    }
+    return value;
+}
+export function hashDescriptor(descriptor) {
+    const { descriptorHash: _ignored, registeredAt: _ts, provenance: _prov, upstreamHash: _up, ...hashable } = descriptor;
+    const json = JSON.stringify(sortKeys(hashable));
+    let hash = 5381;
+    for (let i = 0; i < json.length; i++) {
+        hash = ((hash << 5) + hash) ^ json.charCodeAt(i);
+        hash = hash >>> 0;
+    }
+    return hash.toString(16);
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { validateOps } from './validator.js';
 export { fetchRegistry, listRegistryVersions, snapshotToComponentSchema, registryComponentKey, componentNameFromPath, } from './registry.js';
+export { hashDescriptor } from './component-descriptor.js';
+export type { ComponentDescriptor, ComponentProvenance, FieldAiMeta, RegistryIndex, SerializedField, } from './component-descriptor.js';
 export { validateDocumentStructure } from './structure-validator.js';
 export { validateTranslationAuthority } from './authority-enforcement.js';
 export { resolveTranslatable, resolveSlotAuthority, resolveSlotAuthorityMap, isAuthority, AUTHORITIES, DEFAULT_AUTHORITY, ROOT_SLOT_ID, } from './localization.js';

package/dist/index.js

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

package/dist/validator.js

@@ -1,5 +1,5 @@
 import { registryComponentKey } from './registry.js';
-import { isComponentShape, resolvePropPath } from './guards.js';
+import { getAtPath, isComponentShape, isPlainObject, resolvePropPath } from './guards.js';
 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;
 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;
 const ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
@@ -8,6 +8,27 @@ function isValidPuckId(value) {
         return false;
     return UUID_V4_RE.test(value) || PREFIXED_UUID_RE.test(value) || ULID_RE.test(value);
 }
+function isAcceptedId(value, existingIds) {
+    return isValidPuckId(value) || (typeof value === 'string' && existingIds.has(value));
+}
+function componentIds(value, ids = new Set()) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            componentIds(item, ids);
+    }
+    else if (isPlainObject(value)) {
+        if (isComponentShape(value) && typeof value.props.id === 'string')
+            ids.add(value.props.id);
+        for (const child of Object.values(value))
+            componentIds(child, ids);
+    }
+    return ids;
+}
+function idsHeldAt(snapshot, op) {
+    if (op.type !== 'replace' || snapshot === undefined)
+        return new Set();
+    return componentIds(getAtPath(snapshot, op.path.replace(/\.props$/, '')));
+}
 function allowedPropsForSchema(schema) {
     return new Set([
         'id',
@@ -38,7 +59,7 @@ function validateEnumValue(field, value, componentType, propKey, opIndex, path,
         });
     }
 }
-function validateComponent(comp, registry, opIndex, path, errors, zonesKey, warnOnZonesUsage) {
+function validateComponent(comp, registry, opIndex, path, errors, zonesKey, warnOnZonesUsage, existingIds) {
     if ('readOnly' in comp) {
         errors.push({
             opIndex,
@@ -55,7 +76,7 @@ function validateComponent(comp, registry, opIndex, path, errors, zonesKey, warn
             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)) {
+    else if (!isAcceptedId(comp.props.id, existingIds)) {
         errors.push({
             opIndex,
             path: `${path}.props.id`,
@@ -106,21 +127,21 @@ function validateComponent(comp, registry, opIndex, path, errors, zonesKey, warn
         if (opaqueProps.has(key) || key === 'id')
             continue;
         if (Array.isArray(val) && val.some(isComponentShape)) {
-            validateContent(val, registry, opIndex, `${path}.props.${key}`, errors, zonesKey, warnOnZonesUsage);
+            validateContent(val, registry, opIndex, `${path}.props.${key}`, errors, zonesKey, warnOnZonesUsage, existingIds);
         }
     }
 }
-function validateContent(value, registry, opIndex, path, errors, zonesKey, warnOnZonesUsage) {
+function validateContent(value, registry, opIndex, path, errors, zonesKey, warnOnZonesUsage, existingIds) {
     if (value === null || typeof value !== 'object')
         return;
     if (Array.isArray(value)) {
         value.forEach((item, i) => {
-            validateContent(item, registry, opIndex, `${path}.${i}`, errors, zonesKey, warnOnZonesUsage);
+            validateContent(item, registry, opIndex, `${path}.${i}`, errors, zonesKey, warnOnZonesUsage, existingIds);
         });
         return;
     }
     if (isComponentShape(value)) {
-        validateComponent(value, registry, opIndex, path, errors, zonesKey, warnOnZonesUsage);
+        validateComponent(value, registry, opIndex, path, errors, zonesKey, warnOnZonesUsage, existingIds);
         return;
     }
     for (const [key, val] of Object.entries(value)) {
@@ -133,10 +154,10 @@ function validateContent(value, registry, opIndex, path, errors, zonesKey, warnO
                 message: `"${zonesKey}" is deprecated. Use slot props instead.`,
             });
         }
-        validateContent(val, registry, opIndex, childPath, errors, zonesKey, warnOnZonesUsage);
+        validateContent(val, registry, opIndex, childPath, errors, zonesKey, warnOnZonesUsage, existingIds);
     }
 }
-function validatePropPathOp(op, opIndex, snapshot, registry, errors) {
+function validatePropPathOp(op, opIndex, snapshot, registry, errors, existingIds) {
     const resolved = resolvePropPath(op.path, snapshot);
     if (resolved === undefined)
         return;
@@ -157,7 +178,7 @@ function validatePropPathOp(op, opIndex, snapshot, registry, errors) {
                 message: `Component "${val.type}" at "${componentPath}" is missing required prop "id".`,
             });
         }
-        else if (!isValidPuckId(propsObj.id)) {
+        else if (!isAcceptedId(propsObj.id, existingIds)) {
             errors.push({
                 opIndex,
                 path: `${op.path}.id`,
@@ -232,6 +253,7 @@ export function validateOps(input) {
             continue;
         if (op.content === undefined)
             continue;
+        const existingIds = idsHeldAt(currentSnapshot, op);
         if (op.path.split('.').includes('readOnly')) {
             errors.push({
                 opIndex,
@@ -250,9 +272,9 @@ export function validateOps(input) {
             });
         }
         if (currentSnapshot !== undefined) {
-            validatePropPathOp(op, opIndex, currentSnapshot, normalizedRegistry, errors);
+            validatePropPathOp(op, opIndex, currentSnapshot, normalizedRegistry, errors, existingIds);
         }
-        validateContent(op.content, normalizedRegistry, opIndex, op.path, errors, zonesKey, warnOnZonesUsage);
+        validateContent(op.content, normalizedRegistry, opIndex, op.path, errors, zonesKey, warnOnZonesUsage, existingIds);
     }
     return { errors };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantheon-systems/p1-content-validator",
-  "version": "2.2.2-canary-20260928152900",
+  "version": "2.3.0",
   "description": "Validates Puck component edit operations against the P1 component registry",
   "repository": {
     "type": "git",