@elytracms/studio 0.0.80 → 0.0.81

package/dist/components/app-views/default-modules.js

@@ -1,13 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect } from 'react';
 import { Blocks, Database, FileCog, Image, LayoutGrid, Puzzle, Settings as SettingsIcon, Signpost, Users, } from 'lucide-react';
-import { assetCollection, extendCollectionDef, isSingleton, resolveSingletonDocument, sampleDocuments, } from '@elytracms/core/cms-core';
-import { reconcileSeedDocumentLocalization } from '@elytracms/core/persistence';
+import { assetCollection, extendCollectionDef, isSingleton, resolveSingletonDocument, } from '@elytracms/core/cms-core';
 import { NavigateOnce, STUDIO_PROJECT_ROUTE, studioPath } from '@elytracms/studio/router';
 import { Text } from '@elytracms/studio/ui';
 import { localizedLabel, translate } from '@elytracms/studio/lib/i18n';
 import { getInstantiatedKit } from '@elytracms/studio/lib/starters/kit-session';
-import { isPlaygroundMode } from '@elytracms/studio/lib/persistence';
 import { resolveDeploymentCollections, resolveDeploymentLocaleConfig } from '@elytracms/studio/lib/workspace';
 import { cmsDeepLink, componentsDeepLink, usersDeepLink, redirectsDeepLink, assetsDeepLink, groupNode, separatorNode, viewNode, } from './module.js';
 import { SectionSurface } from '../section-surface.js';
@@ -32,29 +30,95 @@ import { OperationErrorBanner } from '../operation-error.js';
 function slugify(label) {
     return label.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'view';
 }
-/** Derive a stable, deterministic id from the CMS focus (overridable via `config.id`). */
-function cmsViewId(config) {
+/**
+ * The auto-parent namespace for a ONE-ITEM `collections` group (EC-468).
+ *
+ * A PREFIX, not a suffix, and deliberately so: every other derived CMS id starts with
+ * `cms:`, so the 4th character (`-` here, `:` there) makes the two namespaces disjoint
+ * BY CONSTRUCTION — no collection id, whatever it contains, can forge a `cms-group:`
+ * id, whereas a suffix marker (`cms:page:group`) would be forged by a collection
+ * literally named `page:group` (`collectionDefSchema.id` is `z.string().min(1)` —
+ * nothing reserves `:` or `-`).
+ */
+const CMS_GROUP_ID_PREFIX = 'cms-group:';
+/**
+ * Derive a stable, deterministic id from the CMS focus (overridable via `config.id`).
+ *
+ * The id is the route segment, the rail's active-state key AND the override key
+ * (EC-311), so it must be injective: two focuses deriving one id means
+ * `resolveOverrides` drops the later view. The derived shapes:
+ *
+ * | focus                        | id                        |
+ * | ---------------------------- | ------------------------- |
+ * | none                         | `cms`                     |
+ * | `collection: 'page'` (leaf)  | `cms:page`                |
+ * | `collections: ['a','b']`     | `cms:a-b`                 |
+ * | `collections: ['page']`      | `cms-group:page`          |
+ *
+ * EC-468 — why the one-item group is its own namespace: `cms:${join(L)}` of a
+ * single-element list IS that element, so the auto-generated PARENT took the very id
+ * its own auto-expanded child derives (`cmsCollectionLeaf` → `cmsView({ collection })`).
+ * Both landed in the one flat override list `resolveSidebar` feeds `resolveOverrides`,
+ * so the child was dropped with a `duplicate-override-id` error and the parent rendered
+ * childless — a forced collision no config could avoid. Nothing else changes: the leaf
+ * and the multi-collection join keep their exact ids (consumer rails route on them).
+ *
+ * EC-477 — `-` is a SEPARATOR here, and a collection id may legally contain one, so a
+ * collection literally named `a-b` derives the same `cms:a-b` as a `['a','b']` group.
+ * That ambiguity is NOT closed by constraining collection ids (a permanent, repo-wide
+ * naming ban to fix a two-config coincidence, when hyphenated ids are ordinary — see
+ * the task's Done); it is DETECTED where both facts are known, by
+ * {@link checkSidebarIdKeyspace}, which raises a `derived-id-collision` the moment a
+ * group's join equals a real collection id. The escape hatch is unchanged: an explicit
+ * `nav.cms({ id })` always wins, and the derivation below is untouched — consumer rails
+ * route on these ids.
+ */
+export function cmsViewId(config) {
     if (config.id)
         return config.id;
     if (config.collection)
         return `cms:${config.collection}`;
-    if (config.collections && config.collections.length > 0) {
-        return `cms:${[...config.collections].join('-')}`;
+    const collections = config.collections;
+    if (collections && collections.length > 0) {
+        if (collections.length === 1)
+            return `${CMS_GROUP_ID_PREFIX}${collections[0]}`;
+        return `cms:${joinCollectionIds(collections)}`;
     }
     return 'cms';
 }
+/** The multi-collection focus join — ONE definition, so the id and the EC-477 check cannot drift. */
+function joinCollectionIds(collections) {
+    return [...collections].join('-');
+}
+/**
+ * The id provenance a CMS focus carries for diagnostics (EC-477) — set only for the one
+ * derived shape that is genuinely ambiguous: a MULTI-collection join. An explicit `id`,
+ * a single-collection leaf and the one-item `cms-group:` parent are all unambiguous by
+ * construction (EC-468), so they carry nothing and are never diagnosed.
+ */
+function cmsDerivedId(config) {
+    if (config.id || config.collection)
+        return undefined;
+    const collections = config.collections;
+    if (!collections || collections.length < 2)
+        return undefined;
+    return { from: 'collection-join', collections: [...collections] };
+}
 /**
  * Build a CMS view — the default `cms` view, or a focused instance. Every instance
  * shares one surface ({@link CmsScreen}); `collections` narrows the sidebar + index
  * to a subset, `collection` is a single-collection lens that opens straight into
  * that collection's list. The id is derived from the focus (deterministic, stable
- * across rail reorders) unless `id` is given — so two focused views never collide.
+ * across rail reorders) unless `id` is given — see {@link cmsViewId} for the derived
+ * shapes and the one keyspace ambiguity that survives.
  */
 export function cmsView(config = {}) {
     const single = config.collection;
     const focus = single ? [single] : config.collections;
+    const derivedId = cmsDerivedId(config);
     return {
         id: cmsViewId(config),
+        ...(derivedId ? { derivedId } : {}),
         // Lazy label/description (EC-241): the sidebar is built when the consumer's
         // `studio.config` module loads — BEFORE `createStudio` seeds the i18n config — so
         // resolving here would bake English. A getter defers resolution to render, when
@@ -255,10 +319,22 @@ export function builderView() {
             }, replace: true })),
     };
 }
-/** Build a fully custom view (the `nav.view(...)` escape hatch). */
+/**
+ * Build a fully custom view (the `nav.view(...)` escape hatch).
+ *
+ * With no `id` the id is a SLUG of the label, and that slug carries a
+ * {@link DerivedViewId} marker (EC-476): a label is a display string a developer picks
+ * freely, so `label: 'CMS'` deriving `cms` is a coincidence, not a request to replace
+ * the built-in CMS surface. {@link checkSidebarIdKeyspace} refuses the takeover and
+ * says so; an explicit `id` carries no marker and keeps the documented replacement.
+ */
 export function customView(config) {
+    const derivedId = config.id
+        ? undefined
+        : { from: 'label', label: config.label };
     return {
         id: config.id ?? slugify(config.label),
+        ...(derivedId ? { derivedId } : {}),
         label: config.label,
         description: config.description ?? config.label,
         icon: config.icon ?? LayoutGrid,
@@ -284,6 +360,97 @@ export const DEFAULT_VIEWS = [
     settingsView(),
     builderView(),
 ];
+/**
+ * Every id the engine already owns — the replacement targets of the sidebar seam,
+ * INCLUDING the hidden `builder` redirect (it is in the keyspace even though the stock
+ * rail does not list it, so a derived id can swallow it just the same).
+ */
+export const BUILTIN_VIEW_IDS = new Set(DEFAULT_VIEWS.map((view) => view.id));
+/** The extension point these issues are located at — the same literal `resolveSidebar` stamps. */
+const SIDEBAR_POINT = 'sidebar';
+/**
+ * The catalog keys for the two keyspace findings (EC-478). This module stays pure —
+ * it names a key and its identifier values; `lib/persona/labels.ts` resolves them at
+ * the render site, so the rail foot localizes as one list.
+ */
+const KEYSPACE_KEYS = {
+    builtinCollision: 'customization.issue.derivedIdBuiltinCollision',
+    collectionCollision: 'customization.issue.derivedIdCollectionCollision',
+};
+/**
+ * EC-476/477 — guard the sidebar id keyspace against ids that were DERIVED rather than
+ * declared, and landed somewhere that already means something.
+ *
+ * The seam's replacement rule is id equality (`resolveOverrides`: an entry whose id is a
+ * default's id replaces it). That is exactly right for an id the developer TYPED, and
+ * exactly wrong for one a builder computed — and the generic core cannot tell them
+ * apart, because by the time an entry reaches it, an id is just a string. So the rule
+ * lives HERE, next to the derivations that produce it ({@link slugify},
+ * {@link cmsViewId}) and next to {@link DEFAULT_VIEWS}, the set it has to protect.
+ *
+ * Two derived shapes, two different remedies — because the cost of being wrong differs:
+ *
+ * - **A slugged LABEL landing on a built-in id (EC-476) is REJECTED** (`error`). Losing
+ *   a whole built-in surface — the CMS, Assets, the users roster — to a coincidence of
+ *   spelling is far worse than one custom view not appearing, and the developer's fix is
+ *   a one-line explicit `id`. The built-in is kept, so nothing disappears.
+ * - **A collection JOIN equal to a real collection id (EC-477) is KEPT** (`warning`).
+ *   Nothing here is a takeover: the group's id is legitimate, it is merely no longer
+ *   unique to it, so dropping the view would destroy a rail item the developer
+ *   explicitly declared in order to report a naming clash. Reporting is the whole fix.
+ *
+ * Pure and deterministic — the house "extract the core, test the core" shape.
+ * `builtinIds` and `collections` are parameters so the rule is testable against a
+ * synthetic keyspace, not just the live one.
+ */
+export function checkSidebarIdKeyspace(views, collections = [], builtinIds = BUILTIN_VIEW_IDS) {
+    const collectionIds = new Set(collections.map((collection) => collection.id));
+    const kept = [];
+    const issues = [];
+    for (const view of views) {
+        const derived = view.derivedId;
+        // EC-476 — an auto-derived id must never claim a built-in surface.
+        if (derived?.from === 'label' && builtinIds.has(view.id)) {
+            issues.push({
+                code: 'derived-id-collision',
+                severity: 'error',
+                message: `View "${derived.label}" for "${SIDEBAR_POINT}" derives the id "${view.id}" from its label, which is the built-in "${view.id}" view — the built-in is kept and this view is ignored. Pass an explicit id to replace a built-in on purpose.`,
+                messageRef: {
+                    key: KEYSPACE_KEYS.builtinCollision,
+                    vars: { label: derived.label, point: SIDEBAR_POINT, id: view.id },
+                },
+                point: SIDEBAR_POINT,
+                id: view.id,
+            });
+            continue;
+        }
+        // EC-477 — a multi-collection join that a single collection could equally have produced.
+        if (derived?.from === 'collection-join' && collectionIds.has(joinCollectionIds(derived.collections))) {
+            issues.push({
+                code: 'derived-id-collision',
+                severity: 'warning',
+                message: `View id "${view.id}" for "${SIDEBAR_POINT}" is ambiguous: it joins the collections ${quotedIds(derived.collections)} with "-", and a collection is literally named "${joinCollectionIds(derived.collections)}" — its own lens derives the same id. Pass an explicit id to this group.`,
+                messageRef: {
+                    key: KEYSPACE_KEYS.collectionCollision,
+                    vars: {
+                        id: view.id,
+                        point: SIDEBAR_POINT,
+                        collections: quotedIds(derived.collections),
+                        joined: joinCollectionIds(derived.collections),
+                    },
+                },
+                point: SIDEBAR_POINT,
+                id: view.id,
+            });
+        }
+        kept.push(view);
+    }
+    return { views: kept, issues };
+}
+/** `"a", "b"` — a readable id list for an issue message (the EC-467 issue-copy shape). */
+function quotedIds(ids) {
+    return ids.map((id) => `"${id}"`).join(', ');
+}
 /**
  * The `nav` namespace — the single typed builder for `studio.config.tsx`'s section
  * rail. Each call returns a {@link SidebarViewNode} (or a group / separator) that
@@ -313,6 +480,8 @@ export const nav = {
      * The CMS view. `nav.cms()` / `nav.cms({ collections })` is a PARENT that nests its
      * collections in the rail (each a focused `cms:<id>` lens); `nav.cms({ collection })`
      * is a single-collection LEAF; `nav.cms({ children })` supplies explicit children.
+     * A one-item `collections` group is a parent whose id is `cms-group:<id>`, distinct
+     * from its single child by construction (EC-468 — see {@link cmsViewId}).
      */
     cms: (config = {}) => {
         const view = withNavPermission(cmsView(config), config);
@@ -360,59 +529,47 @@ function ComponentsScreen({ projectId, componentId, state, }) {
     return (_jsxs("div", { className: "flex h-full min-h-0", children: [_jsx("aside", { className: "hidden h-full min-h-0 w-[300px] shrink-0 border-r border-border md:block", children: _jsx(RegistryBrowser, { projectId: projectId, activeComponentId: componentId ?? undefined }) }), _jsx("div", { className: "min-h-0 flex-1 overflow-auto", children: componentId === null ? (_jsx(ComponentsIndex, { projectId: projectId })) : (_jsx(ComponentDetail, { projectId: projectId, componentId: componentId })) })] }));
 }
 /**
- * The CMS schema source for a project mount (bug fix, playground-collections):
- * a hydrated session wins (Convex), then a kit's imported schema (EC-119), then —
- * in playground mode only — the active project's config-declared collections
- * (AD-11, `resolveDeploymentCollections`). Without this last fallback, a non-kit
- * playground project has no hydrated session (`null`, by design — see
- * `project-session.tsx`) and no kit, so `CmsProvider` fell through to the core's
- * hardcoded `sampleFilterableCollections` fixture instead of the project's own
- * on-disk schema. Convex mode's first-run `null` is untouched — it still seeds
- * from the fixture there, as before. `playground` defaults to the live
- * {@link isPlaygroundMode} but is overridable so this stays unit testable
- * without stubbing the env (same seam as `resolveBackendConfig`).
+ * The CMS schema source for a project mount: a hydrated session wins (Convex),
+ * then a kit's imported schema (EC-119), then the active project's
+ * config-declared collections (AD-11, `resolveDeploymentCollections`).
+ *
+ * EC-479 — every rung is the PROJECT's own schema and there is no rung after
+ * them. The config rung used to be gated on playground mode, because outside it
+ * the `undefined` return let `CmsProvider` fall through to `cms-core`'s
+ * `sampleFilterableCollections` fixture — the engine's demo schema, shown as the
+ * project's, offering `filterable` fields the project's real backend would
+ * reject. With that fallback retired the gate has nothing left to protect: the
+ * Convex adapter is itself constructed with `resolveDeploymentCollections()`
+ * (`lib/persistence/index.ts`), so config collections are what connected mode
+ * serves too. Dropping it also DISSOLVES the EC-467 two-source divergence — the
+ * section rail reads `resolveDeploymentCollections()` directly, and now so does
+ * the store's last rung, so the two can no longer disagree.
  */
-export function resolveCmsInitialCollections(cms, kit, playground = isPlaygroundMode()) {
-    return cms?.collections ?? kit?.collections ?? (playground ? resolveDeploymentCollections() : undefined);
+export function resolveCmsInitialCollections(cms, kit) {
+    return cms?.collections ?? kit?.collections ?? resolveDeploymentCollections();
 }
 /**
- * The CMS documents source for a project mount (EC-424) — the document-side
- * twin of {@link resolveCmsInitialCollections}, same ladder: a hydrated session
- * wins (Convex), then a kit's imported documents, then — in playground mode
- * only, and only when a config project actually resolved collections — the
- * engine's own `sampleDocuments` fixture RECONCILED against them.
+ * The CMS documents source for a project mount — the document-side twin of
+ * {@link resolveCmsInitialCollections}: a hydrated session wins (Convex), then a
+ * kit's imported documents, then **nothing**.
  *
- * Without this, a config project whose OWN schema diverges from the shared
- * fixture's localization (e.g. this repo's demo declares `post.slug` localized,
- * EC-315, while the engine's `postCollection` fixture deliberately does not)
- * left `CmsProvider` falling straight through to the un-reconciled
- * `sampleDocuments` default — the CMS surfaces' `initialCollections` already
- * reflected the config schema (via the fallback above), but `initialDocuments`
- * did not, so every seeded post showed EC-390's shape-aware validation's
- * `plain-value` warning + `missing-localized-value` error, standing noise a
- * project never actually wrote.
+ * EC-479 — the third rung used to be the engine's own `sampleDocuments` fixture,
+ * reconciled against the project's schema (EC-424). Reconciling it was already an
+ * admission that the content was foreign: EC-424 existed only because the demo
+ * declares `post.slug` localized while the shared fixture stores it plain, so the
+ * seeded posts carried standing validation noise no project had written. The
+ * honest fix is not a better reconciliation but no foreign content at all — a
+ * studio whose config did not arrive now shows an empty CMS and a visible issue
+ * at the rail, not six documents about Ada Lovelace wearing the project's schema.
  *
- * This is the STATIC-baseline twin of `reconcileSeedDocumentLocalization`
- * (`@elytracms/core/persistence`, wired into the seeded persistence adapter for
- * Convex-mode/delivery reads): no adapter round-trip, so the EC-138/EC-320
- * synchronous-first-render contract (`project-session.tsx`: "CMS surfaces keep
- * their fixture baseline") is untouched. `collections` defaults to the SAME
- * resolution `resolveCmsInitialCollections` returns, so the two stay in lockstep
- * by construction; only reconciles when that resolved to a non-empty config
- * schema (env-only playground, with nothing config-declared, is unaffected).
+ * The playground keeps its world through the ordinary path, not through here: its
+ * seeded in-memory adapter IS a persisted backend behind the operations seam
+ * (AD-17), so `CmsSessionGate` hydrates it and the first rung answers. What that
+ * adapter seeds is `persistence/seed.ts`'s business — EC-475 (project-defined seed
+ * content) owns it.
  */
-export function resolveCmsInitialDocuments(cms, kit, collections = resolveCmsInitialCollections(cms, kit)) {
-    if (cms)
-        return cms.documents;
-    if (kit)
-        return kit.documents;
-    if (!collections || collections.length === 0)
-        return undefined;
-    const collectionsById = new Map(collections.map((collection) => [collection.id, collection]));
-    return sampleDocuments.map((doc) => {
-        const collection = collectionsById.get(doc.collection);
-        return collection ? reconcileSeedDocumentLocalization(doc, collection) : doc;
-    });
+export function resolveCmsInitialDocuments(cms, kit) {
+    return cms?.documents ?? kit?.documents;
 }
 /**
  * The CMS locale config for a project mount (EC-357 finding #3). Locales are
@@ -421,18 +578,28 @@ export function resolveCmsInitialDocuments(cms, kit, collections = resolveCmsIni
  * wiring only applied the project's locale settings on a HYDRATED session, so a
  * playground boot — or a connected FIRST RUN with nothing persisted yet — fell
  * back to a kit's locales or the core's sample `en/de` fixture and the switcher
- * showed `EN·/DE` against a `locales: ['de']` config. Without a config project
- * (env-only wiring) the previous ladder is unchanged: hydrated project settings,
- * then the kit's locales, then the sample fixture (via `CmsProvider`'s default).
+ * showed `EN·/DE` against a `locales: ['de']` config.
+ *
+ * EC-479/EC-483 — the ladder is now TOTAL, and every rung is the project's own:
+ * config-declared locales, then (hydrated) its persisted settings, then a kit's,
+ * then its settings regardless. A `Project` only ever exists for a config-declared
+ * project (`studio-context.tsx`: `configProjects()`), so `project.settings` is
+ * config-derived too — which is what lets the CMS session require a locale instead
+ * of borrowing the engine's `en/de` fixture. The default locale is the literal
+ * storage key for every localized value, so a guessed one is a data migration.
  * `configLocales` is a parameter purely so the ladder is unit-testable (same seam
  * pattern as {@link resolveCmsInitialCollections}).
  */
 export function resolveCmsInitialLocaleConfig(cms, kit, project, configLocales = resolveDeploymentLocaleConfig()) {
+    const projectSettings = {
+        default: project.settings.defaultLocale,
+        locales: [...project.settings.locales],
+    };
     if (configLocales)
         return configLocales;
     if (cms)
-        return { default: project.settings.defaultLocale, locales: [...project.settings.locales] };
-    return kit?.localeConfig;
+        return projectSettings;
+    return kit?.localeConfig ?? projectSettings;
 }
 /**
  * CMS section: hydrates the persisted (or kit-seeded) collections + documents, then
@@ -450,10 +617,7 @@ function CmsScreen({ project, collectionId, documentId, state, field, focusColle
     // A project created from a starter kit (EC-119) opens the CMS on the kit's schemas + content.
     const kit = getInstantiatedKit(projectId);
     return (_jsx(CmsSessionGate, { children: (cms) => {
-            // EC-424: resolved once so `initialDocuments`' reconciliation (below)
-            // stays in lockstep with the SAME collections `initialCollections` uses.
-            const initialCollections = resolveCmsInitialCollections(cms, kit);
-            return (_jsx(CmsProvider, { projectId: projectId, initialCollections: initialCollections, initialDocuments: resolveCmsInitialDocuments(cms, kit, initialCollections), initialPublishedKeys: cms?.publishedKeys, initialTimestamps: cms?.timestamps, initialPublishTimestamps: cms?.publishTimestamps, initialChangedKeys: cms?.changedKeys, initialLocaleConfig: resolveCmsInitialLocaleConfig(cms, kit, project), 
+            return (_jsx(CmsProvider, { projectId: projectId, initialCollections: resolveCmsInitialCollections(cms, kit), initialDocuments: resolveCmsInitialDocuments(cms, kit), initialPublishedKeys: cms?.publishedKeys, initialTimestamps: cms?.timestamps, initialPublishTimestamps: cms?.publishTimestamps, initialChangedKeys: cms?.changedKeys, initialLocaleConfig: resolveCmsInitialLocaleConfig(cms, kit, project), 
                 // EC-461: a hydrated mount (cms non-null — both modes now) seeds the
                 // CURRENT persisted state, so staged docs are superseded by it; only
                 // a static kit/fixture seed lets staged entries win.