@jfdevelops/react-layout 0.20.0 → 0.21.0

package/dist/create-config/shell-context.d.mts

@@ -0,0 +1,18 @@
+//#region src/create-config/shell-context.d.ts
+/**
+ * Callback a per-resource layout component calls to report which resource it is
+ * currently rendering. An ancestor `Shell` (from
+ * {@link defineResourceLayout.withLayout}) installs one of these so it can
+ * resolve `resources.current` for its own render without the consumer threading
+ * a route param down to it.
+ *
+ * @param resource - The mounted resource, or `undefined` on unmount.
+ * @param ownerId - Identity of the `defineResourceLayout` definition that
+ *   created the reporting component. The shell only accepts reports from its
+ *   own definition — a page or pane produced by a *different* definition shares
+ *   this context but its resource is unrelated, so the shell ignores it.
+ */
+type ResourceLayoutShellPublisher = (resource: string | undefined, ownerId?: symbol) => void;
+//#endregion
+export { ResourceLayoutShellPublisher };
+//# sourceMappingURL=shell-context.d.mts.map

package/dist/create-config/shell-context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-context.d.mts","names":[],"sources":["../../src/create-config/shell-context.tsx"],"mappings":";;AAeA;;;;AAEkB;;;;;;;;KAFN,4BAAA,IACV,QAAA,sBACA,OAAgB"}

package/dist/create-config/shell-context.mjs

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "react";
+
+//#region src/create-config/shell-context.tsx
+/**
+* Bridge between a `Shell` and the per-resource components rendered inside its
+* `Outlet`. It is deliberately `null` by default: a per-resource component is
+* still valid without a `Shell` ancestor (the pre-`withLayout` usage), so the
+* publish must degrade to a no-op rather than assume a provider.
+*/
+const ResourceLayoutShellPublisherContext = createContext(null);
+/**
+* Reads the {@link ResourceLayoutShellPublisher} installed by an ancestor
+* `Shell`, or `null` when the component renders standalone.
+*/
+function useResourceLayoutShellPublisher() {
+	return useContext(ResourceLayoutShellPublisherContext);
+}
+
+//#endregion
+export { ResourceLayoutShellPublisherContext, useResourceLayoutShellPublisher };
+//# sourceMappingURL=shell-context.mjs.map

package/dist/create-config/shell-context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-context.mjs","names":[],"sources":["../../src/create-config/shell-context.tsx"],"sourcesContent":["import { createContext, useContext } from 'react';\n\n/**\n * Callback a per-resource layout component calls to report which resource it is\n * currently rendering. An ancestor `Shell` (from\n * {@link defineResourceLayout.withLayout}) installs one of these so it can\n * resolve `resources.current` for its own render without the consumer threading\n * a route param down to it.\n *\n * @param resource - The mounted resource, or `undefined` on unmount.\n * @param ownerId - Identity of the `defineResourceLayout` definition that\n *   created the reporting component. The shell only accepts reports from its\n *   own definition — a page or pane produced by a *different* definition shares\n *   this context but its resource is unrelated, so the shell ignores it.\n */\nexport type ResourceLayoutShellPublisher = (\n  resource: string | undefined,\n  ownerId?: symbol,\n) => void;\n\n/**\n * Bridge between a `Shell` and the per-resource components rendered inside its\n * `Outlet`. It is deliberately `null` by default: a per-resource component is\n * still valid without a `Shell` ancestor (the pre-`withLayout` usage), so the\n * publish must degrade to a no-op rather than assume a provider.\n */\nexport const ResourceLayoutShellPublisherContext =\n  createContext<ResourceLayoutShellPublisher | null>(null);\n\n/**\n * Reads the {@link ResourceLayoutShellPublisher} installed by an ancestor\n * `Shell`, or `null` when the component renders standalone.\n */\nexport function useResourceLayoutShellPublisher(): ResourceLayoutShellPublisher | null {\n  return useContext(ResourceLayoutShellPublisherContext);\n}\n"],"mappings":";;;;;;;;;AA0BA,MAAa,sCACX,cAAmD,IAAI;;;;;AAMzD,SAAgB,kCAAuE;CACrF,OAAO,WAAW,mCAAmC;AACvD"}

package/dist/index.d.cts

@@ -6,7 +6,8 @@ import { CreateGetComponentForPath, GetComponentForPath, ResolvedPathValue } fro
 import { ForPaths, ForPathsRenderContext, RenderedPathComponent, RenderedPathComponentHOF, TargetPathBuilder } from "./create-config/for-paths/builder.cjs";
 import { IsSubResourceKey } from "./create-config/is-sub-resource-key.cjs";
 import { ComponentTypes, CreatedResourceConfig } from "./create-config/get-component.cjs";
-import { DefineResourcesFn, LayoutRenderResourcesAccessor, LayoutResourcesAccessor, ResourceSelection, defineResourceLayout } from "./create-config/define-layout.cjs";
+import { CreateResourceLayoutWithLayoutOptions, DefineResourceLayoutWithLayoutFn, DefineResourcesFn, DefinedResourceLayoutWithShell, LayoutRenderResourcesAccessor, LayoutResourcesAccessor, ResourceLayoutShellComponent, ResourceLayoutShellProps, ResourceSelection, ShellLayoutDefinition, ShellRenderContext, defineResourceLayout } from "./create-config/define-layout.cjs";
+import { ResourceLayoutShellPublisher } from "./create-config/shell-context.cjs";
 import { CreateReactLayoutErrorOptions, CreatedReactLayoutError, ErrorMessageRenderer, ReactLayoutError, ReactLayoutErrorContext, ReactLayoutErrorRendererFactory, createReactLayoutError } from "./errors/react-layout-error.cjs";
 import { InvalidConfigContext, InvalidConfigError } from "./errors/invalid-config.cjs";
 import { InvalidPathContext, InvalidPathError } from "./errors/invalid-path.cjs";
@@ -16,4 +17,4 @@ import { InvalidComponentContext, InvalidComponentError } from "./errors/invalid
 import { MissingPathVariableContext, MissingPathVariableError } from "./errors/missing-path-variable.cjs";
 import { AnyComposableComponent, ComposableComponent, ComposableComponentCallable, ComposableComponents, ComposableNameContext, ComposablePresetComponent, ComposablePresetComponentCallProps, ComposablePresetMeta, ComposablePresetProps, ComposableResourceLayout, CreateLayoutComposable, DefinedComposableComponentRecord, LayoutComposablePresetProvider, LayoutComposablesFactory, MakeComposable, MakeComposableOptions, MergePresetProps, PresetPropsFromComposable, RequiredPresetLayoutProps, RequiredPresetRenderProps, ResolveLayoutComposables, collectComposablePresetEntries, createComposableComponent, createLayoutComposableFactory, defineComposableComponent, makeComposable, resolveComposablePresetProps, resolveLayoutComposables } from "@jfdevelops/react-layout-composables";
 import { AnyBuiltPropDefinition, ExtractDefinitionValue, PropError, PropErrorOptions, ResolveLayoutProps, ResolveLayoutPropsAsDefined, ResolveProps, ResolvedBuiltPropShape, createPrimitivePropBuilder, createProp, isPropDefinitionShape, resolvePropDefinitionValues, validateProps } from "@jfdevelops/react-layout-validator";
-export { type AnyBuiltPropDefinition, type AnyComposableComponent, type BaseComponent, type ComponentTypes, type ComposableComponent, type ComposableComponentCallable, type ComposableComponents, type ComposableNameContext, type ComposablePresetComponent, type ComposablePresetComponentCallProps, type ComposablePresetMeta, type ComposablePresetProps, type ComposableResourceLayout, type CreateGetComponentForPath, type CreateLayoutComposable, type CreateReactLayoutErrorOptions, type CreatedReactLayoutError, type CreatedResourceConfig, type DefineResourcesFn, type DefinedComposableComponentRecord, type ErrorMessageRenderer, type ExtractDefinitionValue, type ForPaths, type ForPathsRenderContext, type GetComponentForPath, type InPropsDefinition, type InPropsFunction, type InPropsObject, type InPropsOptions, type IncludedPropBehavior, type IncludedProps, type InferredInProps, type InvalidComponentContext, InvalidComponentError, type InvalidConfigContext, InvalidConfigError, type InvalidPathContext, InvalidPathError, type InvalidResourceContext, InvalidResourceError, type InvalidSubResourceContext, InvalidSubResourceError, type IsSubResourceKey, LayoutComposablePresetProvider, type LayoutComposablesFactory, type LayoutRenderProps, type LayoutRenderResourcesAccessor, type LayoutResourceKey, type LayoutResourcesAccessor, type MakeComposable, type MakeComposableOptions, type MergeIntersection, type MergePresetProps, type MergedLayoutInProps, type MissingPathVariableContext, MissingPathVariableError, type NormalizeResource, type NormalizeResources, type ParameterizedResourcePath, type PathVariables, type PresetPropsFromComposable, PropError, type PropErrorOptions, type PropsContextRender, type PropsRenderDefinition, ReactLayoutError, type ReactLayoutErrorContext, type ReactLayoutErrorRendererFactory, type RenderedPathComponent, type RenderedPathComponentHOF, type RequiredPresetLayoutProps, type RequiredPresetRenderProps, type ResolveLayoutComposables, type ResolveLayoutProps, type ResolveLayoutPropsAsDefined, type ResolveProps, type ResolvedBuiltPropShape, type ResolvedIncludedComponentProps, type ResolvedIncludedConfigProps, type ResolvedIncludedProps, type ResolvedIncludedPropsAsDefined, type ResolvedPathValue, type ResourceDefinition, type ResourceDefinitionValue, type ResourceEnum, type ResourceLayoutComponentProps, type ResourceSelection, type ResourceTree, type Show, type TargetPathBuilder, type UnionToIntersection, collectComposablePresetEntries, createComposableComponent, createLayoutComposableFactory, createPrimitivePropBuilder, createProp, createReactLayoutError, defineComposableComponent, defineResourceLayout, isPropDefinitionShape, makeComposable, normalizeResource, normalizeResources, pick, resolveComposablePresetProps, resolveLayoutComposables, resolvePropDefinitionValues, toResourceEnum, validateProps };
+export { type AnyBuiltPropDefinition, type AnyComposableComponent, type BaseComponent, type ComponentTypes, type ComposableComponent, type ComposableComponentCallable, type ComposableComponents, type ComposableNameContext, type ComposablePresetComponent, type ComposablePresetComponentCallProps, type ComposablePresetMeta, type ComposablePresetProps, type ComposableResourceLayout, type CreateGetComponentForPath, type CreateLayoutComposable, type CreateReactLayoutErrorOptions, type CreateResourceLayoutWithLayoutOptions, type CreatedReactLayoutError, type CreatedResourceConfig, type DefineResourceLayoutWithLayoutFn, type DefineResourcesFn, type DefinedComposableComponentRecord, type DefinedResourceLayoutWithShell, type ErrorMessageRenderer, type ExtractDefinitionValue, type ForPaths, type ForPathsRenderContext, type GetComponentForPath, type InPropsDefinition, type InPropsFunction, type InPropsObject, type InPropsOptions, type IncludedPropBehavior, type IncludedProps, type InferredInProps, type InvalidComponentContext, InvalidComponentError, type InvalidConfigContext, InvalidConfigError, type InvalidPathContext, InvalidPathError, type InvalidResourceContext, InvalidResourceError, type InvalidSubResourceContext, InvalidSubResourceError, type IsSubResourceKey, LayoutComposablePresetProvider, type LayoutComposablesFactory, type LayoutRenderProps, type LayoutRenderResourcesAccessor, type LayoutResourceKey, type LayoutResourcesAccessor, type MakeComposable, type MakeComposableOptions, type MergeIntersection, type MergePresetProps, type MergedLayoutInProps, type MissingPathVariableContext, MissingPathVariableError, type NormalizeResource, type NormalizeResources, type ParameterizedResourcePath, type PathVariables, type PresetPropsFromComposable, PropError, type PropErrorOptions, type PropsContextRender, type PropsRenderDefinition, ReactLayoutError, type ReactLayoutErrorContext, type ReactLayoutErrorRendererFactory, type RenderedPathComponent, type RenderedPathComponentHOF, type RequiredPresetLayoutProps, type RequiredPresetRenderProps, type ResolveLayoutComposables, type ResolveLayoutProps, type ResolveLayoutPropsAsDefined, type ResolveProps, type ResolvedBuiltPropShape, type ResolvedIncludedComponentProps, type ResolvedIncludedConfigProps, type ResolvedIncludedProps, type ResolvedIncludedPropsAsDefined, type ResolvedPathValue, type ResourceDefinition, type ResourceDefinitionValue, type ResourceEnum, type ResourceLayoutComponentProps, type ResourceLayoutShellComponent, type ResourceLayoutShellProps, type ResourceLayoutShellPublisher, type ResourceSelection, type ResourceTree, type ShellLayoutDefinition, type ShellRenderContext, type Show, type TargetPathBuilder, type UnionToIntersection, collectComposablePresetEntries, createComposableComponent, createLayoutComposableFactory, createPrimitivePropBuilder, createProp, createReactLayoutError, defineComposableComponent, defineResourceLayout, isPropDefinitionShape, makeComposable, normalizeResource, normalizeResources, pick, resolveComposablePresetProps, resolveLayoutComposables, resolvePropDefinitionValues, toResourceEnum, validateProps };

package/dist/index.d.mts

@@ -6,7 +6,8 @@ import { CreateGetComponentForPath, GetComponentForPath, ResolvedPathValue } fro
 import { ForPaths, ForPathsRenderContext, RenderedPathComponent, RenderedPathComponentHOF, TargetPathBuilder } from "./create-config/for-paths/builder.mjs";
 import { IsSubResourceKey } from "./create-config/is-sub-resource-key.mjs";
 import { ComponentTypes, CreatedResourceConfig } from "./create-config/get-component.mjs";
-import { DefineResourcesFn, LayoutRenderResourcesAccessor, LayoutResourcesAccessor, ResourceSelection, defineResourceLayout } from "./create-config/define-layout.mjs";
+import { CreateResourceLayoutWithLayoutOptions, DefineResourceLayoutWithLayoutFn, DefineResourcesFn, DefinedResourceLayoutWithShell, LayoutRenderResourcesAccessor, LayoutResourcesAccessor, ResourceLayoutShellComponent, ResourceLayoutShellProps, ResourceSelection, ShellLayoutDefinition, ShellRenderContext, defineResourceLayout } from "./create-config/define-layout.mjs";
+import { ResourceLayoutShellPublisher } from "./create-config/shell-context.mjs";
 import { CreateReactLayoutErrorOptions, CreatedReactLayoutError, ErrorMessageRenderer, ReactLayoutError, ReactLayoutErrorContext, ReactLayoutErrorRendererFactory, createReactLayoutError } from "./errors/react-layout-error.mjs";
 import { InvalidConfigContext, InvalidConfigError } from "./errors/invalid-config.mjs";
 import { InvalidPathContext, InvalidPathError } from "./errors/invalid-path.mjs";
@@ -16,4 +17,4 @@ import { InvalidComponentContext, InvalidComponentError } from "./errors/invalid
 import { MissingPathVariableContext, MissingPathVariableError } from "./errors/missing-path-variable.mjs";
 import { AnyComposableComponent, ComposableComponent, ComposableComponentCallable, ComposableComponents, ComposableNameContext, ComposablePresetComponent, ComposablePresetComponentCallProps, ComposablePresetMeta, ComposablePresetProps, ComposableResourceLayout, CreateLayoutComposable, DefinedComposableComponentRecord, LayoutComposablePresetProvider, LayoutComposablesFactory, MakeComposable, MakeComposableOptions, MergePresetProps, PresetPropsFromComposable, RequiredPresetLayoutProps, RequiredPresetRenderProps, ResolveLayoutComposables, collectComposablePresetEntries, createComposableComponent, createLayoutComposableFactory, defineComposableComponent, makeComposable, resolveComposablePresetProps, resolveLayoutComposables } from "@jfdevelops/react-layout-composables";
 import { AnyBuiltPropDefinition, ExtractDefinitionValue, PropError, PropErrorOptions, ResolveLayoutProps, ResolveLayoutPropsAsDefined, ResolveProps, ResolvedBuiltPropShape, createPrimitivePropBuilder, createProp, isPropDefinitionShape, resolvePropDefinitionValues, validateProps } from "@jfdevelops/react-layout-validator";
-export { type AnyBuiltPropDefinition, type AnyComposableComponent, type BaseComponent, type ComponentTypes, type ComposableComponent, type ComposableComponentCallable, type ComposableComponents, type ComposableNameContext, type ComposablePresetComponent, type ComposablePresetComponentCallProps, type ComposablePresetMeta, type ComposablePresetProps, type ComposableResourceLayout, type CreateGetComponentForPath, type CreateLayoutComposable, type CreateReactLayoutErrorOptions, type CreatedReactLayoutError, type CreatedResourceConfig, type DefineResourcesFn, type DefinedComposableComponentRecord, type ErrorMessageRenderer, type ExtractDefinitionValue, type ForPaths, type ForPathsRenderContext, type GetComponentForPath, type InPropsDefinition, type InPropsFunction, type InPropsObject, type InPropsOptions, type IncludedPropBehavior, type IncludedProps, type InferredInProps, type InvalidComponentContext, InvalidComponentError, type InvalidConfigContext, InvalidConfigError, type InvalidPathContext, InvalidPathError, type InvalidResourceContext, InvalidResourceError, type InvalidSubResourceContext, InvalidSubResourceError, type IsSubResourceKey, LayoutComposablePresetProvider, type LayoutComposablesFactory, type LayoutRenderProps, type LayoutRenderResourcesAccessor, type LayoutResourceKey, type LayoutResourcesAccessor, type MakeComposable, type MakeComposableOptions, type MergeIntersection, type MergePresetProps, type MergedLayoutInProps, type MissingPathVariableContext, MissingPathVariableError, type NormalizeResource, type NormalizeResources, type ParameterizedResourcePath, type PathVariables, type PresetPropsFromComposable, PropError, type PropErrorOptions, type PropsContextRender, type PropsRenderDefinition, ReactLayoutError, type ReactLayoutErrorContext, type ReactLayoutErrorRendererFactory, type RenderedPathComponent, type RenderedPathComponentHOF, type RequiredPresetLayoutProps, type RequiredPresetRenderProps, type ResolveLayoutComposables, type ResolveLayoutProps, type ResolveLayoutPropsAsDefined, type ResolveProps, type ResolvedBuiltPropShape, type ResolvedIncludedComponentProps, type ResolvedIncludedConfigProps, type ResolvedIncludedProps, type ResolvedIncludedPropsAsDefined, type ResolvedPathValue, type ResourceDefinition, type ResourceDefinitionValue, type ResourceEnum, type ResourceLayoutComponentProps, type ResourceSelection, type ResourceTree, type Show, type TargetPathBuilder, type UnionToIntersection, collectComposablePresetEntries, createComposableComponent, createLayoutComposableFactory, createPrimitivePropBuilder, createProp, createReactLayoutError, defineComposableComponent, defineResourceLayout, isPropDefinitionShape, makeComposable, normalizeResource, normalizeResources, pick, resolveComposablePresetProps, resolveLayoutComposables, resolvePropDefinitionValues, toResourceEnum, validateProps };
+export { type AnyBuiltPropDefinition, type AnyComposableComponent, type BaseComponent, type ComponentTypes, type ComposableComponent, type ComposableComponentCallable, type ComposableComponents, type ComposableNameContext, type ComposablePresetComponent, type ComposablePresetComponentCallProps, type ComposablePresetMeta, type ComposablePresetProps, type ComposableResourceLayout, type CreateGetComponentForPath, type CreateLayoutComposable, type CreateReactLayoutErrorOptions, type CreateResourceLayoutWithLayoutOptions, type CreatedReactLayoutError, type CreatedResourceConfig, type DefineResourceLayoutWithLayoutFn, type DefineResourcesFn, type DefinedComposableComponentRecord, type DefinedResourceLayoutWithShell, type ErrorMessageRenderer, type ExtractDefinitionValue, type ForPaths, type ForPathsRenderContext, type GetComponentForPath, type InPropsDefinition, type InPropsFunction, type InPropsObject, type InPropsOptions, type IncludedPropBehavior, type IncludedProps, type InferredInProps, type InvalidComponentContext, InvalidComponentError, type InvalidConfigContext, InvalidConfigError, type InvalidPathContext, InvalidPathError, type InvalidResourceContext, InvalidResourceError, type InvalidSubResourceContext, InvalidSubResourceError, type IsSubResourceKey, LayoutComposablePresetProvider, type LayoutComposablesFactory, type LayoutRenderProps, type LayoutRenderResourcesAccessor, type LayoutResourceKey, type LayoutResourcesAccessor, type MakeComposable, type MakeComposableOptions, type MergeIntersection, type MergePresetProps, type MergedLayoutInProps, type MissingPathVariableContext, MissingPathVariableError, type NormalizeResource, type NormalizeResources, type ParameterizedResourcePath, type PathVariables, type PresetPropsFromComposable, PropError, type PropErrorOptions, type PropsContextRender, type PropsRenderDefinition, ReactLayoutError, type ReactLayoutErrorContext, type ReactLayoutErrorRendererFactory, type RenderedPathComponent, type RenderedPathComponentHOF, type RequiredPresetLayoutProps, type RequiredPresetRenderProps, type ResolveLayoutComposables, type ResolveLayoutProps, type ResolveLayoutPropsAsDefined, type ResolveProps, type ResolvedBuiltPropShape, type ResolvedIncludedComponentProps, type ResolvedIncludedConfigProps, type ResolvedIncludedProps, type ResolvedIncludedPropsAsDefined, type ResolvedPathValue, type ResourceDefinition, type ResourceDefinitionValue, type ResourceEnum, type ResourceLayoutComponentProps, type ResourceLayoutShellComponent, type ResourceLayoutShellProps, type ResourceLayoutShellPublisher, type ResourceSelection, type ResourceTree, type ShellLayoutDefinition, type ShellRenderContext, type Show, type TargetPathBuilder, type UnionToIntersection, collectComposablePresetEntries, createComposableComponent, createLayoutComposableFactory, createPrimitivePropBuilder, createProp, createReactLayoutError, defineComposableComponent, defineResourceLayout, isPropDefinitionShape, makeComposable, normalizeResource, normalizeResources, pick, resolveComposablePresetProps, resolveLayoutComposables, resolvePropDefinitionValues, toResourceEnum, validateProps };

package/dist/resource.d.mts

@@ -1,6 +1,6 @@
 import { MergeIntersection, UnionToIntersection } from "./utils.mjs";
-import { NonEmptyReadonlyArray } from "@jfdevelops/react-layout-validator";
 import { ReactNode } from "react";
+import { NonEmptyReadonlyArray } from "@jfdevelops/react-layout-validator";
 
 //#region src/resource.d.ts
 type ResourceDefinition = string | {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jfdevelops/react-layout",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "A React library for creating layout components.",
   "repository": {
     "type": "git",

package/skills/build-react-layouts/SKILL.md

@@ -69,6 +69,10 @@ not-found states.
   add a schema dependency solely to connect a route parameter to a resource.
 - Create a separate `defineResourceLayout` definition for a surface with a
   meaningfully different structural contract, such as a create or detail pane.
+- Reach for `defineResourceLayout.withLayout` when the shared chrome (sidebar,
+  header, subscriptions) must survive navigation between resources. Mount its
+  `Shell` once around the router outlet; keep per-resource structure in
+  `layout.render`, which becomes optional there.
 - Preserve inferred types. Do not use `any`, broad casts, or duplicated
   hand-written resource types to work around a layout mismatch.
 

package/skills/build-react-layouts/references/architecture.md

@@ -6,6 +6,7 @@
 - Shared layout contract
 - Semantic composables
 - Preset composables
+- Persistent application shell
 - Secondary layout families
 - Feature organization
 
@@ -125,6 +126,97 @@ Include the preset's required values in `layout.props.include`. Keep
 presentation in the preset renderer and segment definitions in resource page
 configuration.
 
+## Persist the application shell across navigation
+
+Plain `defineResourceLayout` wraps every page in its own `createResourceLayout`
+component. Navigating between resources unmounts one page component and mounts
+another, so the chrome that `render` produces — a sidebar, a header,
+subscriptions, observers — is rebuilt on every navigation.
+
+Use `defineResourceLayout.withLayout` when that rebuild is a problem. It returns
+a `Shell` component in addition to the usual helpers:
+
+```tsx
+export const {
+  createResourceConfig,
+  createResourceLayout,
+  createResourceLinks,
+  Shell,
+} = defineResourceLayout.withLayout({
+  resources: ['appointments', 'locations', 'services', 'settings'],
+  options: {
+    title: createProp.component({ type: 'ReactNode' }).optional(),
+  },
+  shell: {
+    composables: (create) => ({
+      Layout: create({
+        name: ({ capitalize, resource }) =>
+          resource ? `${capitalize(resource)}Shell` : 'Shell',
+        wrapWith: AppLayout,
+      }),
+    }),
+    render: (_props, { composables, children }) => (
+      <composables.Layout>
+        <AppSidebar />
+        <main>{children}</main>
+      </composables.Layout>
+    ),
+  },
+  layout: {
+    // Optional under `withLayout`. Give a resource its own header or actions
+    // here, or omit `render` entirely and the page renders its children into
+    // the shell's outlet.
+    props: {
+      custom: {
+        children: createProp.component({ type: 'ReactNode' }),
+        actions: createProp.component({ type: 'ReactNode' }).optional(),
+      },
+    },
+    render: ({ children, actions }, { composables }) => (
+      <composables.ResourceLayout>
+        {actions && (
+          <composables.ResourceHeaderActions>
+            {actions}
+          </composables.ResourceHeaderActions>
+        )}
+        {children}
+      </composables.ResourceLayout>
+    ),
+  },
+});
+```
+
+Mount `Shell` once, in the parent route, wrapping the router outlet:
+
+```tsx
+function AdminRoute() {
+  return (
+    <Shell>
+      <Outlet />
+    </Shell>
+  );
+}
+```
+
+The shell's `render` context matches a per-resource `render` context
+(`composables`, `resources`, `name`) plus `children` — the outlet subtree, which
+you place where page content belongs. `resource` and `resources.current` are
+possibly `undefined`: the shell outlives any single page, so the current
+resource is whatever the mounted page reports.
+
+A page created by `createResourceLayout` reports its resource to the shell
+automatically, so resource-scoped composable names still resolve. Pass the
+always-optional `resource` prop to `<Shell>` for routes that render non-library
+content, or in tests and stories:
+
+```tsx
+<Shell resource="appointments">{children}</Shell>
+```
+
+Keep genuinely shared, stateful chrome (sidebar, header, breadcrumb container)
+in `shell`. Keep anything that varies per resource in `layout.render`. Anything
+placed in `shell` cannot read per-page render props.
+
 ## Create secondary layout families
 
 Create another `defineResourceLayout` when a surface has a distinct structural