@pantheon-systems/puck-css 0.4.0

package/dist/editor/useComponentRegistry.js

@@ -0,0 +1,237 @@
+/**
+ * useComponentRegistry Hook
+ *
+ * Runs at editor startup to serialise the Puck config into ComponentDescriptor
+ * objects, hash-checks them for changes, and writes updated descriptors to CSS
+ * documents under the /_registry/ path prefix.
+ *
+ * Uses the same P1PuckContext pattern as useVersions, useAutoSave, and useDocuments.
+ */
+import { useState, useEffect } from 'react';
+import { useP1Puck } from '../core/P1PuckContext.js';
+import { extractDescriptors, buildRegistryIndex, } from './utils/componentRegistry.js';
+import { ConflictError } from '@pantheon-systems/css-client';
+// =============================================================================
+// Registry path helpers
+// =============================================================================
+const REGISTRY_PREFIX = '_registry/';
+const COMPONENT_PREFIX = '_registry/components/';
+const INDEX_PATH = '_registry/index';
+function componentPath(name) {
+    return `${COMPONENT_PREFIX}${name}`;
+}
+async function runRegistration(client, siteId, branchId, descriptors) {
+    // Step 1: List all existing registry documents
+    const existingDocs = (await client.documents.list(siteId, branchId, {
+        pathPrefix: REGISTRY_PREFIX,
+    }));
+    // Step 2: Build lookup maps for existing component docs
+    const docByName = new Map();
+    let indexDoc;
+    for (const doc of existingDocs) {
+        if (doc.path === INDEX_PATH) {
+            indexDoc = doc;
+        }
+        else if (doc.path.startsWith(COMPONENT_PREFIX)) {
+            const name = doc.path.slice(COMPONENT_PREFIX.length);
+            docByName.set(name, doc);
+        }
+    }
+    // Step 3: Resolve stored hashes — fast path (from index) or legacy (per-component).
+    //
+    // Fast path: if the index version has a `hashes` map, read all hashes from it
+    // in a single request instead of fetching each component version individually.
+    // This collapses N simultaneous getLatest calls (one per component) into 1.
+    //
+    // Legacy fallback: index exists but has no `hashes` field (written by an older
+    // version of this hook), or no index exists yet. Falls back to per-component
+    // fetches so existing registries continue to work on the first run after deploy.
+    const storedHashByName = new Map();
+    let gotHashesFromIndex = false;
+    if (indexDoc !== undefined) {
+        try {
+            const indexVersion = await client.versions.getLatest(siteId, branchId, indexDoc.id);
+            const indexSnapshot = indexVersion.snapshot;
+            if (indexSnapshot.hashes !== undefined && typeof indexSnapshot.hashes === 'object') {
+                for (const [name, hash] of Object.entries(indexSnapshot.hashes)) {
+                    if (typeof hash === 'string') {
+                        storedHashByName.set(name, hash);
+                    }
+                }
+                gotHashesFromIndex = true;
+                console.debug('[useComponentRegistry] Fast path: loaded', storedHashByName.size, 'hashes from index');
+            }
+            else {
+                console.debug('[useComponentRegistry] Index exists but has no hashes field (legacy format) — falling back to per-component fetch');
+            }
+        }
+        catch (err) {
+            console.debug('[useComponentRegistry] Index version fetch failed — falling back to per-component fetch:', err);
+        }
+    }
+    else {
+        console.debug('[useComponentRegistry] No index document found — will create one after registration');
+    }
+    if (!gotHashesFromIndex) {
+        // Legacy path: fetch each component version individually to get stored hash.
+        console.debug('[useComponentRegistry] Legacy path: fetching', docByName.size, 'component versions individually');
+        await Promise.all(Array.from(docByName.entries()).map(async ([name, doc]) => {
+            try {
+                const version = await client.versions.getLatest(siteId, branchId, doc.id);
+                const snapshot = version.snapshot;
+                if (typeof snapshot.descriptorHash === 'string') {
+                    storedHashByName.set(name, snapshot.descriptorHash);
+                }
+            }
+            catch {
+                // Version fetch failure → treat as hash mismatch, will overwrite
+            }
+        }));
+    }
+    // Step 4: Write only changed/new descriptors
+    let registered = 0;
+    let skipped = 0;
+    await Promise.all(descriptors.map(async (descriptor) => {
+        const storedHash = storedHashByName.get(descriptor.name);
+        const existingDoc = docByName.get(descriptor.name);
+        // Skip only when the hash is unchanged AND the component document still
+        // exists on this branch. A hash-only check is unsafe: the index can drift
+        // out of sync with on-disk component docs (e.g. a partial historical
+        // write, an out-of-band deletion, or branch CoW interactions where the
+        // index was inherited but its referenced component docs were not). In
+        // that case the index reports a matching hash for a name whose document
+        // is missing, and the registry stays permanently stuck at fewer
+        // components than the running config defines. Requiring `existingDoc`
+        // forces the missing component through the create path on the next run,
+        // which self-heals the desync and rewrites the index from the full
+        // descriptor set.
+        if (existingDoc !== undefined && storedHash === descriptor.descriptorHash) {
+            skipped++;
+            return;
+        }
+        let docId;
+        if (existingDoc === undefined) {
+            try {
+                const newDoc = await client.documents.create({
+                    siteId,
+                    branchId,
+                    path: componentPath(descriptor.name),
+                });
+                docId = newDoc.id;
+            }
+            catch (err) {
+                if (err instanceof ConflictError) {
+                    const existing = await client.documents.getByPath(siteId, componentPath(descriptor.name));
+                    docId = existing.id;
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        else {
+            docId = existingDoc.id;
+        }
+        await client.versions.create(siteId, {
+            documentId: docId,
+            branchId,
+            snapshot: descriptor,
+        });
+        registered++;
+    }));
+    console.debug('[useComponentRegistry] Registration complete:', 'registered =', registered, 'skipped =', skipped, 'total =', descriptors.length, '| gotHashesFromIndex =', gotHashesFromIndex);
+    // Detect hash instability: if we got hashes from the index but still had to register
+    // components, log which components had mismatched hashes.
+    if (gotHashesFromIndex && registered > 0) {
+        const changed = descriptors.filter(d => storedHashByName.get(d.name) !== d.descriptorHash);
+        console.warn('[useComponentRegistry] Hash mismatch detected for', changed.length, 'component(s) despite index being present.', 'These components will trigger a full re-registration on every load if their hashes are unstable:', changed.map(d => ({ name: d.name, stored: storedHashByName.get(d.name), computed: d.descriptorHash })));
+    }
+    // Step 5: Write index when something changed, index doesn't exist yet, OR the existing
+    // index lacks the `hashes` field (legacy format). The third condition promotes legacy
+    // indexes to the fast-path format so that the next startup can skip per-component fetches.
+    const indexNeedsWrite = registered > 0 || indexDoc === undefined || !gotHashesFromIndex;
+    console.debug('[useComponentRegistry] indexNeedsWrite =', indexNeedsWrite, '(registered > 0:', registered > 0, ', no indexDoc:', indexDoc === undefined, ', legacy format:', !gotHashesFromIndex, ')');
+    if (indexNeedsWrite) {
+        const index = buildRegistryIndex(descriptors, siteId, branchId);
+        let indexDocId;
+        if (indexDoc === undefined) {
+            try {
+                const newIndexDoc = await client.documents.create({ siteId, branchId, path: INDEX_PATH });
+                indexDocId = newIndexDoc.id;
+            }
+            catch (err) {
+                if (err instanceof ConflictError) {
+                    const existing = await client.documents.getByPath(siteId, INDEX_PATH);
+                    indexDocId = existing.id;
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        else {
+            indexDocId = indexDoc.id;
+        }
+        await client.versions.create(siteId, {
+            documentId: indexDocId,
+            branchId,
+            snapshot: index,
+        });
+    }
+    return { registered, skipped, total: descriptors.length };
+}
+// =============================================================================
+// Hook
+// =============================================================================
+export function useComponentRegistry(options) {
+    const { puckConfig, upstreamPuckConfig, onRegistered, onError } = options;
+    const { client, siteId, branchId } = useP1Puck();
+    const [status, setStatus] = useState('idle');
+    const [result, setResult] = useState(null);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        // branchId starts as null and resolves asynchronously. Skip registration
+        // until it is available to avoid a guaranteed 404 on every page load.
+        if (!branchId)
+            return;
+        let cancelled = false;
+        setStatus('registering');
+        const descriptors = extractDescriptors(puckConfig, upstreamPuckConfig);
+        runRegistration(client, siteId, branchId, descriptors)
+            .then((registrationResult) => {
+            if (cancelled)
+                return;
+            setStatus('registered');
+            setResult(registrationResult);
+            onRegistered?.(registrationResult);
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            const registrationError = err instanceof Error ? err : new Error(String(err));
+            setStatus('error');
+            setError(registrationError);
+            onError?.(registrationError);
+            // Log but don't re-throw — a registry failure must not break the editor
+            console.warn('[useComponentRegistry] Registration failed:', registrationError.message);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // Dependency array rationale:
+        //   - `puckConfig` / `upstreamPuckConfig`: re-run whenever the component schema changes.
+        //   - `siteId` / `branchId`: re-run when the user switches sites or branches.
+        //   - `client`: intentionally omitted — P1PuckContext provides a stable reference across renders;
+        //     including it would cause spurious re-registrations on every context re-render.
+        //   - `onRegistered` / `onError`: intentionally omitted — callback identity changes (e.g. from
+        //     an inline arrow function) must not trigger re-registration. Callers are expected to
+        //     memoize callbacks or accept that the latest callback at call-time is used.
+        //   - `puckConfigRef`: not used — `puckConfig` is expected to be a stable reference from the
+        //     consumer (same object passed to <Puck config={...} />). A ref guard was considered but
+        //     removed because consumers that inline config objects would be broken by design; the hook
+        //     documents the stable-reference expectation instead.
+        // eslint-disable-next-line -- intentional omissions documented above
+    }, [puckConfig, upstreamPuckConfig, siteId, branchId]);
+    return { status, result, error };
+}
+//# sourceMappingURL=useComponentRegistry.js.map

package/dist/editor/useComponentRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useComponentRegistry.js","sourceRoot":"","sources":["../../src/editor/useComponentRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GAGnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AA8B7D,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAEhF,MAAM,eAAe,GAAG,YAAY,CAAC;AACrC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AACjD,MAAM,UAAU,GAAG,iBAAiB,CAAC;AAErC,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,GAAG,gBAAgB,GAAG,IAAI,EAAE,CAAC;AACtC,CAAC;AAYD,KAAK,UAAU,eAAe,CAC5B,MAAgB,EAChB,MAAc,EACd,QAAgB,EAChB,WAAkC;IAElC,+CAA+C;IAC/C,MAAM,YAAY,GAAG,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE;QAClE,UAAU,EAAE,eAAe;KAC5B,CAAC,CAAmB,CAAC;IAEtB,wDAAwD;IACxD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAwB,CAAC;IAClD,IAAI,QAAkC,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC5B,QAAQ,GAAG,GAAG,CAAC;QACjB,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;YACrD,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,oFAAoF;IACpF,EAAE;IACF,8EAA8E;IAC9E,+EAA+E;IAC/E,4EAA4E;IAC5E,EAAE;IACF,+EAA+E;IAC/E,6EAA6E;IAC7E,iFAAiF;IACjF,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAkB,CAAC;IACnD,IAAI,kBAAkB,GAAG,KAAK,CAAC;IAE/B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;YACpF,MAAM,aAAa,GAAG,YAAY,CAAC,QAAkC,CAAC;YACtE,IAAI,aAAa,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,aAAa,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACnF,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;oBAChE,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;wBAC7B,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;oBACnC,CAAC;gBACH,CAAC;gBACD,kBAAkB,GAAG,IAAI,CAAC;gBAC1B,OAAO,CAAC,KAAK,CAAC,0CAA0C,EAAE,gBAAgB,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;YACxG,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,mHAAmH,CAAC,CAAC;YACrI,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,0FAA0F,EAAE,GAAG,CAAC,CAAC;QACjH,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,qFAAqF,CAAC,CAAC;IACvG,CAAC;IAED,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,6EAA6E;QAC7E,OAAO,CAAC,KAAK,CAAC,8CAA8C,EAAE,SAAS,CAAC,IAAI,EAAE,iCAAiC,CAAC,CAAC;QACjH,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE;YACxD,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC1E,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAwC,CAAC;gBAClE,IAAI,OAAO,QAAQ,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;oBAChD,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;gBACtD,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,iEAAiE;YACnE,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;IAED,6CAA6C;IAC7C,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,MAAM,OAAO,CAAC,GAAG,CACf,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE;QACnC,MAAM,UAAU,GAAG,gBAAgB,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAEnD,wEAAwE;QACxE,0EAA0E;QAC1E,qEAAqE;QACrE,uEAAuE;QACvE,sEAAsE;QACtE,wEAAwE;QACxE,gEAAgE;QAChE,sEAAsE;QACtE,wEAAwE;QACxE,mEAAmE;QACnE,kBAAkB;QAClB,IAAI,WAAW,KAAK,SAAS,IAAI,UAAU,KAAK,UAAU,CAAC,cAAc,EAAE,CAAC;YAC1E,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QAED,IAAI,KAAa,CAAC;QAElB,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;oBAC3C,MAAM;oBACN,QAAQ;oBACR,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC;iBACrC,CAAC,CAAC;gBACH,KAAK,GAAI,MAAuB,CAAC,EAAE,CAAC;YACtC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;oBACjC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;oBAC1F,KAAK,GAAI,QAAyB,CAAC,EAAE,CAAC;gBACxC,CAAC;qBAAM,CAAC;oBACN,MAAM,GAAG,CAAC;gBACZ,CAAC;YACH,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC;QACzB,CAAC;QAED,MAAM,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;YACnC,UAAU,EAAE,KAAK;YACjB,QAAQ;YACR,QAAQ,EAAE,UAAgD;SAC3D,CAAC,CAAC;QAEH,UAAU,EAAE,CAAC;IACf,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,CAAC,KAAK,CACX,+CAA+C,EAC/C,cAAc,EAAE,UAAU,EAC1B,WAAW,EAAE,OAAO,EACpB,SAAS,EAAE,WAAW,CAAC,MAAM,EAC7B,wBAAwB,EAAE,kBAAkB,CAC7C,CAAC;IAEF,qFAAqF;IACrF,0DAA0D;IAC1D,IAAI,kBAAkB,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,CAAC;QAC3F,OAAO,CAAC,IAAI,CACV,mDAAmD,EAAE,OAAO,CAAC,MAAM,EAAE,2CAA2C,EAChH,kGAAkG,EAClG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CACvG,CAAC;IACJ,CAAC;IAED,uFAAuF;IACvF,sFAAsF;IACtF,2FAA2F;IAC3F,MAAM,eAAe,GAAG,UAAU,GAAG,CAAC,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,kBAAkB,CAAC;IACxF,OAAO,CAAC,KAAK,CAAC,0CAA0C,EAAE,eAAe,EAAE,kBAAkB,EAAE,UAAU,GAAG,CAAC,EAAE,gBAAgB,EAAE,QAAQ,KAAK,SAAS,EAAE,kBAAkB,EAAE,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IAEvM,IAAI,eAAe,EAAE,CAAC;QACpB,MAAM,KAAK,GAAkB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC/E,IAAI,UAAkB,CAAC;QACvB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;gBAC1F,UAAU,GAAI,WAA4B,CAAC,EAAE,CAAC;YAChD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;oBACjC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;oBACtE,UAAU,GAAI,QAAyB,CAAC,EAAE,CAAC;gBAC7C,CAAC;qBAAM,CAAC;oBACN,MAAM,GAAG,CAAC;gBACZ,CAAC;YACH,CAAC;QACH,CAAC;aAAM,CAAC;YACN,UAAU,GAAG,QAAQ,CAAC,EAAE,CAAC;QAC3B,CAAC;QACD,MAAM,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;YACnC,UAAU,EAAE,UAAU;YACtB,QAAQ;YACR,QAAQ,EAAE,KAA2C;SACtD,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC;AAC5D,CAAC;AAED,gFAAgF;AAChF,OAAO;AACP,gFAAgF;AAEhF,MAAM,UAAU,oBAAoB,CAClC,OAAoC;IAEpC,MAAM,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC1E,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC;IAEjD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAuC,MAAM,CAAC,CAAC;IACnF,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAA4B,IAAI,CAAC,CAAC;IACtE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,SAAS,CAAC,GAAG,EAAE;QACb,yEAAyE;QACzE,sEAAsE;QACtE,IAAI,CAAC,QAAQ;YAAE,OAAO;QAEtB,IAAI,SAAS,GAAG,KAAK,CAAC;QAEtB,SAAS,CAAC,aAAa,CAAC,CAAC;QAEzB,MAAM,WAAW,GAAG,kBAAkB,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC;QAEvE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC;aACnD,IAAI,CAAC,CAAC,kBAAkB,EAAE,EAAE;YAC3B,IAAI,SAAS;gBAAE,OAAO;YACtB,SAAS,CAAC,YAAY,CAAC,CAAC;YACxB,SAAS,CAAC,kBAAkB,CAAC,CAAC;YAC9B,YAAY,EAAE,CAAC,kBAAkB,CAAC,CAAC;QACrC,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACtB,IAAI,SAAS;gBAAE,OAAO;YACtB,MAAM,iBAAiB,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9E,SAAS,CAAC,OAAO,CAAC,CAAC;YACnB,QAAQ,CAAC,iBAAiB,CAAC,CAAC;YAC5B,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC;YAC7B,wEAAwE;YACxE,OAAO,CAAC,IAAI,CAAC,6CAA6C,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;QACzF,CAAC,CAAC,CAAC;QAEL,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC;QACJ,8BAA8B;QAC9B,yFAAyF;QACzF,8EAA8E;QAC9E,kGAAkG;QAClG,qFAAqF;QACrF,+FAA+F;QAC/F,0FAA0F;QAC1F,iFAAiF;QACjF,6FAA6F;QAC7F,6FAA6F;QAC7F,+FAA+F;QAC/F,0DAA0D;QAC1D,qEAAqE;IACrE,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAEvD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACnC,CAAC"}

package/dist/editor/useDocuments.d.ts

@@ -0,0 +1,66 @@
+/**
+ * useDocuments Hook
+ *
+ * Provides document management functionality.
+ */
+import type { Document, PuckData } from '@pantheon-systems/css-client';
+import type { P1Client } from '@pantheon-systems/css-client';
+interface UseDocumentsParams {
+    client: P1Client;
+    siteId: string;
+    branchId: string;
+}
+interface UseDocumentsReturn {
+    /**
+     * List of documents on the current branch.
+     */
+    documents: Document[];
+    /**
+     * Loading state.
+     */
+    loading: boolean;
+    /**
+     * Error state.
+     */
+    error: Error | null;
+    /**
+     * Create a new document.
+     */
+    create: (path: string, initialData?: PuckData) => Promise<Document>;
+    /**
+     * Delete a document.
+     */
+    remove: (documentId: string) => Promise<void>;
+    /**
+     * Refresh the documents list.
+     */
+    refresh: () => Promise<void>;
+    /**
+     * Get a document by path.
+     */
+    getByPath: (path: string) => Document | undefined;
+}
+/**
+ * Hook for managing documents on a branch.
+ *
+ * @param params - Configuration for document management
+ * @returns Document state and operations
+ *
+ * @example
+ * ```tsx
+ * const { documents, create, remove, loading } = useDocuments({
+ *   client,
+ *   siteId,
+ *   branchId,
+ * });
+ *
+ * // Create a new page
+ * await create('/new-page');
+ *
+ * // Delete a page
+ * await remove(documentId);
+ * ```
+ */
+export declare function useDocuments({ client, siteId, branchId, }: UseDocumentsParams): UseDocumentsReturn;
+export {};
+//# sourceMappingURL=useDocuments.d.ts.map

package/dist/editor/useDocuments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocuments.d.ts","sourceRoot":"","sources":["../../src/editor/useDocuments.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAE7D,UAAU,kBAAkB;IAC1B,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,kBAAkB;IAC1B;;OAEG;IACH,SAAS,EAAE,QAAQ,EAAE,CAAC;IAEtB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEpE;;OAEG;IACH,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;OAEG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;OAEG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;CACnD;AAUD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,MAAM,EACN,QAAQ,GACT,EAAE,kBAAkB,GAAG,kBAAkB,CA+FzC"}

package/dist/editor/useDocuments.js

@@ -0,0 +1,112 @@
+/**
+ * useDocuments Hook
+ *
+ * Provides document management functionality.
+ */
+import { useState, useCallback, useEffect, useRef } from 'react';
+/**
+ * Default empty Puck data for new documents.
+ */
+const DEFAULT_PUCK_DATA = {
+    content: [],
+    root: { props: {} },
+};
+/**
+ * Hook for managing documents on a branch.
+ *
+ * @param params - Configuration for document management
+ * @returns Document state and operations
+ *
+ * @example
+ * ```tsx
+ * const { documents, create, remove, loading } = useDocuments({
+ *   client,
+ *   siteId,
+ *   branchId,
+ * });
+ *
+ * // Create a new page
+ * await create('/new-page');
+ *
+ * // Delete a page
+ * await remove(documentId);
+ * ```
+ */
+export function useDocuments({ client, siteId, branchId, }) {
+    const [documents, setDocuments] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Track the previous branchId to detect changes and reset state synchronously
+    const prevBranchIdRef = useRef(branchId);
+    // Reset state synchronously when branchId changes
+    // This prevents race conditions where loadDocument is recreated with new branchId
+    // but documents array still contains old branch's documents
+    if (branchId !== prevBranchIdRef.current) {
+        prevBranchIdRef.current = branchId;
+        // Clear documents and set loading synchronously during render
+        // This ensures consumers see loading=true immediately when branch changes
+        setDocuments([]);
+        setLoading(true);
+        setError(null);
+    }
+    // Fetch documents
+    const refresh = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const docs = await client.documents.list(siteId, branchId);
+            setDocuments(docs);
+        }
+        catch (err) {
+            console.error('[useDocuments] error:', err);
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, siteId, branchId]);
+    // Initial fetch and refetch when branchId changes
+    useEffect(() => {
+        if (branchId) {
+            void refresh();
+        }
+    }, [refresh, branchId]);
+    // Create a new document
+    const create = useCallback(async (path, initialData) => {
+        // Create the document
+        const doc = await client.documents.create({
+            siteId,
+            branchId,
+            path,
+        });
+        // Create initial version with default or provided data
+        const data = initialData ?? DEFAULT_PUCK_DATA;
+        await client.versions.create(siteId, {
+            documentId: doc.id,
+            branchId,
+            snapshot: data,
+        });
+        // Refresh the list
+        await refresh();
+        return doc;
+    }, [client, siteId, branchId, refresh]);
+    // Delete a document
+    const remove = useCallback(async (documentId) => {
+        await client.documents.delete(siteId, branchId, documentId);
+        await refresh();
+    }, [client, siteId, branchId, refresh]);
+    // Get document by path
+    const getByPath = useCallback((path) => {
+        return documents.find((doc) => doc.path === path);
+    }, [documents]);
+    return {
+        documents,
+        loading,
+        error,
+        create,
+        remove,
+        refresh,
+        getByPath,
+    };
+}
+//# sourceMappingURL=useDocuments.js.map

package/dist/editor/useDocuments.js.map

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

package/dist/editor/useMergePreview.d.ts

@@ -0,0 +1,15 @@
+import type { DocumentDiffSummary } from '../versioning/utils/branchDiff.js';
+export interface UseMergePreviewReturn {
+    documents: DocumentDiffSummary[];
+    loading: boolean;
+    error: Error | null;
+    sourceBranchName: string;
+    targetBranchName: string;
+    isMainBranch: boolean;
+}
+/**
+ * Automatically loads a merge preview comparing the current branch against main.
+ * Must be used inside a P1PuckProvider.
+ */
+export declare function useMergePreview(): UseMergePreviewReturn;
+//# sourceMappingURL=useMergePreview.d.ts.map

package/dist/editor/useMergePreview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMergePreview.d.ts","sourceRoot":"","sources":["../../src/editor/useMergePreview.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAE7E,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,qBAAqB,CAsDvD"}

package/dist/editor/useMergePreview.js

@@ -0,0 +1,56 @@
+import { useState, useEffect } from 'react';
+import { useP1Puck } from '../core/P1PuckContext.js';
+/**
+ * Automatically loads a merge preview comparing the current branch against main.
+ * Must be used inside a P1PuckProvider.
+ */
+export function useMergePreview() {
+    const css = useP1Puck();
+    const mainBranch = css.branches.find((b) => b.isMain) ?? null;
+    const isMainBranch = css.currentBranch?.isMain ?? false;
+    const [documents, setDocuments] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const sourceBranchName = css.currentBranch?.name ?? 'Draft';
+    const targetBranchName = mainBranch?.name ?? 'Live';
+    useEffect(() => {
+        if (css.branchesLoading)
+            return;
+        if (isMainBranch || !mainBranch) {
+            setLoading(false);
+            setDocuments([]);
+            return;
+        }
+        let cancelled = false;
+        setLoading(true);
+        setError(null);
+        css.client.merge
+            .preview(css.siteId, css.branchId, mainBranch.id, {
+            includeContent: true,
+            excludePathPrefixes: ['_registry/'],
+        })
+            .then((preview) => {
+            if (cancelled)
+                return;
+            const docs = (preview.documentDiffs ?? []).map((d) => ({
+                documentId: d.documentId,
+                documentPath: d.documentPath,
+                sourceSnapshot: d.sourceSnapshot,
+                targetSnapshot: d.targetSnapshot,
+            }));
+            setDocuments(docs);
+            setLoading(false);
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+            setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [css.siteId, css.branchId, mainBranch?.id, css.branchesLoading, isMainBranch]);
+    return { documents, loading, error, sourceBranchName, targetBranchName, isMainBranch };
+}
+//# sourceMappingURL=useMergePreview.js.map

package/dist/editor/useMergePreview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMergePreview.js","sourceRoot":"","sources":["../../src/editor/useMergePreview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAYrD;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;IAExB,MAAM,UAAU,GAAG,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC;IAC9D,MAAM,YAAY,GAAG,GAAG,CAAC,aAAa,EAAE,MAAM,IAAI,KAAK,CAAC;IAExD,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAwB,EAAE,CAAC,CAAC;IACtE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,MAAM,gBAAgB,GAAG,GAAG,CAAC,aAAa,EAAE,IAAI,IAAI,OAAO,CAAC;IAC5D,MAAM,gBAAgB,GAAG,UAAU,EAAE,IAAI,IAAI,MAAM,CAAC;IAEpD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,GAAG,CAAC,eAAe;YAAE,OAAO;QAEhC,IAAI,YAAY,IAAI,CAAC,UAAU,EAAE,CAAC;YAChC,UAAU,CAAC,KAAK,CAAC,CAAC;YAClB,YAAY,CAAC,EAAE,CAAC,CAAC;YACjB,OAAO;QACT,CAAC;QAED,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,UAAU,CAAC,IAAI,CAAC,CAAC;QACjB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,GAAG,CAAC,MAAM,CAAC,KAAK;aACb,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,EAAE;YAChD,cAAc,EAAE,IAAI;YACpB,mBAAmB,EAAE,CAAC,YAAY,CAAC;SACpC,CAAC;aACD,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;YAChB,IAAI,SAAS;gBAAE,OAAO;YACtB,MAAM,IAAI,GAA0B,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC5E,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,YAAY,EAAE,CAAC,CAAC,YAAY;gBAC5B,cAAc,EAAE,CAAC,CAAC,cAAc;gBAChC,cAAc,EAAE,CAAC,CAAC,cAAc;aACjC,CAAC,CAAC,CAAC;YACJ,YAAY,CAAC,IAAI,CAAC,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACtB,IAAI,SAAS;gBAAE,OAAO;YACtB,QAAQ,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC9D,UAAU,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;QAEL,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,GAAG,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC;IAElF,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,YAAY,EAAE,CAAC;AACzF,CAAC"}

package/dist/editor/useP1Editor.d.ts

@@ -0,0 +1,125 @@
+/**
+ * useP1Editor Hook
+ *
+ * All-in-one hook for setting up a P1-enabled Puck editor.
+ * Composes useP1Plugin and useP1Overrides internally, handles
+ * document loading, version management, historical version protection,
+ * and provides everything needed to render <Puck>.
+ */
+import type { ThumbnailMap } from './utils/buildThumbnailOverride.js';
+import type { UseP1PluginOptions } from './useP1Plugin.js';
+import type { UseP1OverridesOptions } from './useP1Overrides.js';
+import type { PuckOverrides } from './plugin/index.js';
+import type { Plugin } from '@puckeditor/core';
+import type { P1PuckContextValue } from '../core/types.js';
+import type { PuckData } from '@pantheon-systems/css-client';
+import type { UiState } from '@puckeditor/core';
+/**
+ * Options for useP1Editor.
+ */
+export interface UseP1EditorOptions {
+    /** Document path to load */
+    documentPath: string;
+    /** Puck component configuration */
+    puckConfig: unknown;
+    /** Additional plugins to include after the CSS plugin */
+    additionalPlugins?: Plugin[];
+    /**
+     * Additional overrides to merge with P1 overrides.
+     * Merged with stable memoization to prevent Puck's appStore.setState
+     * from firing on every render (which causes preview iframe re-renders).
+     * Nested objects (e.g. fieldTypes) are shallow-merged.
+     */
+    additionalOverrides?: PuckOverrides;
+    /**
+     * Map from Puck component name to a zero-argument React FC that renders a
+     * schematic SVG wireframe thumbnail. When provided, each drawer item shows
+     * a 48×32 thumbnail alongside the name and a drag-handle affordance.
+     * Unknown names fall back to a generic placeholder automatically.
+     *
+     * @example
+     * ```tsx
+     * import { THUMBNAIL_MAP } from '@/data/thumbnails';
+     *
+     * useP1Editor({ thumbnails: THUMBNAIL_MAP, ... });
+     * ```
+     */
+    thumbnails?: ThumbnailMap;
+    /** Customization options for overrides */
+    overrideOptions?: UseP1OverridesOptions;
+    /** Customization options for the CSS plugin (versions are managed internally) */
+    pluginOptions?: Omit<UseP1PluginOptions, 'versions' | 'versionsLoading' | 'selectedVersionId' | 'onVersionSelect'>;
+    /** Callback when user selection changes */
+    onSelectionChange?: (path: string | null, itemId: string | null) => void;
+    /** Called when document loading fails. Return true to retry loading. */
+    onDocumentNotFound?: (documentPath: string, error: Error) => Promise<boolean>;
+}
+/**
+ * Props to spread onto <Puck> component.
+ */
+export interface PuckProps {
+    /** Puck component configuration */
+    config: unknown;
+    /** Safe data (never null) */
+    data: PuckData;
+    /** onChange handler wired to context saveData (disabled for historical versions) */
+    onChange: (data: unknown) => void;
+    /** Plugin array with CSS plugin first */
+    plugins: Plugin[];
+    /** Overrides with header actions */
+    overrides: PuckOverrides;
+    /** Permissions (locked down for historical versions) */
+    permissions?: Record<string, boolean>;
+    /** Initial UI state (sidebar visibility etc.) — read from localStorage on each key-based remount */
+    ui?: Partial<UiState>;
+}
+/**
+ * Return value from useP1Editor.
+ */
+export interface UseP1EditorReturn {
+    /** Whether the initial document is still loading */
+    loading: boolean;
+    /** Error from document loading, if any */
+    error: Error | null;
+    /** React key — pass directly as `<Puck key={puckKey} {...puckProps} />` to force clean remount on document switch */
+    puckKey: string;
+    /** Props to spread onto <Puck> */
+    puckProps: PuckProps;
+    /** Full P1 context for advanced/escape-hatch use */
+    css: P1PuckContextValue;
+    /**
+     * @deprecated Always null. Branch-switch redirects have been removed; the
+     * editor now unloads the page context and shows an empty state in the
+     * preview area when the current document does not exist on the selected branch.
+     */
+    redirectPath: string | null;
+}
+/**
+ * All-in-one hook for setting up a P1-enabled Puck editor.
+ *
+ * Handles document loading, version management, plugin/overrides creation,
+ * safe data, historical version protection, and plugin array assembly.
+ * Returns everything needed to render <Puck> with minimal boilerplate.
+ *
+ * Must be used inside a P1PuckProvider.
+ *
+ * @param options - Editor configuration
+ * @returns Loading state, puck props, and P1 context
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const { loading, error, puckProps } = useP1Editor({
+ *     documentPath: '/home',
+ *     puckConfig: config,
+ *   });
+ *
+ *   if (loading) return <Loading />;
+ *   if (error) return <Error error={error} />;
+ *
+ *   return <Puck {...puckProps} />;
+ * }
+ * ```
+ */
+export declare function useP1Editor(options: UseP1EditorOptions): UseP1EditorReturn;
+//# sourceMappingURL=useP1Editor.d.ts.map

package/dist/editor/useP1Editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useP1Editor.d.ts","sourceRoot":"","sources":["../../src/editor/useP1Editor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAmB,MAAM,8BAA8B,CAAC;AAC9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,UAAU,EAAE,OAAO,CAAC;IACpB,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,aAAa,CAAC;IACpC;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,0CAA0C;IAC1C,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,iFAAiF;IACjF,aAAa,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC,CAAC;IACnH,2CAA2C;IAC3C,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACzE,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/E;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,6BAA6B;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,oFAAoF;IACpF,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,yCAAyC;IACzC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oCAAoC;IACpC,SAAS,EAAE,aAAa,CAAC;IACzB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,oGAAoG;IACpG,EAAE,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,qHAAqH;IACrH,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,SAAS,EAAE,SAAS,CAAC;IACrB,oDAAoD;IACpD,GAAG,EAAE,kBAAkB,CAAC;IACxB;;;;OAIG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAyW1E"}