@elytracms/studio 0.0.17 → 0.0.19

package/dist/components/app-views/module.d.ts

@@ -1,35 +1,38 @@
 import type { ReactNode } from 'react';
 import type { LucideIcon } from 'lucide-react';
-import type { AppViewEntry, CustomizationIssue, Project, SectionAvailability, SectionId } from '@elytracms/core/studio-core';
+import type { Project, SectionAvailability, SectionId } from '@elytracms/core/studio-core';
+import type { CollectionDef } from '@elytracms/core/cms-core';
 import type { StudioSearch } from '@elytracms/studio/router/search';
 /**
- * EC-239 — the app-view module contract, an instance of the EC-236 customization
- * seam.
+ * The studio **view** contract + the **sidebar node** model — the internal types
+ * the consumer-facing `nav.*` builders (EC-237/239, customization seam EC-236)
+ * produce.
  *
  * A studio surface (the CMS, Routes, Assets view, or a net-new one) is a
- * self-contained MODULE: id + display metadata + a React `render` + an optional
- * deep-link parser. The configurable sidebar (EC-237) mounts modules; the splat
- * router (`matchStudioRoute`) addresses one by its id as the first path segment
- * and hands its trailing segments to `parsePath`. The studio ships a DEFAULT
- * registry (so the stock studio needs zero config); a consuming repo adds or
- * replaces modules through `config.appViews`, resolved over the defaults by the
- * shared {@link resolveOverrides} core — an unknown/duplicate/contract-violating
- * entry is a visible issue, never a silent drop, and the default block is kept.
+ * self-contained {@link AppViewModule}: a stable id + display metadata + a React
+ * `render` + an optional deep-link parser. A {@link SidebarNode} is one rail entry
+ * — a view, a labelled group of views, or a separator — and a **view node carries
+ * its view object DIRECTLY**, not a string id. This is the redesign's core: there
+ * is no separate "register a view, then reference it by `moduleId`" indirection
+ * and no shared id-keyspace, so the section rail IS the set of views, the router
+ * registry is DERIVED from it, and the duplicate-id / both-highlighted class of
+ * bug is gone by construction.
  *
- * Reuse-not-copy (the EC-239 headline): a focused view like "Taxonomy" is the CMS
- * module instantiated with config (`cmsAppView({ collections })`), not a fork — so
- * the registry holds module INSTANCES and the same surface code backs many ids.
+ * The boundary principle: everything here is studio-only live code passed by
+ * reference (no string keys). A string only crosses the serializable boundary for
+ * field controls (`form.control`), where the field lives in delivery-shared schema.
  *
- * This module is the contract + the pure resolver only; the default registry and
- * the surfaces (which pull the heavy editor providers) live in `default-modules`.
+ * Reuse-not-copy (EC-239): a focused view like "Catalog" is the CMS surface
+ * instantiated with config (`nav.cms({ collections })`), not a fork — the same
+ * surface code backs many views, each its own addressable node.
  */
-/** The deep-link a module parses out of its trailing path segments (e.g. `{ collectionId, documentId }`). */
+/** The deep-link a view parses out of its trailing path segments (e.g. `{ collectionId, documentId }`). */
 export type AppViewDeepLink = Record<string, string | null>;
-/** Everything a module's surface needs to render (EC-239). */
+/** Everything a view's surface needs to render (EC-239). */
 export interface AppViewContext {
     project: Project;
     projectId: string;
-    /** The module's parsed deep-link; `{}` for a flat view with no nested resource. */
+    /** The view's parsed deep-link; `{}` for a flat view with no nested resource. */
     deepLink: AppViewDeepLink;
     /** The validated `?…` search (forced state, focused field/asset, …). */
     search: StudioSearch;
@@ -40,54 +43,82 @@ export interface AppViewModule {
     label: string;
     description: string;
     icon: LucideIcon;
-    /** Render the surface; it mounts its own providers/gates (like the old resolver case bodies). */
+    /** Render the surface; it mounts its own providers/gates. */
     render: (ctx: AppViewContext) => ReactNode;
     /**
-     * Parse this module's trailing path segments into a deep-link, or `null` for an
-     * unroutable path (→ not-found). Omitted → a FLAT module ({@link flatPath}): only
+     * Parse this view's trailing path segments into a deep-link, or `null` for an
+     * unroutable path (→ not-found). Omitted → a FLAT view ({@link flatPath}): only
      * the bare path is valid, any trailing segment is not-found.
      */
     parsePath?: (segments: string[]) => AppViewDeepLink | null;
     /**
-     * The availability section this module rides on (EC-221 gating): an
-     * `unavailable` section hides the module from the rail. Omitted → always
-     * available (a custom module defaults to visible).
+     * The availability section this view rides on (EC-221 gating): an `unavailable`
+     * section hides the view from the rail. Omitted → always available (a custom
+     * view defaults to visible).
      */
     availabilitySection?: SectionId;
-    /** A redirect-only / utility module the stock rail does not list (e.g. `builder`). */
+    /** A redirect-only / utility view the stock rail does not list (e.g. `builder`). */
     hidden?: boolean;
 }
-/** A flat module: only the bare path resolves; any trailing segment is not-found. */
+/**
+ * A rail entry that mounts a view. Carries the view object directly — no string id.
+ *
+ * EC-293: a view node may NEST one level. `children` is a static list of sub-views;
+ * `expand` derives them at resolve time from the project's collections (CMS
+ * auto-expand). Children render indented under the parent — indentation signals
+ * parent→child, distinct from a flat labelled {@link SidebarGroupNode}. `children`
+ * (explicit) wins over `expand` when both are set.
+ */
+export interface SidebarViewNode {
+    kind: 'view';
+    view: AppViewModule;
+    /** Static sub-views, rendered indented under this view (one level of nesting). */
+    children?: SidebarViewNode[];
+    /**
+     * Resolve-time children from the project's collections (e.g. CMS expanding each
+     * collection into a focused-lens child). Run by `resolveSidebar` with the
+     * config-sourced collections; the result renders as {@link children}.
+     */
+    expand?: (collections: readonly CollectionDef[]) => SidebarViewNode[];
+}
+/**
+ * A labelled group of view entries. Groups are presentation only — never routable,
+ * and **flat**: their children render aligned with the top-level items (the heading
+ * is the only grouping signal). Group children do not nest — use a parent-with-
+ * children ({@link SidebarViewNode.expand}/`children`) for nesting (EC-293).
+ */
+export interface SidebarGroupNode {
+    kind: 'group';
+    label: string;
+    children: SidebarViewNode[];
+}
+/** A divider between rail sections. */
+export interface SidebarSeparatorNode {
+    kind: 'separator';
+}
+export type SidebarNode = SidebarViewNode | SidebarGroupNode | SidebarSeparatorNode;
+/** Wrap a view as a rail entry. */
+export declare function viewNode(view: AppViewModule): SidebarViewNode;
+/** A labelled group of view entries (sub-views under a header). */
+export declare function groupNode(label: string, children: SidebarViewNode[]): SidebarGroupNode;
+/** A rail divider. */
+export declare function separatorNode(): SidebarSeparatorNode;
+/** A flat view: only the bare path resolves; any trailing segment is not-found. */
 export declare function flatPath(segments: string[]): AppViewDeepLink | null;
 /** CMS arity: `[]` index · `[c]` collection · `[c, d]` document; deeper is not-found. */
 export declare function cmsDeepLink(segments: string[]): AppViewDeepLink | null;
 /** Components arity: `[]` index · `[id]` detail; deeper is not-found. */
 export declare function componentsDeepLink(segments: string[]): AppViewDeepLink | null;
-export interface ResolvedAppViews {
-    /** Default + custom modules, defaults first in registry order, additions appended. */
-    modules: AppViewModule[];
-    /** Resolve one id to its module — a custom override beats the default. */
-    get(id: string): AppViewModule | undefined;
-    /** Resolution issues (unknown target is impossible here — additive; duplicate / invalid). */
-    issues: CustomizationIssue[];
-}
-/**
- * Resolve the config's custom app-view modules over the studio's default registry
- * through the shared customization core (EC-236): an additive registry keyed by
- * module id, rejecting a module with no `render` / no `label` (or a duplicate id)
- * with a visible issue and keeping the default. Pure — the React payloads are
- * opaque here.
- */
-export declare function resolveAppViews(defaults: readonly AppViewModule[], entries?: readonly AppViewEntry[]): ResolvedAppViews;
 /**
- * A module's availability for a project (EC-221): the section it rides on, or
- * always `available` when it declares none (a custom module). Drives both the
- * rail (hide `unavailable`) and the bare-project landing target.
+ * A view's availability for a project (EC-221): the section it rides on, or always
+ * `available` when it declares none (a custom view). Drives both the rail (hide
+ * `unavailable`) and the bare-project landing target.
  */
 export declare function moduleAvailability(project: Project, module: AppViewModule): SectionAvailability;
 /**
- * The module a project should open to from its bare URL: the first listed
- * (non-hidden), non-`unavailable` module in registry order. There is always at
- * least one (Settings is always available), so this never returns `null`.
+ * The view a project should open to from its bare URL: the first listed
+ * (non-hidden), non-`unavailable` view in rail order. Callers pass the resolved
+ * registry's view list (rail order); `undefined` only if every view is
+ * hidden/unavailable (the resolver guarantees Settings, so in practice never).
  */
-export declare function firstAvailableModule(modules: readonly AppViewModule[], project: Project): string;
+export declare function firstAvailableView(views: readonly AppViewModule[], project: Project): AppViewModule | undefined;

package/dist/components/app-views/module.js

@@ -1,6 +1,18 @@
-import { availabilityOf, resolveOverrides } from '@elytracms/core/studio-core';
-// --- Deep-link parsers (shared by the default modules + reused by factories) ---
-/** A flat module: only the bare path resolves; any trailing segment is not-found. */
+import { availabilityOf } from '@elytracms/core/studio-core';
+/** Wrap a view as a rail entry. */
+export function viewNode(view) {
+    return { kind: 'view', view };
+}
+/** A labelled group of view entries (sub-views under a header). */
+export function groupNode(label, children) {
+    return { kind: 'group', label, children };
+}
+/** A rail divider. */
+export function separatorNode() {
+    return { kind: 'separator' };
+}
+// --- Deep-link parsers (shared by the built-in views + reused by factories) ---
+/** A flat view: only the bare path resolves; any trailing segment is not-found. */
 export function flatPath(segments) {
     return segments.length === 0 ? {} : null;
 }
@@ -22,41 +34,11 @@ export function componentsDeepLink(segments) {
         return { componentId: segments[0] };
     return null;
 }
+// --- Availability (EC-221) ---
 /**
- * Resolve the config's custom app-view modules over the studio's default registry
- * through the shared customization core (EC-236): an additive registry keyed by
- * module id, rejecting a module with no `render` / no `label` (or a duplicate id)
- * with a visible issue and keeping the default. Pure — the React payloads are
- * opaque here.
- */
-export function resolveAppViews(defaults, entries = []) {
-    const resolved = resolveOverrides({
-        point: 'appViews',
-        defaults: defaults.map((module) => ({ id: module.id, value: module })),
-        overrides: entries.map((entry) => {
-            const module = entry;
-            return { id: module.id, value: module };
-        }),
-        allowNew: true,
-        validate: (entry) => {
-            const module = entry.value;
-            if (typeof module.render !== 'function')
-                return 'the module has no render function';
-            if (typeof module.label !== 'string' || module.label.trim().length === 0)
-                return 'the module has no label';
-            return null;
-        },
-    });
-    return {
-        modules: resolved.entries.map((entry) => entry.value),
-        get: (id) => resolved.get(id),
-        issues: resolved.issues,
-    };
-}
-/**
- * A module's availability for a project (EC-221): the section it rides on, or
- * always `available` when it declares none (a custom module). Drives both the
- * rail (hide `unavailable`) and the bare-project landing target.
+ * A view's availability for a project (EC-221): the section it rides on, or always
+ * `available` when it declares none (a custom view). Drives both the rail (hide
+ * `unavailable`) and the bare-project landing target.
  */
 export function moduleAvailability(project, module) {
     return module.availabilitySection
@@ -64,12 +46,12 @@ export function moduleAvailability(project, module) {
         : 'available';
 }
 /**
- * The module a project should open to from its bare URL: the first listed
- * (non-hidden), non-`unavailable` module in registry order. There is always at
- * least one (Settings is always available), so this never returns `null`.
+ * The view a project should open to from its bare URL: the first listed
+ * (non-hidden), non-`unavailable` view in rail order. Callers pass the resolved
+ * registry's view list (rail order); `undefined` only if every view is
+ * hidden/unavailable (the resolver guarantees Settings, so in practice never).
  */
-export function firstAvailableModule(modules, project) {
-    const found = modules.find((module) => !module.hidden && moduleAvailability(project, module) !== 'unavailable');
-    return found?.id ?? 'settings';
+export function firstAvailableView(views, project) {
+    return views.find((view) => !view.hidden && moduleAvailability(project, view) !== 'unavailable');
 }
 //# sourceMappingURL=module.js.map

package/dist/components/app-views/module.js.map

@@ -1 +1 @@
-{"version":3,"file":"module.js","sourceRoot":"","sources":["../../../src/components/app-views/module.tsx"],"names":[],"mappings":"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","sourcesContent":["import type { ReactNode } from 'react'\nimport type { LucideIcon } from 'lucide-react'\nimport { availabilityOf, resolveOverrides } from '@elytracms/core/studio-core'\nimport type {\n  AppViewEntry,\n  CustomizationIssue,\n  Project,\n  SectionAvailability,\n  SectionId,\n} from '@elytracms/core/studio-core'\nimport type { StudioSearch } from '@elytracms/studio/router/search'\n\n/**\n * EC-239 — the app-view module contract, an instance of the EC-236 customization\n * seam.\n *\n * A studio surface (the CMS, Routes, Assets view, or a net-new one) is a\n * self-contained MODULE: id + display metadata + a React `render` + an optional\n * deep-link parser. The configurable sidebar (EC-237) mounts modules; the splat\n * router (`matchStudioRoute`) addresses one by its id as the first path segment\n * and hands its trailing segments to `parsePath`. The studio ships a DEFAULT\n * registry (so the stock studio needs zero config); a consuming repo adds or\n * replaces modules through `config.appViews`, resolved over the defaults by the\n * shared {@link resolveOverrides} core — an unknown/duplicate/contract-violating\n * entry is a visible issue, never a silent drop, and the default block is kept.\n *\n * Reuse-not-copy (the EC-239 headline): a focused view like \"Taxonomy\" is the CMS\n * module instantiated with config (`cmsAppView({ collections })`), not a fork — so\n * the registry holds module INSTANCES and the same surface code backs many ids.\n *\n * This module is the contract + the pure resolver only; the default registry and\n * the surfaces (which pull the heavy editor providers) live in `default-modules`.\n */\n\n/** The deep-link a module parses out of its trailing path segments (e.g. `{ collectionId, documentId }`). */\nexport type AppViewDeepLink = Record<string, string | null>\n\n/** Everything a module's surface needs to render (EC-239). */\nexport interface AppViewContext {\n  project: Project\n  projectId: string\n  /** The module's parsed deep-link; `{}` for a flat view with no nested resource. */\n  deepLink: AppViewDeepLink\n  /** The validated `?…` search (forced state, focused field/asset, …). */\n  search: StudioSearch\n}\n\nexport interface AppViewModule {\n  /** Stable id — the first path segment under the project + the registry key. */\n  id: string\n  label: string\n  description: string\n  icon: LucideIcon\n  /** Render the surface; it mounts its own providers/gates (like the old resolver case bodies). */\n  render: (ctx: AppViewContext) => ReactNode\n  /**\n   * Parse this module's trailing path segments into a deep-link, or `null` for an\n   * unroutable path (→ not-found). Omitted → a FLAT module ({@link flatPath}): only\n   * the bare path is valid, any trailing segment is not-found.\n   */\n  parsePath?: (segments: string[]) => AppViewDeepLink | null\n  /**\n   * The availability section this module rides on (EC-221 gating): an\n   * `unavailable` section hides the module from the rail. Omitted → always\n   * available (a custom module defaults to visible).\n   */\n  availabilitySection?: SectionId\n  /** A redirect-only / utility module the stock rail does not list (e.g. `builder`). */\n  hidden?: boolean\n}\n\n// --- Deep-link parsers (shared by the default modules + reused by factories) ---\n\n/** A flat module: only the bare path resolves; any trailing segment is not-found. */\nexport function flatPath(segments: string[]): AppViewDeepLink | null {\n  return segments.length === 0 ? {} : null\n}\n\n/** CMS arity: `[]` index · `[c]` collection · `[c, d]` document; deeper is not-found. */\nexport function cmsDeepLink(segments: string[]): AppViewDeepLink | null {\n  if (segments.length === 0) return { collectionId: null, documentId: null }\n  if (segments.length === 1) return { collectionId: segments[0]!, documentId: null }\n  if (segments.length === 2) return { collectionId: segments[0]!, documentId: segments[1]! }\n  return null\n}\n\n/** Components arity: `[]` index · `[id]` detail; deeper is not-found. */\nexport function componentsDeepLink(segments: string[]): AppViewDeepLink | null {\n  if (segments.length === 0) return { componentId: null }\n  if (segments.length === 1) return { componentId: segments[0]! }\n  return null\n}\n\n// --- Resolution (EC-236 seam) ---\n\nexport interface ResolvedAppViews {\n  /** Default + custom modules, defaults first in registry order, additions appended. */\n  modules: AppViewModule[]\n  /** Resolve one id to its module — a custom override beats the default. */\n  get(id: string): AppViewModule | undefined\n  /** Resolution issues (unknown target is impossible here — additive; duplicate / invalid). */\n  issues: CustomizationIssue[]\n}\n\n/**\n * Resolve the config's custom app-view modules over the studio's default registry\n * through the shared customization core (EC-236): an additive registry keyed by\n * module id, rejecting a module with no `render` / no `label` (or a duplicate id)\n * with a visible issue and keeping the default. Pure — the React payloads are\n * opaque here.\n */\nexport function resolveAppViews(\n  defaults: readonly AppViewModule[],\n  entries: readonly AppViewEntry[] = [],\n): ResolvedAppViews {\n  const resolved = resolveOverrides<AppViewModule>({\n    point: 'appViews',\n    defaults: defaults.map((module) => ({ id: module.id, value: module })),\n    overrides: entries.map((entry) => {\n      const module = entry as unknown as AppViewModule\n      return { id: module.id, value: module }\n    }),\n    allowNew: true,\n    validate: (entry) => {\n      const module = entry.value as Partial<AppViewModule>\n      if (typeof module.render !== 'function') return 'the module has no render function'\n      if (typeof module.label !== 'string' || module.label.trim().length === 0)\n        return 'the module has no label'\n      return null\n    },\n  })\n  return {\n    modules: resolved.entries.map((entry) => entry.value),\n    get: (id) => resolved.get(id),\n    issues: resolved.issues,\n  }\n}\n\n/**\n * A module's availability for a project (EC-221): the section it rides on, or\n * always `available` when it declares none (a custom module). Drives both the\n * rail (hide `unavailable`) and the bare-project landing target.\n */\nexport function moduleAvailability(project: Project, module: AppViewModule): SectionAvailability {\n  return module.availabilitySection\n    ? availabilityOf(project.settings.sectionAvailability, module.availabilitySection)\n    : 'available'\n}\n\n/**\n * The module a project should open to from its bare URL: the first listed\n * (non-hidden), non-`unavailable` module in registry order. There is always at\n * least one (Settings is always available), so this never returns `null`.\n */\nexport function firstAvailableModule(modules: readonly AppViewModule[], project: Project): string {\n  const found = modules.find(\n    (module) => !module.hidden && moduleAvailability(project, module) !== 'unavailable',\n  )\n  return found?.id ?? 'settings'\n}\n"]}
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../../src/components/app-views/module.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AA0G5D,mCAAmC;AACnC,MAAM,UAAU,QAAQ,CAAC,IAAmB;IAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;AAC/B,CAAC;AACD,mEAAmE;AACnE,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,QAA2B;IAClE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;AAC3C,CAAC;AACD,sBAAsB;AACtB,MAAM,UAAU,aAAa;IAC3B,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAA;AAC9B,CAAC;AAED,iFAAiF;AAEjF,mFAAmF;AACnF,MAAM,UAAU,QAAQ,CAAC,QAAkB;IACzC,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AAC1C,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,WAAW,CAAC,QAAkB;IAC5C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAA;IAC1E,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAA;IAClF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAE,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAE,EAAE,CAAA;IAC1F,OAAO,IAAI,CAAA;AACb,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,kBAAkB,CAAC,QAAkB;IACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAA;IACvD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAE,EAAE,CAAA;IAC/D,OAAO,IAAI,CAAA;AACb,CAAC;AAED,gCAAgC;AAEhC;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB,EAAE,MAAqB;IACxE,OAAO,MAAM,CAAC,mBAAmB;QAC/B,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC,mBAAmB,CAAC;QAClF,CAAC,CAAC,WAAW,CAAA;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAA+B,EAC/B,OAAgB;IAEhB,OAAO,KAAK,CAAC,IAAI,CACf,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,aAAa,CAC9E,CAAA;AACH,CAAC","sourcesContent":["import type { ReactNode } from 'react'\nimport type { LucideIcon } from 'lucide-react'\nimport { availabilityOf } from '@elytracms/core/studio-core'\nimport type { Project, SectionAvailability, SectionId } from '@elytracms/core/studio-core'\nimport type { CollectionDef } from '@elytracms/core/cms-core'\nimport type { StudioSearch } from '@elytracms/studio/router/search'\n\n/**\n * The studio **view** contract + the **sidebar node** model — the internal types\n * the consumer-facing `nav.*` builders (EC-237/239, customization seam EC-236)\n * produce.\n *\n * A studio surface (the CMS, Routes, Assets view, or a net-new one) is a\n * self-contained {@link AppViewModule}: a stable id + display metadata + a React\n * `render` + an optional deep-link parser. A {@link SidebarNode} is one rail entry\n * — a view, a labelled group of views, or a separator — and a **view node carries\n * its view object DIRECTLY**, not a string id. This is the redesign's core: there\n * is no separate \"register a view, then reference it by `moduleId`\" indirection\n * and no shared id-keyspace, so the section rail IS the set of views, the router\n * registry is DERIVED from it, and the duplicate-id / both-highlighted class of\n * bug is gone by construction.\n *\n * The boundary principle: everything here is studio-only live code passed by\n * reference (no string keys). A string only crosses the serializable boundary for\n * field controls (`form.control`), where the field lives in delivery-shared schema.\n *\n * Reuse-not-copy (EC-239): a focused view like \"Catalog\" is the CMS surface\n * instantiated with config (`nav.cms({ collections })`), not a fork — the same\n * surface code backs many views, each its own addressable node.\n */\n\n/** The deep-link a view parses out of its trailing path segments (e.g. `{ collectionId, documentId }`). */\nexport type AppViewDeepLink = Record<string, string | null>\n\n/** Everything a view's surface needs to render (EC-239). */\nexport interface AppViewContext {\n  project: Project\n  projectId: string\n  /** The view's parsed deep-link; `{}` for a flat view with no nested resource. */\n  deepLink: AppViewDeepLink\n  /** The validated `?…` search (forced state, focused field/asset, …). */\n  search: StudioSearch\n}\n\nexport interface AppViewModule {\n  /** Stable id — the first path segment under the project + the registry key. */\n  id: string\n  label: string\n  description: string\n  icon: LucideIcon\n  /** Render the surface; it mounts its own providers/gates. */\n  render: (ctx: AppViewContext) => ReactNode\n  /**\n   * Parse this view's trailing path segments into a deep-link, or `null` for an\n   * unroutable path (→ not-found). Omitted → a FLAT view ({@link flatPath}): only\n   * the bare path is valid, any trailing segment is not-found.\n   */\n  parsePath?: (segments: string[]) => AppViewDeepLink | null\n  /**\n   * The availability section this view rides on (EC-221 gating): an `unavailable`\n   * section hides the view from the rail. Omitted → always available (a custom\n   * view defaults to visible).\n   */\n  availabilitySection?: SectionId\n  /** A redirect-only / utility view the stock rail does not list (e.g. `builder`). */\n  hidden?: boolean\n}\n\n// --- The sidebar node model (what `nav.*` produces) ---\n\n/**\n * A rail entry that mounts a view. Carries the view object directly — no string id.\n *\n * EC-293: a view node may NEST one level. `children` is a static list of sub-views;\n * `expand` derives them at resolve time from the project's collections (CMS\n * auto-expand). Children render indented under the parent — indentation signals\n * parent→child, distinct from a flat labelled {@link SidebarGroupNode}. `children`\n * (explicit) wins over `expand` when both are set.\n */\nexport interface SidebarViewNode {\n  kind: 'view'\n  view: AppViewModule\n  /** Static sub-views, rendered indented under this view (one level of nesting). */\n  children?: SidebarViewNode[]\n  /**\n   * Resolve-time children from the project's collections (e.g. CMS expanding each\n   * collection into a focused-lens child). Run by `resolveSidebar` with the\n   * config-sourced collections; the result renders as {@link children}.\n   */\n  expand?: (collections: readonly CollectionDef[]) => SidebarViewNode[]\n}\n/**\n * A labelled group of view entries. Groups are presentation only — never routable,\n * and **flat**: their children render aligned with the top-level items (the heading\n * is the only grouping signal). Group children do not nest — use a parent-with-\n * children ({@link SidebarViewNode.expand}/`children`) for nesting (EC-293).\n */\nexport interface SidebarGroupNode {\n  kind: 'group'\n  label: string\n  children: SidebarViewNode[]\n}\n/** A divider between rail sections. */\nexport interface SidebarSeparatorNode {\n  kind: 'separator'\n}\nexport type SidebarNode = SidebarViewNode | SidebarGroupNode | SidebarSeparatorNode\n\n/** Wrap a view as a rail entry. */\nexport function viewNode(view: AppViewModule): SidebarViewNode {\n  return { kind: 'view', view }\n}\n/** A labelled group of view entries (sub-views under a header). */\nexport function groupNode(label: string, children: SidebarViewNode[]): SidebarGroupNode {\n  return { kind: 'group', label, children }\n}\n/** A rail divider. */\nexport function separatorNode(): SidebarSeparatorNode {\n  return { kind: 'separator' }\n}\n\n// --- Deep-link parsers (shared by the built-in views + reused by factories) ---\n\n/** A flat view: only the bare path resolves; any trailing segment is not-found. */\nexport function flatPath(segments: string[]): AppViewDeepLink | null {\n  return segments.length === 0 ? {} : null\n}\n\n/** CMS arity: `[]` index · `[c]` collection · `[c, d]` document; deeper is not-found. */\nexport function cmsDeepLink(segments: string[]): AppViewDeepLink | null {\n  if (segments.length === 0) return { collectionId: null, documentId: null }\n  if (segments.length === 1) return { collectionId: segments[0]!, documentId: null }\n  if (segments.length === 2) return { collectionId: segments[0]!, documentId: segments[1]! }\n  return null\n}\n\n/** Components arity: `[]` index · `[id]` detail; deeper is not-found. */\nexport function componentsDeepLink(segments: string[]): AppViewDeepLink | null {\n  if (segments.length === 0) return { componentId: null }\n  if (segments.length === 1) return { componentId: segments[0]! }\n  return null\n}\n\n// --- Availability (EC-221) ---\n\n/**\n * A view's availability for a project (EC-221): the section it rides on, or always\n * `available` when it declares none (a custom view). Drives both the rail (hide\n * `unavailable`) and the bare-project landing target.\n */\nexport function moduleAvailability(project: Project, module: AppViewModule): SectionAvailability {\n  return module.availabilitySection\n    ? availabilityOf(project.settings.sectionAvailability, module.availabilitySection)\n    : 'available'\n}\n\n/**\n * The view a project should open to from its bare URL: the first listed\n * (non-hidden), non-`unavailable` view in rail order. Callers pass the resolved\n * registry's view list (rail order); `undefined` only if every view is\n * hidden/unavailable (the resolver guarantees Settings, so in practice never).\n */\nexport function firstAvailableView(\n  views: readonly AppViewModule[],\n  project: Project,\n): AppViewModule | undefined {\n  return views.find(\n    (view) => !view.hidden && moduleAvailability(project, view) !== 'unavailable',\n  )\n}\n"]}

package/dist/components/app-views/sidebar.d.ts

@@ -1,95 +1,86 @@
 import type { LucideIcon } from 'lucide-react';
 import type { CustomizationIssue, Project, SectionAvailability } from '@elytracms/core/studio-core';
-import { type ResolvedAppViews } from './module';
+import type { CollectionDef } from '@elytracms/core/cms-core';
+import { type AppViewModule, type SidebarNode } from './module';
 /**
- * EC-237 — the configurable sidebar, an instance of the EC-236 customization seam.
+ * EC-237 — resolving the configurable section rail, an instance of the EC-236
+ * customization seam.
  *
- * The section rail is a consumer-extendable ARRAY of nav entries — items (each
- * targeting an EC-239 app-view module, optionally deep-linked to a resource),
- * groups of sub-items, and separators. A consuming repo supplies its own array
- * through `config.sidebar`; omitted → the studio derives the default rail from its
- * module registry (every non-hidden module, in order). The supplied array is
- * resolved through the shared {@link resolveOverrides} core: a duplicate id, an
- * item whose target module isn't registered ("unknown view"), or a deep-link that
- * doesn't resolve becomes a visible {@link CustomizationIssue} and the entry is
- * dropped — never a silent failure. Sub-views (a focused "Taxonomy") are EC-239
- * modules; this file decides only how the rail PRESENTS and orders them.
+ * A consuming repo supplies its rail as a `SidebarNode[]` (built from `nav.*`);
+ * omitted → the studio derives the default rail from its built-in views. The rail
+ * IS the set of views — each view node carries its view object directly — so this
+ * resolver does two things at once:
+ *
+ *   1. **Renders the rail.** Walk the nodes into display-ready entries (views,
+ *      groups, separators) with per-view availability (EC-221) and a route path.
+ *   2. **Derives the router registry.** Collect every rail view + the always-on
+ *      built-ins (so deep-links resolve even for views a rail omits), keyed by id.
+ *
+ * Only VIEWS occupy the id-keyspace; groups + separators are presentation with no
+ * id, so a group label can never collide with a view (the old duplicate-id bug).
+ * Views resolve through the shared {@link resolveOverrides} core: a duplicate view
+ * id or a view missing `render`/`label` is a visible {@link CustomizationIssue} and
+ * is dropped — never silent. The active rail item is matched by the view id in the
+ * URL, so two views backed by the same surface (Content vs. a focused Categories)
+ * highlight independently.
  */
-/** A nav item targeting an app-view module, optionally deep-linked to a resource. */
-export interface SidebarItemConfig {
-    kind: 'item';
-    /** Stable id (defaults to `moduleId` via {@link navItem}). */
-    id: string;
-    /** The app-view module this item mounts — must be in the registry. */
-    moduleId: string;
-    /** Overrides the module's rail label. */
-    label?: string;
-    /** Overrides the module's rail icon. */
-    icon?: LucideIcon;
-    /** Trailing path segments targeting a specific resource, e.g. `['category']`. */
-    deepLink?: readonly string[];
-}
-export interface SidebarGroupConfig {
-    kind: 'group';
-    id: string;
-    label: string;
-    items: SidebarItemConfig[];
-}
-export interface SidebarSeparatorConfig {
-    kind: 'separator';
-    id?: string;
-}
-export type SidebarNodeConfig = SidebarItemConfig | SidebarGroupConfig | SidebarSeparatorConfig;
-export interface ResolvedSidebarItem {
-    kind: 'item';
+export interface ResolvedRailView {
+    kind: 'view';
+    /** The view id — the route segment and the active-state key. */
     id: string;
-    moduleId: string;
     label: string;
     icon: LucideIcon;
-    /** The `_splat` to navigate to (moduleId + deep-link segments). */
+    /** The `_splat` to navigate to (the view's home route = its id). */
     path: string;
     availability: SectionAvailability;
+    /**
+     * EC-293: nested sub-views (e.g. a CMS view's collections), rendered indented
+     * under this view. Present only on a parent that expanded; leaves omit it.
+     */
+    children?: ResolvedRailView[];
 }
-export interface ResolvedSidebarGroup {
+export interface ResolvedRailGroup {
     kind: 'group';
-    id: string;
     label: string;
-    items: ResolvedSidebarItem[];
+    views: ResolvedRailView[];
 }
-export interface ResolvedSidebarSeparator {
+export interface ResolvedRailSeparator {
     kind: 'separator';
-    id: string;
 }
-export type ResolvedSidebarNode = ResolvedSidebarItem | ResolvedSidebarGroup | ResolvedSidebarSeparator;
-export interface ResolvedSidebar {
-    nodes: ResolvedSidebarNode[];
+export type ResolvedRailNode = ResolvedRailView | ResolvedRailGroup | ResolvedRailSeparator;
+/** The router registry derived from the rail: id → view, plus the landing order. */
+export interface ViewRegistry {
+    /** Resolve a view id to its module (rail views + always-on built-ins). */
+    get(id: string): AppViewModule | undefined;
+    /** Views in landing order (rail order first, then non-rail built-ins). */
+    views: AppViewModule[];
+}
+export interface StudioNav {
+    /** The display-ready rail (for {@link import('../section-nav').SectionNav}). */
+    nodes: ResolvedRailNode[];
+    /** The router registry (for the screen resolver + breadcrumb). */
+    registry: ViewRegistry;
+    /** Customization issues (duplicate view id, invalid view) — visible, never silent. */
     issues: CustomizationIssue[];
 }
-/** A nav item; `id` defaults to `moduleId` when omitted. */
-export declare function navItem(config: Omit<SidebarItemConfig, 'kind' | 'id'> & {
-    id?: string;
-}): SidebarItemConfig;
-/** A labelled group of sub-items; `id` defaults to a slug of the label. */
-export declare function navGroup(label: string, items: SidebarItemConfig[], opts?: {
-    id?: string;
-}): SidebarGroupConfig;
-/** A divider between rail sections. */
-export declare function navSeparator(id?: string): SidebarSeparatorConfig;
-/** Identity helper that types a consumer's `config.sidebar` array. */
-export declare function defineSidebar(nodes: SidebarNodeConfig[]): SidebarNodeConfig[];
 /**
- * Resolve a consumer sidebar (or the default rail) over the app-view registry
- * through the shared customization core (EC-236). Every node — items, group
- * headers, nested items, separators — is keyed by id and run through
- * {@link resolveOverrides} for dedup + per-node validation, so a duplicate id or
- * an invalid item is a visible issue and is dropped; the surviving nodes are
- * rebuilt into the rail tree (groups keep their surviving sub-items).
+ * Resolve a consumer rail (or the default rail) into the display tree + the router
+ * registry through the EC-236 seam. Views are resolved over the built-in defaults
+ * (so an omitted built-in stays routable and a rail `cms` REPLACES the default
+ * one); groups/separators pass through as presentation.
+ *
+ * EC-293: a view node may nest. `collections` (config-sourced) materialises a CMS
+ * parent's per-collection children; every child view joins the override pass + the
+ * derived registry, so a nested `cms:<id>` lens routes and highlights like any view.
  */
-export declare function resolveSidebar(registry: ResolvedAppViews, project: Project, entries?: readonly SidebarNodeConfig[]): ResolvedSidebar;
-/** The active module id parsed from a studio pathname `/<projectId>/<module>[/…]`. */
-export declare function activeModuleFromPath(pathname: string): string | null;
+export declare function resolveSidebar(entries: readonly SidebarNode[] | undefined, project: Project, collections?: readonly CollectionDef[]): StudioNav;
+/** The active view id parsed from a studio pathname `/<projectId>/<viewId>[/…]`. */
+export declare function activeViewIdFromPath(pathname: string): string | null;
+/** The view a bare project URL should open to: the first navigable rail view (EC-221). */
+export declare function landingViewId(nav: StudioNav, project: Project): string;
 /**
- * The active project's resolved sidebar — the default rail or `config.sidebar`,
- * resolved over the module registry through the EC-236 seam (static per boot).
+ * The active project's resolved studio nav — the default rail or
+ * `studioConfig.sidebar`, resolved over the built-in views through the EC-236 seam
+ * (static per studio boot).
  */
-export declare function useSidebar(project: Project): ResolvedSidebar;
+export declare function useStudioNav(project: Project): StudioNav;