@elytracms/studio 0.0.42 → 0.0.44

package/dist/components/cms/cms-composition-validators.js

@@ -0,0 +1,75 @@
+import { validateCompositionValue } from '@elytracms/core/project-graph';
+import { collectComponentEmbeds, parseRichTextValue } from '@elytracms/core/rich-text';
+import { getStudioRegistry } from '@elytracms/studio/lib/registry';
+/**
+ * Composition validator adapters (EC-326, extracted from `cms-store.tsx`) —
+ * injected into `validateDocument`'s `validateComposition`/`validateRichTextEmbeds`
+ * options so `@elytracms/core/cms-core` stays free of `@elytracms/core/project-graph`
+ * and `@elytracms/core/rich-text`.
+ */
+/**
+ * EC-188: validate a `blocks` composition field value against the field's `allow`
+ * vocabulary + the code-owned component registry (the leash), mapping graph
+ * issues into plain CMS findings. Never throws — a malformed (non-node)
+ * value degrades to a single finding, matching the "validation is first-class,
+ * never a crash" rule.
+ */
+export function validateComposition(value, field) {
+    if (value == null)
+        return [];
+    const roots = Array.isArray(value) ? value : [value];
+    if (!roots.every((r) => r != null && typeof r === 'object' && 'componentId' in r)) {
+        return [{ message: 'is not a valid composition (expected component nodes)', severity: 'error' }];
+    }
+    const components = getStudioRegistry().registry.lookup;
+    return validateCompositionValue(value, {
+        allow: field.allow,
+        components,
+    }).map((issue) => ({
+        message: issue.message,
+        severity: issue.severity,
+        nodePath: issue.path.join('/'),
+    }));
+}
+/**
+ * EC-189: validate the composition embeds inside a `richText` field value. Each
+ * `componentEmbed` holds a single `ComponentNode` constrained by the field's
+ * `allow` vocabulary (the SAME leash a `blocks` field uses). Parse the value, walk
+ * its embeds at any depth, and validate each embedded node via
+ * `validateCompositionValue`; findings carry the rich-text node path joined with
+ * the in-embed graph path. Never throws — a malformed embed degrades to a
+ * single finding.
+ */
+export function validateRichTextEmbeds(value, field) {
+    if (value == null)
+        return [];
+    const parsed = parseRichTextValue(value);
+    // A plain-string / schema-invalid rich-text value carries no embeds to check
+    // here (scalar type validation owns reporting a malformed value).
+    if (!parsed.ok)
+        return [];
+    const components = getStudioRegistry().registry.lookup;
+    const out = [];
+    for (const occurrence of collectComponentEmbeds(parsed.value.doc)) {
+        if (!occurrence.embedded) {
+            out.push({
+                message: `embed at ${occurrence.nodePath} is missing a valid embedded component`,
+                severity: 'error',
+                nodePath: occurrence.nodePath,
+            });
+            continue;
+        }
+        for (const issue of validateCompositionValue(occurrence.embedded, {
+            allow: field.allow,
+            components,
+        })) {
+            out.push({
+                message: issue.message,
+                severity: issue.severity,
+                nodePath: `${occurrence.nodePath}/attrs/node/${issue.path.join('/')}`,
+            });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=cms-composition-validators.js.map

package/dist/components/cms/cms-composition-validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms-composition-validators.js","sourceRoot":"","sources":["../../../src/components/cms/cms-composition-validators.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAExE,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AACtF,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAA;AAElE;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc,EAAE,KAAqB;IACvE,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,EAAE,CAAA;IAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;IACpD,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,aAAa,IAAI,CAAC,CAAC,EAAE,CAAC;QAClF,OAAO,CAAC,EAAE,OAAO,EAAE,uDAAuD,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAA;IAClG,CAAC;IACD,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAA;IACtD,OAAO,wBAAwB,CAAC,KAAwC,EAAE;QACxE,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,UAAU;KACX,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACjB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;KAC/B,CAAC,CAAC,CAAA;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc,EAAE,KAAuB;IAC5E,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,EAAE,CAAA;IAC5B,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;IACxC,6EAA6E;IAC7E,kEAAkE;IAClE,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,CAAA;IACzB,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAA;IACtD,MAAM,GAAG,GAAuB,EAAE,CAAA;IAClC,KAAK,MAAM,UAAU,IAAI,sBAAsB,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;YACzB,GAAG,CAAC,IAAI,CAAC;gBACP,OAAO,EAAE,YAAY,UAAU,CAAC,QAAQ,wCAAwC;gBAChF,QAAQ,EAAE,OAAO;gBACjB,QAAQ,EAAE,UAAU,CAAC,QAAQ;aAC9B,CAAC,CAAA;YACF,SAAQ;QACV,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,wBAAwB,CAAC,UAAU,CAAC,QAAQ,EAAE;YAChE,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,UAAU;SACX,CAAC,EAAE,CAAC;YACH,GAAG,CAAC,IAAI,CAAC;gBACP,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,QAAQ,EAAE,GAAG,UAAU,CAAC,QAAQ,eAAe,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;aACtE,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC","sourcesContent":["import type { BlocksFieldDef, CompositionIssue, RichTextFieldDef } from '@elytracms/core/cms-core'\nimport { validateCompositionValue } from '@elytracms/core/project-graph'\nimport type { ComponentNode } from '@elytracms/core/project-graph'\nimport { collectComponentEmbeds, parseRichTextValue } from '@elytracms/core/rich-text'\nimport { getStudioRegistry } from '@elytracms/studio/lib/registry'\n\n/**\n * Composition validator adapters (EC-326, extracted from `cms-store.tsx`) —\n * injected into `validateDocument`'s `validateComposition`/`validateRichTextEmbeds`\n * options so `@elytracms/core/cms-core` stays free of `@elytracms/core/project-graph`\n * and `@elytracms/core/rich-text`.\n */\n\n/**\n * EC-188: validate a `blocks` composition field value against the field's `allow`\n * vocabulary + the code-owned component registry (the leash), mapping graph\n * issues into plain CMS findings. Never throws — a malformed (non-node)\n * value degrades to a single finding, matching the \"validation is first-class,\n * never a crash\" rule.\n */\nexport function validateComposition(value: unknown, field: BlocksFieldDef): CompositionIssue[] {\n  if (value == null) return []\n  const roots = Array.isArray(value) ? value : [value]\n  if (!roots.every((r) => r != null && typeof r === 'object' && 'componentId' in r)) {\n    return [{ message: 'is not a valid composition (expected component nodes)', severity: 'error' }]\n  }\n  const components = getStudioRegistry().registry.lookup\n  return validateCompositionValue(value as ComponentNode | ComponentNode[], {\n    allow: field.allow,\n    components,\n  }).map((issue) => ({\n    message: issue.message,\n    severity: issue.severity,\n    nodePath: issue.path.join('/'),\n  }))\n}\n\n/**\n * EC-189: validate the composition embeds inside a `richText` field value. Each\n * `componentEmbed` holds a single `ComponentNode` constrained by the field's\n * `allow` vocabulary (the SAME leash a `blocks` field uses). Parse the value, walk\n * its embeds at any depth, and validate each embedded node via\n * `validateCompositionValue`; findings carry the rich-text node path joined with\n * the in-embed graph path. Never throws — a malformed embed degrades to a\n * single finding.\n */\nexport function validateRichTextEmbeds(value: unknown, field: RichTextFieldDef): CompositionIssue[] {\n  if (value == null) return []\n  const parsed = parseRichTextValue(value)\n  // A plain-string / schema-invalid rich-text value carries no embeds to check\n  // here (scalar type validation owns reporting a malformed value).\n  if (!parsed.ok) return []\n  const components = getStudioRegistry().registry.lookup\n  const out: CompositionIssue[] = []\n  for (const occurrence of collectComponentEmbeds(parsed.value.doc)) {\n    if (!occurrence.embedded) {\n      out.push({\n        message: `embed at ${occurrence.nodePath} is missing a valid embedded component`,\n        severity: 'error',\n        nodePath: occurrence.nodePath,\n      })\n      continue\n    }\n    for (const issue of validateCompositionValue(occurrence.embedded, {\n      allow: field.allow,\n      components,\n    })) {\n      out.push({\n        message: issue.message,\n        severity: issue.severity,\n        nodePath: `${occurrence.nodePath}/attrs/node/${issue.path.join('/')}`,\n      })\n    }\n  }\n  return out\n}\n"]}

package/dist/components/cms/cms-labels.d.ts

@@ -0,0 +1,15 @@
+import type { FieldDef } from '@elytracms/core/cms-core';
+/**
+ * Pure label formatters (EC-326) — no `CmsProvider`/store coupling, so
+ * portable surfaces (AD-19: `collection-table.tsx`, `detail-editor.tsx`, and
+ * friends) can format a field label without statically depending on the
+ * 1000+ line `cms-store.tsx` module for a single formatter.
+ */
+/**
+ * A field's display label (EC-241): resolve its (possibly localized) `form.label`,
+ * falling back to the field name. **`locale` defaults to the active UI locale** —
+ * a bare `fieldLabel(field)` localizes a `{ en, de }` map against the browser locale
+ * (via the non-hook `localizedLabel`), so a German editor sees German labels. Pass an
+ * explicit `locale` only to force a specific one (e.g. a content-locale variant view).
+ */
+export declare function fieldLabel(field: FieldDef, locale?: string): string;

package/dist/components/cms/cms-labels.js

@@ -0,0 +1,27 @@
+import { resolveLabel } from '@elytracms/core/cms-core';
+import { localizedLabel, resolveMsgLabel } from '@elytracms/studio/lib/i18n';
+/**
+ * Pure label formatters (EC-326) — no `CmsProvider`/store coupling, so
+ * portable surfaces (AD-19: `collection-table.tsx`, `detail-editor.tsx`, and
+ * friends) can format a field label without statically depending on the
+ * 1000+ line `cms-store.tsx` module for a single formatter.
+ */
+/**
+ * A field's display label (EC-241): resolve its (possibly localized) `form.label`,
+ * falling back to the field name. **`locale` defaults to the active UI locale** —
+ * a bare `fieldLabel(field)` localizes a `{ en, de }` map against the browser locale
+ * (via the non-hook `localizedLabel`), so a German editor sees German labels. Pass an
+ * explicit `locale` only to force a specific one (e.g. a content-locale variant view).
+ */
+export function fieldLabel(field, locale) {
+    // A catalog-backed built-in-rail label (msgLabel) always resolves through the
+    // catalog against the active UI locale, ignoring a content-locale override — a rail
+    // is chrome, not localized content.
+    const chrome = resolveMsgLabel(field.form?.label);
+    if (chrome !== undefined)
+        return chrome;
+    if (locale !== undefined)
+        return resolveLabel(field.form?.label, locale) ?? field.name;
+    return localizedLabel(field.form?.label, field.name);
+}
+//# sourceMappingURL=cms-labels.js.map

package/dist/components/cms/cms-labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms-labels.js","sourceRoot":"","sources":["../../../src/components/cms/cms-labels.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAE5E;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAe,EAAE,MAAe;IACzD,8EAA8E;IAC9E,oFAAoF;IACpF,oCAAoC;IACpC,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACjD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAA;IACvC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,CAAA;IACtF,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;AACtD,CAAC","sourcesContent":["import type { FieldDef } from '@elytracms/core/cms-core'\nimport { resolveLabel } from '@elytracms/core/cms-core'\nimport { localizedLabel, resolveMsgLabel } from '@elytracms/studio/lib/i18n'\n\n/**\n * Pure label formatters (EC-326) — no `CmsProvider`/store coupling, so\n * portable surfaces (AD-19: `collection-table.tsx`, `detail-editor.tsx`, and\n * friends) can format a field label without statically depending on the\n * 1000+ line `cms-store.tsx` module for a single formatter.\n */\n\n/**\n * A field's display label (EC-241): resolve its (possibly localized) `form.label`,\n * falling back to the field name. **`locale` defaults to the active UI locale** —\n * a bare `fieldLabel(field)` localizes a `{ en, de }` map against the browser locale\n * (via the non-hook `localizedLabel`), so a German editor sees German labels. Pass an\n * explicit `locale` only to force a specific one (e.g. a content-locale variant view).\n */\nexport function fieldLabel(field: FieldDef, locale?: string): string {\n  // A catalog-backed built-in-rail label (msgLabel) always resolves through the\n  // catalog against the active UI locale, ignoring a content-locale override — a rail\n  // is chrome, not localized content.\n  const chrome = resolveMsgLabel(field.form?.label)\n  if (chrome !== undefined) return chrome\n  if (locale !== undefined) return resolveLabel(field.form?.label, locale) ?? field.name\n  return localizedLabel(field.form?.label, field.name)\n}\n"]}

package/dist/components/cms/cms-store.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { CmsDocument, CmsValidationIssue, CollectionDef, DocumentRef, FieldDef, Locale, LocaleConfig, RestoreScope } from '@elytracms/core/cms-core';
+import type { CmsDocument, CmsValidationIssue, CollectionDef, CollectionRegistry, DocumentRef, FieldDef, Locale, LocaleConfig, RestoreScope } from '@elytracms/core/cms-core';
 import type { DocumentVersionRecord } from '@elytracms/core/persistence';
 import type { OperationError } from '@elytracms/studio/lib/operations';
 import type { TableViewState } from '@elytracms/studio/lib/cms-views';
@@ -142,6 +142,7 @@ export interface CmsStore {
     /** Await all queued persisted mutations (tests, publish flows). */
     flushPersistence(): Promise<void>;
 }
+declare const useCms: () => CmsStore;
 declare function primaryField(collection: CollectionDef): string;
 /**
  * EC-316 (bug fix) — mint a fresh, COLLISION-FREE document id for `+ New`.
@@ -158,6 +159,26 @@ declare function primaryField(collection: CollectionDef): string;
 export declare function mintDocumentId(collectionId: string, seq: {
     current: number;
 }, existingIds: ReadonlySet<string>): string;
+/**
+ * Build a fresh document for `collectionId`: a collision-free id (EC-316, via
+ * {@link mintDocumentId} against every id `existingDocs` already holds for
+ * this collection) and the collection's declared field defaults (EC-297, via
+ * `seedDefaults`). Pure — the sensitive part of the insert sequence shared by
+ * `createDocument` and `ensureSingletonDocument`'s empty branch (via the
+ * private `insertNewDocument` below), factored out so it's unit-testable
+ * without a `CmsProvider`.
+ */
+export declare function buildNewDocument(collectionId: string, registry: CollectionRegistry, seq: {
+    current: number;
+}, existingDocs: readonly CmsDocument[]): CmsDocument;
+/**
+ * Does `docs` already hold a document for `collectionId`? `ensureSingletonDocument`'s
+ * empty branch re-checks this INSIDE the `setDocuments` updater (against the
+ * latest `prev`, not a stale snapshot) so a concurrent invocation — StrictMode's
+ * double-invoked effect, or a second caller racing the same synchronous guard —
+ * can never materialize a second singleton document.
+ */
+export declare function hasDocumentFor(docs: readonly CmsDocument[], collectionId: string): boolean;
 /**
  * The CMS session store (EC-141): documents and collections are optimistic,
  * synchronous session state (live validation while typing); every mutation —
@@ -181,14 +202,6 @@ export declare function CmsProvider({ children, projectId, initialCollections, i
     /** Locale config for the seeded content; defaults to the sample config. */
     initialLocaleConfig?: LocaleConfig;
 }): import("react").JSX.Element;
-export declare function useCms(): CmsStore;
-/**
- * A field's display label (EC-241): resolve its (possibly localized) `form.label`,
- * falling back to the field name. **`locale` defaults to the active UI locale** —
- * a bare `fieldLabel(field)` localizes a `{ en, de }` map against the browser locale
- * (via the non-hook `localizedLabel`), so a German editor sees German labels. Pass an
- * explicit `locale` only to force a specific one (e.g. a content-locale variant view).
- */
-export declare function fieldLabel(field: FieldDef, locale?: string): string;
+export { useCms };
 export { primaryField };
 export type { Locale };

package/dist/components/cms/cms-store.js

@@ -1,86 +1,20 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
-import { createCollectionRegistry, createDocumentStore, documentKey, documentSchema, resolveDocumentTitle, resolveField, resolveLabel, sampleDocuments, seedDefaults, sampleFilterableCollections, sampleLocaleConfig, samplePublishedKeys, resolveSingletonDocument, titleFieldOf, validateDocument, } from '@elytracms/core/cms-core';
-import { validateCompositionValue } from '@elytracms/core/project-graph';
-import { collectComponentEmbeds, parseRichTextValue } from '@elytracms/core/rich-text';
-import { localizedLabel, resolveMsgLabel, translate } from '@elytracms/studio/lib/i18n';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createCollectionRegistry, createDocumentStore, documentKey, documentSchema, resolveDocumentTitle, resolveField, sampleDocuments, seedDefaults, sampleFilterableCollections, sampleLocaleConfig, samplePublishedKeys, resolveSingletonDocument, titleFieldOf, validateDocument, } from '@elytracms/core/cms-core';
+import { translate } from '@elytracms/studio/lib/i18n';
 import { configureStudioLocales, useStudioLocale } from '@elytracms/studio/lib/locale';
-import { getStudioRegistry, studioManifestLookup } from '@elytracms/studio/lib/registry';
+import { studioManifestLookup } from '@elytracms/studio/lib/registry';
 import { resolveDeploymentCollections } from '@elytracms/studio/lib/workspace';
+import { validateComposition, validateRichTextEmbeds } from './cms-composition-validators';
+import { matchesRef, removeDoc, replaceDoc, upsertDoc } from './document-ref-utils';
+import { createRequiredContext } from '@elytracms/studio/lib/required-context';
 import { createCmsPersister, getStudioOperations } from '@elytracms/studio/lib/operations';
 import { ALL_VIEW_ID, canonicalViewState, configViewsFor, defaultViewState, viewStatesEqual, } from '@elytracms/studio/lib/cms-views';
 import { useOptionalAssets } from '../assets/assets-store';
-import { stagedDocuments } from './document-staging';
+import { consumeStagedDocuments } from './document-staging';
 import { applyCellValue, commitCellEdit } from './cell-edit';
 import { runBulkAction } from './bulk-actions';
-/**
- * EC-188: validate a `blocks` composition field value against the field's `allow`
- * vocabulary + the code-owned component registry (the leash), mapping graph
- * issues into plain CMS findings. Injected into `validateDocument` so cms-core
- * stays free of `@elytracms/core/project-graph`. Never throws — a malformed (non-node)
- * value degrades to a single finding, matching the "validation is first-class,
- * never a crash" rule.
- */
-function validateComposition(value, field) {
-    if (value == null)
-        return [];
-    const roots = Array.isArray(value) ? value : [value];
-    if (!roots.every((r) => r != null && typeof r === 'object' && 'componentId' in r)) {
-        return [{ message: 'is not a valid composition (expected component nodes)', severity: 'error' }];
-    }
-    const components = getStudioRegistry().registry.lookup;
-    return validateCompositionValue(value, {
-        allow: field.allow,
-        components,
-    }).map((issue) => ({
-        message: issue.message,
-        severity: issue.severity,
-        nodePath: issue.path.join('/'),
-    }));
-}
-/**
- * EC-189: validate the composition embeds inside a `richText` field value. Each
- * `componentEmbed` holds a single `ComponentNode` constrained by the field's
- * `allow` vocabulary (the SAME leash a `blocks` field uses). Parse the value, walk
- * its embeds at any depth, and validate each embedded node via
- * `validateCompositionValue`; findings carry the rich-text node path joined with
- * the in-embed graph path. Injected into `validateDocument` so cms-core depends on
- * neither `@elytracms/core/project-graph` nor `@elytracms/core/rich-text`. Never throws — a
- * malformed embed degrades to a single finding.
- */
-function validateRichTextEmbeds(value, field) {
-    if (value == null)
-        return [];
-    const parsed = parseRichTextValue(value);
-    // A plain-string / schema-invalid rich-text value carries no embeds to check
-    // here (scalar type validation owns reporting a malformed value).
-    if (!parsed.ok)
-        return [];
-    const components = getStudioRegistry().registry.lookup;
-    const out = [];
-    for (const occurrence of collectComponentEmbeds(parsed.value.doc)) {
-        if (!occurrence.embedded) {
-            out.push({
-                message: `embed at ${occurrence.nodePath} is missing a valid embedded component`,
-                severity: 'error',
-                nodePath: occurrence.nodePath,
-            });
-            continue;
-        }
-        for (const issue of validateCompositionValue(occurrence.embedded, {
-            allow: field.allow,
-            components,
-        })) {
-            out.push({
-                message: issue.message,
-                severity: issue.severity,
-                nodePath: `${occurrence.nodePath}/attrs/node/${issue.path.join('/')}`,
-            });
-        }
-    }
-    return out;
-}
-const CmsContext = createContext(null);
+const { Context: CmsContext, useRequired: useCms } = createRequiredContext('Cms');
 function primaryField(collection) {
     return titleFieldOf(collection)?.name ?? collection.fields[0]?.name ?? 'id';
 }
@@ -104,6 +38,31 @@ export function mintDocumentId(collectionId, seq, existingIds) {
     } while (existingIds.has(id));
     return id;
 }
+/**
+ * Build a fresh document for `collectionId`: a collision-free id (EC-316, via
+ * {@link mintDocumentId} against every id `existingDocs` already holds for
+ * this collection) and the collection's declared field defaults (EC-297, via
+ * `seedDefaults`). Pure — the sensitive part of the insert sequence shared by
+ * `createDocument` and `ensureSingletonDocument`'s empty branch (via the
+ * private `insertNewDocument` below), factored out so it's unit-testable
+ * without a `CmsProvider`.
+ */
+export function buildNewDocument(collectionId, registry, seq, existingDocs) {
+    const existingIds = new Set(existingDocs.filter((d) => d.collection === collectionId).map((d) => d.id));
+    const id = mintDocumentId(collectionId, seq, existingIds);
+    const collection = registry.get(collectionId);
+    return { collection: collectionId, id, values: collection ? seedDefaults(collection) : {} };
+}
+/**
+ * Does `docs` already hold a document for `collectionId`? `ensureSingletonDocument`'s
+ * empty branch re-checks this INSIDE the `setDocuments` updater (against the
+ * latest `prev`, not a stale snapshot) so a concurrent invocation — StrictMode's
+ * double-invoked effect, or a second caller racing the same synchronous guard —
+ * can never materialize a second singleton document.
+ */
+export function hasDocumentFor(docs, collectionId) {
+    return docs.some((d) => d.collection === collectionId);
+}
 /** The unnamed built-in view: no filters, no sort, every field visible. */
 function defaultView(collection) {
     return {
@@ -124,16 +83,14 @@ function defaultView(collection) {
 export function CmsProvider({ children, projectId, initialCollections, initialDocuments, initialPublishedKeys, initialLocaleConfig, }) {
     const [documents, setDocuments] = useState(() => {
         const seeded = (initialDocuments ?? sampleDocuments).map((d) => structuredClone(d));
-        // EC-320: merge any documents STAGED by the Components-view "Use in document…"
-        // transfer (a playground cross-mount handoff — see document-staging). Staged
-        // wins by id; empty in Convex mode, where hydration is the source of truth.
-        const staged = stagedDocuments(projectId);
-        if (staged.length === 0)
-            return seeded;
-        const byKey = new Map(seeded.map((d) => [`${d.collection}/${d.id}`, d]));
-        for (const d of staged)
-            byKey.set(`${d.collection}/${d.id}`, d);
-        return [...byKey.values()];
+        // EC-320 (0.0.44 follow-up): merge any documents STAGED by the
+        // Components-view "Use in document…" transfer — a cross-mount handoff in
+        // EVERY mode now (see document-staging.ts), not just the playground. The
+        // merge rule itself stays mode-aware there: playground's seeded set is a
+        // static baseline that never reflects a write (staged always wins);
+        // Convex's is a fresh per-mount hydration query (staged fills gaps only,
+        // dropped once the seeded set actually carries the key).
+        return consumeStagedDocuments(projectId, seeded);
     });
     // Published-ness as the version POINTER (EC-224), decoupled from the flat
     // `state` enum: seeded from hydration's pointer set, or — when none is supplied
@@ -209,9 +166,9 @@ export function CmsProvider({ children, projectId, initialCollections, initialDo
         configureStudioLocales(localeConfig);
     }, [localeConfig]);
     const getCollection = useCallback((id) => registry.get(id), [registry]);
-    const getDocument = useCallback((ref) => documents.find((d) => d.collection === ref.collection && d.id === ref.id), [documents]);
+    const getDocument = useCallback((ref) => documents.find((d) => matchesRef(d, ref)), [documents]);
     const titleOf = useCallback((ref) => {
-        const doc = documents.find((d) => d.collection === ref.collection && d.id === ref.id);
+        const doc = documents.find((d) => matchesRef(d, ref));
         const collection = registry.get(ref.collection);
         if (!doc || !collection)
             return ref.id;
@@ -232,18 +189,15 @@ export function CmsProvider({ children, projectId, initialCollections, initialDo
         return typeof value === 'string' && value ? value : ref.id;
     }, [documents, registry, localeConfig, activeLocale]);
     const saveDocument = useCallback((doc) => {
-        setDocuments((prev) => {
-            const i = prev.findIndex((d) => d.collection === doc.collection && d.id === doc.id);
-            if (i < 0)
-                return [...prev, doc];
-            const next = [...prev];
-            next[i] = doc;
-            return next;
-        });
+        // Replace-or-append (upsert): a brand-new document must still land even
+        // though nothing in the session matches its ref yet.
+        setDocuments((prev) => upsertDoc(prev, doc));
         persisterRef.current?.upsertDocument(doc);
     }, []);
     const commitFieldEdit = useCallback((input) => {
-        const replaceWith = (doc) => setDocuments((prev) => prev.map((d) => (d.collection === doc.collection && d.id === doc.id ? doc : d)));
+        // Pure map-replace: an edit always targets a document already open in
+        // the session, so a miss (already gone) is a no-op, never an append.
+        const replaceWith = (doc) => setDocuments((prev) => replaceDoc(prev, doc));
         const persister = persisterRef.current;
         return commitCellEdit({
             registry,
@@ -264,22 +218,24 @@ export function CmsProvider({ children, projectId, initialCollections, initialDo
                 : {}),
         }, input);
     }, [registry, localeConfig, projectId]);
-    const createDocument = useCallback((collectionId) => {
-        // EC-316: never reissue an id a document (this session's or a prior
-        // one's) already holds — see `mintDocumentId`.
-        const existingIds = new Set(documentsRef.current.filter((d) => d.collection === collectionId).map((d) => d.id));
-        const id = mintDocumentId(collectionId, seq, existingIds);
-        // EC-297: seed the collection's declared field defaults at create time.
-        const collection = registry.get(collectionId);
-        const doc = {
-            collection: collectionId,
-            id,
-            values: collection ? seedDefaults(collection) : {},
-        };
-        setDocuments((prev) => [...prev, doc]);
+    // Shared insert sequence (EC-326): existingIds/mint/seedDefaults (via
+    // `buildNewDocument`) + optimistic append + persist, consumed by both
+    // `createDocument` (always inserts) and `ensureSingletonDocument`'s empty
+    // branch (`guardExisting: true` — re-checks "no document for this collection
+    // yet" against the LATEST `prev` inside the `setDocuments` updater, not the
+    // `documentsRef.current` snapshot the caller already checked, so a
+    // concurrent invocation — StrictMode's double-invoked effect — can never
+    // materialize a second singleton document).
+    const insertNewDocument = useCallback((collectionId, options) => {
+        const doc = buildNewDocument(collectionId, registry, seq, documentsRef.current);
+        setDocuments((prev) => options?.guardExisting && hasDocumentFor(prev, collectionId) ? prev : [...prev, doc]);
         persisterRef.current?.upsertDocument(doc);
-        return { collection: collectionId, id };
+        return doc;
     }, [registry]);
+    const createDocument = useCallback((collectionId) => {
+        const doc = insertNewDocument(collectionId);
+        return { collection: collectionId, id: doc.id };
+    }, [insertNewDocument]);
     // EC-274 (re-scopes EC-217): a singleton is a UI lens, not a fixed id. Resolve
     // the collection's lone document and return its ref; if none exists yet, create
     // one with a NORMAL generated id (never the collection id — no code ever names a
@@ -308,22 +264,14 @@ export function CmsProvider({ children, projectId, initialCollections, initialDo
             return { collection: collectionId, id: `new-${collectionId}-pending` };
         }
         ensuredSingletons.current.add(collectionId);
-        // EC-316: same collision-free mint as `createDocument` (defensive here —
-        // the singleton-empty branch only runs when no document exists yet).
-        const existingIds = new Set(documentsRef.current.filter((d) => d.collection === collectionId).map((d) => d.id));
-        const id = mintDocumentId(collectionId, seq, existingIds);
-        // EC-297: seed the singleton's declared field defaults at create time.
-        const doc = {
-            collection: collectionId,
-            id,
-            values: collection ? seedDefaults(collection) : {},
-        };
-        setDocuments((prev) => prev.some((d) => d.collection === collectionId) ? prev : [...prev, doc]);
-        persisterRef.current?.upsertDocument(doc);
-        return { collection: collectionId, id };
-    }, [registry]);
+        // EC-316: same collision-free mint as `createDocument` (via the shared
+        // `insertNewDocument` — defensive here, the singleton-empty branch only
+        // runs when no document exists yet).
+        const doc = insertNewDocument(collectionId, { guardExisting: true });
+        return { collection: collectionId, id: doc.id };
+    }, [registry, insertNewDocument]);
     const deleteDocument = useCallback((ref) => {
-        setDocuments((prev) => prev.filter((d) => !(d.collection === ref.collection && d.id === ref.id)));
+        setDocuments((prev) => removeDoc(prev, ref));
         persisterRef.current?.deleteDocument(ref);
     }, []);
     // EC-224: published-ness IS the version pointer (`publishedKeys`) — the SOLE
@@ -412,7 +360,9 @@ export function CmsProvider({ children, projectId, initialCollections, initialDo
             return null;
         }
         const restored = result.value.document;
-        setDocuments((prev) => prev.map((d) => d.collection === restored.collection && d.id === restored.id ? restored : d));
+        // Pure map-replace: a restore always targets a document already open in
+        // the session.
+        setDocuments((prev) => replaceDoc(prev, restored));
         return restored;
     }, [projectId]);
     const validate = useCallback((doc) => validateDocument(registry, doc, {
@@ -462,17 +412,10 @@ export function CmsProvider({ children, projectId, initialCollections, initialDo
                 accepted.push(doc);
         }
         if (accepted.length > 0) {
-            setDocuments((prev) => {
-                const next = [...prev];
-                for (const doc of accepted) {
-                    const i = next.findIndex((d) => d.collection === doc.collection && d.id === doc.id);
-                    if (i < 0)
-                        next.push(doc);
-                    else
-                        next[i] = doc;
-                }
-                return next;
-            });
+            // Replace-or-append (upsert): an imported row may be brand new to the
+            // session, so each accepted document must land even with no prior
+            // entry for its ref.
+            setDocuments((prev) => accepted.reduce((acc, doc) => upsertDoc(acc, doc), prev));
             for (const doc of accepted)
                 persisterRef.current?.upsertDocument(doc);
             // EC-224: imports land as the working DRAFT. Publish-ness is the version
@@ -556,7 +499,7 @@ export function CmsProvider({ children, projectId, initialCollections, initialDo
                 // set-field: upsert the document carrying the new value. The write
                 // path self-types it through the schema lens (EC-277); a scalar field
                 // stores its scalar as-is.
-                const current = documentsRef.current.find((d) => d.collection === ref.collection && d.id === ref.id);
+                const current = documentsRef.current.find((d) => matchesRef(d, ref));
                 if (!current) {
                     return Promise.resolve({
                         ok: false,
@@ -590,10 +533,12 @@ export function CmsProvider({ children, projectId, initialCollections, initialDo
             // `state` mirror to keep in sync (published-ness is derived from the
             // pointer set).
             applyState: (ref, state) => setPublished(ref, state === 'published'),
-            applyDelete: (ref) => setDocuments((prev) => prev.filter((d) => !(d.collection === ref.collection && d.id === ref.id))),
+            applyDelete: (ref) => setDocuments((prev) => removeDoc(prev, ref)),
             // EC-247: fold the new value into the session document (same
-            // locale-aware path the dispatched upsert used).
-            applySetField: (ref) => setDocuments((prev) => prev.map((d) => d.collection === ref.collection && d.id === ref.id ? setFieldDoc(d) : d)),
+            // locale-aware path the dispatched upsert used). Not a plain
+            // `replaceDoc` — the replacement is computed FROM each matched
+            // document (`setFieldDoc(d)`), not a fixed value to swap in.
+            applySetField: (ref) => setDocuments((prev) => prev.map((d) => (matchesRef(d, ref) ? setFieldDoc(d) : d))),
             ...(dispatch ? { dispatch } : {}),
         }, collectionId, ids, action, setField);
     }, [projectId, titleOf, registry, localeConfig, activeLocale, setPublished, assetExists]);
@@ -682,29 +627,6 @@ export function CmsProvider({ children, projectId, initialCollections, initialDo
     ]);
     return _jsx(CmsContext.Provider, { value: store$, children: children });
 }
-export function useCms() {
-    const store = useContext(CmsContext);
-    if (!store)
-        throw new Error('useCms must be used within a <CmsProvider>.');
-    return store;
-}
-/**
- * A field's display label (EC-241): resolve its (possibly localized) `form.label`,
- * falling back to the field name. **`locale` defaults to the active UI locale** —
- * a bare `fieldLabel(field)` localizes a `{ en, de }` map against the browser locale
- * (via the non-hook `localizedLabel`), so a German editor sees German labels. Pass an
- * explicit `locale` only to force a specific one (e.g. a content-locale variant view).
- */
-export function fieldLabel(field, locale) {
-    // A catalog-backed built-in-rail label (msgLabel) always resolves through the
-    // catalog against the active UI locale, ignoring a content-locale override — a rail
-    // is chrome, not localized content.
-    const chrome = resolveMsgLabel(field.form?.label);
-    if (chrome !== undefined)
-        return chrome;
-    if (locale !== undefined)
-        return resolveLabel(field.form?.label, locale) ?? field.name;
-    return localizedLabel(field.form?.label, field.name);
-}
+export { useCms };
 export { primaryField };
 //# sourceMappingURL=cms-store.js.map