@contractspec/bundle.library 3.9.8 → 3.9.9

package/dist/components/docs/libraries/LibrariesApplicationShellPage.content.d.ts

@@ -1,16 +1,33 @@
-export declare const shellUsageExample = "import {\n  AppShell,\n  PageOutline,\n  type AppShellNavigationSection,\n  type PageOutlineItem,\n} from \"@contractspec/lib.design-system/shell\";\n\nconst navigation: AppShellNavigationSection[] = [\n  {\n    title: \"Workspace\",\n    items: [\n      { label: \"Dashboard\", href: \"/dashboard\" },\n      {\n        label: \"Contracts\",\n        href: \"/contracts\",\n        children: [\n          { label: \"Operations\", href: \"/contracts/operations\" },\n          { label: \"Events\", href: \"/contracts/events\" },\n        ],\n      },\n    ],\n  },\n];\n\nconst outline: PageOutlineItem[] = [\n  {\n    id: \"architecture\",\n    label: \"Architecture\",\n    level: 1,\n    children: [\n      { id: \"desktop\", label: \"Desktop shell\", level: 2 },\n      { id: \"mobile\", label: \"Mobile adaptation\", level: 2 },\n    ],\n  },\n];\n\nexport function WorkspacePage() {\n  return (\n    <AppShell\n      brand={{ label: \"ContractSpec\", href: \"/dashboard\" }}\n      navigation={navigation}\n      breadcrumbs={[\n        { label: \"Workspace\", href: \"/dashboard\" },\n        { label: \"Contracts\" },\n      ]}\n      command={{\n        placeholder: \"Search contracts or run an action\",\n        groups: [\n          {\n            title: \"Quick actions\",\n            actions: [\n              { id: \"new-contract\", label: \"New contract\" },\n              { id: \"import\", label: \"Import existing app\" },\n            ],\n          },\n        ],\n      }}\n      user={{\n        name: \"Ada Lovelace\",\n        email: \"ada@example.com\",\n        actions: [{ label: \"Sign out\", onSelect: () => signOut() }],\n      }}\n      pageOutline={<PageOutline items={outline} activeId=\"desktop\" />}\n    >\n      <main>{/* route content */}</main>\n    </AppShell>\n  );\n}";
-export declare const scratchPrompt = "You are implementing a modern application shell from scratch.\n\nGoal:\nBuild a reusable application shell for a React/Next.js web app and an Expo React Native app. The shell must provide a desktop sidebar, desktop topbar, command search, breadcrumbs, nested navigation, user/auth actions, and an in-page section navigator called PageOutline.\n\nUse this architecture:\n- Keep route content independent from navigation chrome.\n- Create a typed navigation model with sections, items, active state, optional children, badges, icons, disabled items, and href/onSelect support.\n- Create a command model with search input, grouped suggestions, quick actions, keyboard shortcut labels, empty state, and loading state.\n- Create a breadcrumb model for the topbar.\n- Create a PageOutline model for right-side in-page navigation with exactly three supported levels. It should render anchors, support active section state, and degrade gracefully when no sections exist.\n- Expose the system from the design system or a dedicated shell module, not from a single app route.\n\nDesktop behavior:\n- Persistent left sidebar with app logo/title, command trigger, grouped navigation, nested submenus, and current user/auth/logout area.\n- Topbar with breadcrumbs and an optional command trigger.\n- Content area with optional right PageOutline.\n- Keep dimensions stable. Navigation labels must not resize layout on hover or active state.\n\nMobile web behavior:\n- Use bottom navigation for the primary destinations.\n- Put deeper navigation, command search, auth actions, and secondary actions behind a menu or drawer.\n- Keep route content first and make the shell controls reachable without covering important content.\n\nNative behavior:\n- Add .native.tsx entrypoints for Expo/React Native.\n- Prefer bottom tabs for primary destinations and a menu/sheet for deeper navigation and account actions.\n- Keep the same typed navigation, command, breadcrumb, and PageOutline data contracts across web and native.\n\nImplementation constraints:\n- Reuse the existing design-system primitives, tokens, icons, and accessibility patterns.\n- Do not hardcode app-specific routes in the shell component.\n- Do not introduce a new dependency unless the repo already uses it for dialogs, menus, icons, or navigation.\n- Include tests for navigation rendering, nested items, command filtering, breadcrumbs, PageOutline level handling, active section state, and mobile/native adaptation contracts.\n- Update docs and exports so developers can import the shell from a stable public API.\n\nDeliverables:\n- Typed shell models.\n- Web shell components.\n- Native shell components or adapters.\n- PageOutline component with three-level support.\n- Usage example.\n- Focused tests and typecheck/build evidence.";
-export declare const refactorPrompt = "You are refactoring an existing application to use the shared application shell system.\n\nGoal:\nReplace app-specific sidebar, topbar, breadcrumb, command palette, account menu, mobile navigation, and in-page table-of-contents code with the shared AppShell and PageOutline system.\n\nStart by auditing:\n- Current layout wrappers and route groups.\n- Sidebar, topbar, breadcrumb, command/search, auth menu, and mobile navigation implementations.\n- Any duplicated navigation arrays, route labels, icon maps, access-control checks, and active-state logic.\n- Any in-page summary/table-of-contents components that should become PageOutline data.\n- Web-only assumptions that would block Expo/React Native adaptation.\n\nRefactor plan:\n1. Define a single typed navigation source for primary nav, grouped sidebar nav, nested children, labels, icons, badges, disabled states, and permissions.\n2. Map existing command/search behavior into grouped command actions with search text and quick actions.\n3. Map existing route metadata into breadcrumbs.\n4. Convert page table-of-contents or section summary data into PageOutline items with a maximum of three levels.\n5. Wrap app routes in AppShell while keeping page content components route-local.\n6. Move primary mobile destinations into bottom navigation and deeper/account actions into a menu or drawer.\n7. Add or preserve .native.tsx adapters when the app targets Expo.\n\nPreserve behavior:\n- Existing route URLs and access rules.\n- Existing keyboard shortcuts where they are public behavior.\n- Existing analytics or telemetry events on navigation and command actions.\n- Existing auth/logout behavior.\n- Existing responsive breakpoints unless there is a documented design-system breakpoint to adopt.\n\nQuality gates:\n- Add regression tests around current visible navigation before removing old shell code when coverage is missing.\n- Test active nav state, nested nav expansion, command search/action invocation, breadcrumbs, auth menu, mobile bottom navigation, and PageOutline anchor behavior.\n- Run lint, typecheck, and the app's relevant test/build command.\n- Remove dead app-specific shell components only after the shared shell path is verified.\n\nOutput:\n- List old shell files removed or simplified.\n- List new shared shell integration points.\n- Include before/after route coverage and verification commands.";
+export declare const shellUsageExample = "import {\n  AppShell,\n  type ShellCommandGroup,\n  type ShellNavSection,\n  type ShellNotificationCenter,\n  type PageOutlineItem,\n} from \"@contractspec/lib.design-system/shell\";\n\nconst navigation: ShellNavSection[] = [\n  {\n    title: \"Workspace\",\n    items: [\n      { label: \"Dashboard\", href: \"/dashboard\" },\n      {\n        label: \"Contracts\",\n        href: \"/contracts\",\n        children: [\n          { label: \"Operations\", href: \"/contracts/operations\" },\n          { label: \"Events\", href: \"/contracts/events\" },\n        ],\n      },\n    ],\n  },\n];\n\nconst commands: ShellCommandGroup[] = [\n  {\n    heading: \"Quick actions\",\n    items: [\n      { id: \"new-contract\", label: \"New contract\", shortcut: \"N\" },\n      { id: \"import\", label: \"Import existing app\" },\n    ],\n  },\n];\n\nconst outline: PageOutlineItem[] = [\n  {\n    id: \"architecture\",\n    label: \"Architecture\",\n    level: 1,\n    children: [\n      { id: \"desktop\", label: \"Desktop shell\", level: 2 },\n      { id: \"mobile\", label: \"Mobile adaptation\", level: 2 },\n    ],\n  },\n];\n\nconst notifications: ShellNotificationCenter = {\n  label: \"Notifications\",\n  loading: false,\n  unreadCount: 2,\n  items: [\n    {\n      id: \"contract-approved\",\n      title: \"Contract approved\",\n      body: \"Billing.create is ready to publish.\",\n      status: \"unread\",\n      createdAt: \"2026-04-29T09:30:00Z\",\n      actionUrl: \"/contracts/billing.create\",\n      category: \"Review\",\n    },\n  ],\n  onSelect: (item) => openNotificationTarget(item),\n  onMarkRead: (item) => markNotificationRead(item.id),\n  onMarkAllRead: () => markAllNotificationsRead(),\n};\n\nexport function WorkspacePage() {\n  return (\n    <AppShell\n      title=\"ContractSpec\"\n      homeHref=\"/dashboard\"\n      navigation={navigation}\n      commands={commands}\n      breadcrumbs={[\n        { label: \"Workspace\", href: \"/dashboard\" },\n        { label: \"Contracts\" },\n      ]}\n      notifications={notifications}\n      pageOutline={outline}\n      activeHref=\"/contracts\"\n      activeOutlineId=\"desktop\"\n      userMenu={<UserMenu onSignOut={() => signOut()} />}\n    >\n      <main>{/* route content */}</main>\n    </AppShell>\n  );\n}";
+export declare const notificationCenterExample = "import {\n  ListNotificationsOutputModel,\n  MarkNotificationReadInputModel,\n} from \"@contractspec/lib.contracts-spec/notifications\";\nimport {\n  notificationsSchemaContribution,\n  renderNotificationTemplate,\n} from \"@contractspec/lib.notification\";\nimport type { ShellNotificationCenter } from \"@contractspec/lib.design-system/shell\";\n\ntype NotificationListResult = {\n  unreadCount: number;\n  notifications: Array<{\n    id: string;\n    title: string;\n    body: string;\n    type: string;\n    status: string;\n    readAt?: string | Date | null;\n    createdAt: string | Date;\n    actionUrl?: string;\n    metadata?: Record<string, unknown>;\n  }>;\n};\n\nexport function toShellNotifications(\n  data: NotificationListResult,\n  actions: {\n    open: (id: string) => void;\n    markRead: (input: { notificationId: string }) => void;\n    markAllRead: () => void;\n  }\n): ShellNotificationCenter {\n  return {\n    unreadCount: data.unreadCount,\n    items: data.notifications.map((notification) => ({\n      id: notification.id,\n      title: notification.title,\n      body: notification.body,\n      status: notification.status,\n      createdAt: notification.createdAt,\n      actionUrl: notification.actionUrl,\n      category: notification.type,\n      metadata: notification.metadata,\n    })),\n    onSelect: (item) => actions.open(item.id),\n    onMarkRead: (item) => actions.markRead({ notificationId: item.id }),\n    onMarkAllRead: actions.markAllRead,\n  };\n}\n\nvoid ListNotificationsOutputModel;\nvoid MarkNotificationReadInputModel;\nvoid notificationsSchemaContribution;\nvoid renderNotificationTemplate;";
+export declare const scratchPrompt = "You are implementing a modern application shell from scratch.\n\nGoal:\nBuild a reusable application shell for a React/Next.js web app and an Expo React Native app. The shell must provide a desktop sidebar, desktop topbar, command search, breadcrumbs, nested navigation, user/auth actions, in-app notifications, and an in-page section navigator called PageOutline.\n\nUse this architecture:\n- Keep route content independent from navigation chrome.\n- Create a typed navigation model with sections, items, active state, optional children, badges, icons, disabled items, and href/onSelect support.\n- Create a command model with search input, grouped suggestions, quick actions, keyboard shortcut labels, empty state, and loading state.\n- Create a breadcrumb model for the topbar.\n- Create a PageOutline model for right-side in-page navigation with exactly three supported levels. It should render anchors, support active section state, and degrade gracefully when no sections exist.\n- Create a ShellNotificationCenter model with render-ready items, unread count, loading and empty states, onSelect, onMarkRead, onMarkAllRead, and optional custom item rendering.\n- Expose the system from the design system or a dedicated shell module, not from a single app route.\n\nNotification boundary:\n- Use @contractspec/lib.contracts-spec/notifications as the canonical source for notification contracts, operation models, and feature metadata.\n- Use @contractspec/lib.notification for reusable notification entities, schema contribution, channels, templates, and i18n helpers.\n- Keep persistence, polling/subscriptions, delivery providers, and optimistic mutations in the host application or notification runtime layer.\n- Pass only render-ready ShellNotificationCenter state into AppShell so the design system does not import or own notification runtime behavior.\n\nDesktop behavior:\n- Persistent left sidebar with app logo/title, command trigger, grouped navigation, nested submenus, and current user/auth/logout area.\n- Topbar with breadcrumbs and an optional command trigger.\n- Topbar notification trigger with unread badge, loading/empty states, mark-read actions, and item selection.\n- Content area with optional right PageOutline.\n- Keep dimensions stable. Navigation labels must not resize layout on hover or active state.\n\nMobile web behavior:\n- Use bottom navigation for the primary destinations.\n- Put deeper navigation, command search, notifications, auth actions, and secondary actions behind a menu or drawer when the topbar cannot safely hold them.\n- Keep route content first and make the shell controls reachable without covering important content.\n\nNative behavior:\n- Add .native.tsx entrypoints for Expo/React Native.\n- Prefer bottom tabs for primary destinations and a menu/sheet for deeper navigation, notifications, and account actions.\n- Keep the same typed navigation, command, breadcrumb, notification, and PageOutline data contracts across web and native.\n\nImplementation constraints:\n- Reuse the existing design-system primitives, tokens, icons, and accessibility patterns.\n- Do not hardcode app-specific routes in the shell component.\n- Do not introduce a new dependency unless the repo already uses it for dialogs, menus, icons, or navigation.\n- Include tests for navigation rendering, nested items, command filtering, breadcrumbs, notification unread badge/loading/empty/callback behavior, PageOutline level handling, active section state, and mobile/native adaptation contracts.\n- Update docs and exports so developers can import the shell from a stable public API.\n\nDeliverables:\n- Typed shell models.\n- Web shell components.\n- Native shell components or adapters.\n- PageOutline component with three-level support.\n- ShellNotifications or equivalent notification center component for web and native shell placement.\n- Usage example.\n- Focused tests and typecheck/build evidence.";
+export declare const refactorPrompt = "You are refactoring an existing application to use the shared application shell system.\n\nGoal:\nReplace app-specific sidebar, topbar, breadcrumb, command palette, notification badge/inbox, account menu, mobile navigation, and in-page table-of-contents code with the shared AppShell, ShellNotifications, and PageOutline system.\n\nStart by auditing:\n- Current layout wrappers and route groups.\n- Sidebar, topbar, breadcrumb, command/search, auth menu, and mobile navigation implementations.\n- Existing notification badges, inbox panels, toasts that represent durable in-app items, unread count queries, mark-read actions, and delivery modules.\n- Imports from @contractspec/module.notifications that should migrate to @contractspec/lib.contracts-spec/notifications or @contractspec/lib.notification.\n- Any duplicated navigation arrays, route labels, icon maps, access-control checks, and active-state logic.\n- Any in-page summary/table-of-contents components that should become PageOutline data.\n- Web-only assumptions that would block Expo/React Native adaptation.\n\nRefactor plan:\n1. Define a single typed navigation source for primary nav, grouped sidebar nav, nested children, labels, icons, badges, disabled states, and permissions.\n2. Map existing command/search behavior into grouped command actions with search text and quick actions.\n3. Map existing route metadata into breadcrumbs.\n4. Move canonical notification contracts to @contractspec/lib.contracts-spec/notifications and reusable helpers to @contractspec/lib.notification; keep the old module shim only for compatibility imports that still need the legacy module id.\n5. Convert notification query results into ShellNotificationCenter items with unreadCount, loading, empty state, onSelect, onMarkRead, and onMarkAllRead callbacks.\n6. Convert page table-of-contents or section summary data into PageOutline items with a maximum of three levels.\n7. Wrap app routes in AppShell while keeping page content components route-local.\n8. Move primary mobile destinations into bottom navigation and deeper/account/notification actions into a menu or drawer.\n9. Add or preserve .native.tsx adapters when the app targets Expo.\n\nPreserve behavior:\n- Existing route URLs and access rules.\n- Existing keyboard shortcuts where they are public behavior.\n- Existing analytics or telemetry events on navigation and command actions.\n- Existing notification delivery semantics, unread count semantics, deep links, and mark-read behavior.\n- Existing auth/logout behavior.\n- Existing responsive breakpoints unless there is a documented design-system breakpoint to adopt.\n\nQuality gates:\n- Add regression tests around current visible navigation before removing old shell code when coverage is missing.\n- Test active nav state, nested nav expansion, command search/action invocation, breadcrumbs, notification unread badge/loading/empty/callback behavior, auth menu, mobile bottom navigation, and PageOutline anchor behavior.\n- Run lint, typecheck, and the app's relevant test/build command.\n- Remove dead app-specific shell components only after the shared shell path is verified.\n\nOutput:\n- List old shell files removed or simplified.\n- List new shared shell integration points.\n- Include before/after route coverage and verification commands.";
+export declare const notificationGuide: readonly [{
+    readonly title: "Contracts stay canonical";
+    readonly body: "Use @contractspec/lib.contracts-spec/notifications for operation models, feature metadata, and contract-level compatibility.";
+}, {
+    readonly title: "Runtime helpers stay reusable";
+    readonly body: "Use @contractspec/lib.notification for schema contribution, channel adapters, templates, and i18n without importing the deprecated module shim in new code.";
+}, {
+    readonly title: "Apps own live state";
+    readonly body: "Fetch, subscribe, persist, mutate, and reconcile notification state in the host app or runtime layer where auth and tenancy are known.";
+}, {
+    readonly title: "Shell receives view state";
+    readonly body: "Pass AppShell a ShellNotificationCenter with render-ready items, counts, loading state, and callbacks; the design system only renders affordances.";
+}];
 export declare const shellParts: readonly [{
     readonly title: "Sidebar";
     readonly body: "Desktop owns brand, command entry, grouped navigation, nested items, and account actions in one persistent scanning area.";
 }, {
     readonly title: "Topbar";
-    readonly body: "Breadcrumbs stay visible while the current route changes. The command trigger can live here when the sidebar is collapsed or hidden.";
+    readonly body: "Breadcrumbs stay visible while the current route changes. Command search and notification affordances can live here when the sidebar is collapsed or hidden.";
 }, {
     readonly title: "PageOutline";
     readonly body: "The right-side in-page navigator replaces ad hoc tables of contents. It supports three levels of section anchors and active state.";
+}, {
+    readonly title: "Notifications";
+    readonly body: "The shell renders unread badges, item lists, loading/empty states, mark-read actions, and deep-link selection from host-owned notification state.";
 }, {
     readonly title: "Mobile adapters";
-    readonly body: "Small web and native surfaces move primary destinations to bottom navigation and reserve drawers or menus for deep navigation and account actions.";
+    readonly body: "Small web and native surfaces move primary destinations to bottom navigation and reserve drawers or menus for deep navigation, notifications, and account actions.";
 }];

package/dist/components/docs/libraries/LibrariesApplicationShellPage.content.js

@@ -1,12 +1,13 @@
 // @bun
-var n=Object.defineProperty;var o=(e)=>e;function i(e,t){this[e]=o.bind(null,t)}var s=(e,t)=>{for(var a in t)n(e,a,{get:t[a],enumerable:!0,configurable:!0,set:i.bind(t,a)})};var r=(e,t)=>()=>(e&&(t=e(e=0)),t);var c=`import {
+var i=Object.defineProperty;var n=(e)=>e;function o(e,t){this[e]=n.bind(null,t)}var s=(e,t)=>{for(var a in t)i(e,a,{get:t[a],enumerable:!0,configurable:!0,set:o.bind(t,a)})};var r=(e,t)=>()=>(e&&(t=e(e=0)),t);var l=`import {
   AppShell,
-  PageOutline,
-  type AppShellNavigationSection,
+  type ShellCommandGroup,
+  type ShellNavSection,
+  type ShellNotificationCenter,
   type PageOutlineItem,
 } from "@contractspec/lib.design-system/shell";
 
-const navigation: AppShellNavigationSection[] = [
+const navigation: ShellNavSection[] = [
   {
     title: "Workspace",
     items: [
@@ -23,6 +24,16 @@ const navigation: AppShellNavigationSection[] = [
   },
 ];
 
+const commands: ShellCommandGroup[] = [
+  {
+    heading: "Quick actions",
+    items: [
+      { id: "new-contract", label: "New contract", shortcut: "N" },
+      { id: "import", label: "Import existing app" },
+    ],
+  },
+];
+
 const outline: PageOutlineItem[] = [
   {
     id: "architecture",
@@ -35,41 +46,104 @@ const outline: PageOutlineItem[] = [
   },
 ];
 
+const notifications: ShellNotificationCenter = {
+  label: "Notifications",
+  loading: false,
+  unreadCount: 2,
+  items: [
+    {
+      id: "contract-approved",
+      title: "Contract approved",
+      body: "Billing.create is ready to publish.",
+      status: "unread",
+      createdAt: "2026-04-29T09:30:00Z",
+      actionUrl: "/contracts/billing.create",
+      category: "Review",
+    },
+  ],
+  onSelect: (item) => openNotificationTarget(item),
+  onMarkRead: (item) => markNotificationRead(item.id),
+  onMarkAllRead: () => markAllNotificationsRead(),
+};
+
 export function WorkspacePage() {
   return (
     <AppShell
-      brand={{ label: "ContractSpec", href: "/dashboard" }}
+      title="ContractSpec"
+      homeHref="/dashboard"
       navigation={navigation}
+      commands={commands}
       breadcrumbs={[
         { label: "Workspace", href: "/dashboard" },
         { label: "Contracts" },
       ]}
-      command={{
-        placeholder: "Search contracts or run an action",
-        groups: [
-          {
-            title: "Quick actions",
-            actions: [
-              { id: "new-contract", label: "New contract" },
-              { id: "import", label: "Import existing app" },
-            ],
-          },
-        ],
-      }}
-      user={{
-        name: "Ada Lovelace",
-        email: "ada@example.com",
-        actions: [{ label: "Sign out", onSelect: () => signOut() }],
-      }}
-      pageOutline={<PageOutline items={outline} activeId="desktop" />}
+      notifications={notifications}
+      pageOutline={outline}
+      activeHref="/contracts"
+      activeOutlineId="desktop"
+      userMenu={<UserMenu onSignOut={() => signOut()} />}
     >
       <main>{/* route content */}</main>
     </AppShell>
   );
-}`,d=`You are implementing a modern application shell from scratch.
+}`,d=`import {
+  ListNotificationsOutputModel,
+  MarkNotificationReadInputModel,
+} from "@contractspec/lib.contracts-spec/notifications";
+import {
+  notificationsSchemaContribution,
+  renderNotificationTemplate,
+} from "@contractspec/lib.notification";
+import type { ShellNotificationCenter } from "@contractspec/lib.design-system/shell";
+
+type NotificationListResult = {
+  unreadCount: number;
+  notifications: Array<{
+    id: string;
+    title: string;
+    body: string;
+    type: string;
+    status: string;
+    readAt?: string | Date | null;
+    createdAt: string | Date;
+    actionUrl?: string;
+    metadata?: Record<string, unknown>;
+  }>;
+};
+
+export function toShellNotifications(
+  data: NotificationListResult,
+  actions: {
+    open: (id: string) => void;
+    markRead: (input: { notificationId: string }) => void;
+    markAllRead: () => void;
+  }
+): ShellNotificationCenter {
+  return {
+    unreadCount: data.unreadCount,
+    items: data.notifications.map((notification) => ({
+      id: notification.id,
+      title: notification.title,
+      body: notification.body,
+      status: notification.status,
+      createdAt: notification.createdAt,
+      actionUrl: notification.actionUrl,
+      category: notification.type,
+      metadata: notification.metadata,
+    })),
+    onSelect: (item) => actions.open(item.id),
+    onMarkRead: (item) => actions.markRead({ notificationId: item.id }),
+    onMarkAllRead: actions.markAllRead,
+  };
+}
+
+void ListNotificationsOutputModel;
+void MarkNotificationReadInputModel;
+void notificationsSchemaContribution;
+void renderNotificationTemplate;`,p=`You are implementing a modern application shell from scratch.
 
 Goal:
-Build a reusable application shell for a React/Next.js web app and an Expo React Native app. The shell must provide a desktop sidebar, desktop topbar, command search, breadcrumbs, nested navigation, user/auth actions, and an in-page section navigator called PageOutline.
+Build a reusable application shell for a React/Next.js web app and an Expo React Native app. The shell must provide a desktop sidebar, desktop topbar, command search, breadcrumbs, nested navigation, user/auth actions, in-app notifications, and an in-page section navigator called PageOutline.
 
 Use this architecture:
 - Keep route content independent from navigation chrome.
@@ -77,29 +151,37 @@ Use this architecture:
 - Create a command model with search input, grouped suggestions, quick actions, keyboard shortcut labels, empty state, and loading state.
 - Create a breadcrumb model for the topbar.
 - Create a PageOutline model for right-side in-page navigation with exactly three supported levels. It should render anchors, support active section state, and degrade gracefully when no sections exist.
+- Create a ShellNotificationCenter model with render-ready items, unread count, loading and empty states, onSelect, onMarkRead, onMarkAllRead, and optional custom item rendering.
 - Expose the system from the design system or a dedicated shell module, not from a single app route.
 
+Notification boundary:
+- Use @contractspec/lib.contracts-spec/notifications as the canonical source for notification contracts, operation models, and feature metadata.
+- Use @contractspec/lib.notification for reusable notification entities, schema contribution, channels, templates, and i18n helpers.
+- Keep persistence, polling/subscriptions, delivery providers, and optimistic mutations in the host application or notification runtime layer.
+- Pass only render-ready ShellNotificationCenter state into AppShell so the design system does not import or own notification runtime behavior.
+
 Desktop behavior:
 - Persistent left sidebar with app logo/title, command trigger, grouped navigation, nested submenus, and current user/auth/logout area.
 - Topbar with breadcrumbs and an optional command trigger.
+- Topbar notification trigger with unread badge, loading/empty states, mark-read actions, and item selection.
 - Content area with optional right PageOutline.
 - Keep dimensions stable. Navigation labels must not resize layout on hover or active state.
 
 Mobile web behavior:
 - Use bottom navigation for the primary destinations.
-- Put deeper navigation, command search, auth actions, and secondary actions behind a menu or drawer.
+- Put deeper navigation, command search, notifications, auth actions, and secondary actions behind a menu or drawer when the topbar cannot safely hold them.
 - Keep route content first and make the shell controls reachable without covering important content.
 
 Native behavior:
 - Add .native.tsx entrypoints for Expo/React Native.
-- Prefer bottom tabs for primary destinations and a menu/sheet for deeper navigation and account actions.
-- Keep the same typed navigation, command, breadcrumb, and PageOutline data contracts across web and native.
+- Prefer bottom tabs for primary destinations and a menu/sheet for deeper navigation, notifications, and account actions.
+- Keep the same typed navigation, command, breadcrumb, notification, and PageOutline data contracts across web and native.
 
 Implementation constraints:
 - Reuse the existing design-system primitives, tokens, icons, and accessibility patterns.
 - Do not hardcode app-specific routes in the shell component.
 - Do not introduce a new dependency unless the repo already uses it for dialogs, menus, icons, or navigation.
-- Include tests for navigation rendering, nested items, command filtering, breadcrumbs, PageOutline level handling, active section state, and mobile/native adaptation contracts.
+- Include tests for navigation rendering, nested items, command filtering, breadcrumbs, notification unread badge/loading/empty/callback behavior, PageOutline level handling, active section state, and mobile/native adaptation contracts.
 - Update docs and exports so developers can import the shell from a stable public API.
 
 Deliverables:
@@ -107,15 +189,18 @@ Deliverables:
 - Web shell components.
 - Native shell components or adapters.
 - PageOutline component with three-level support.
+- ShellNotifications or equivalent notification center component for web and native shell placement.
 - Usage example.
-- Focused tests and typecheck/build evidence.`,p=`You are refactoring an existing application to use the shared application shell system.
+- Focused tests and typecheck/build evidence.`,m=`You are refactoring an existing application to use the shared application shell system.
 
 Goal:
-Replace app-specific sidebar, topbar, breadcrumb, command palette, account menu, mobile navigation, and in-page table-of-contents code with the shared AppShell and PageOutline system.
+Replace app-specific sidebar, topbar, breadcrumb, command palette, notification badge/inbox, account menu, mobile navigation, and in-page table-of-contents code with the shared AppShell, ShellNotifications, and PageOutline system.
 
 Start by auditing:
 - Current layout wrappers and route groups.
 - Sidebar, topbar, breadcrumb, command/search, auth menu, and mobile navigation implementations.
+- Existing notification badges, inbox panels, toasts that represent durable in-app items, unread count queries, mark-read actions, and delivery modules.
+- Imports from @contractspec/module.notifications that should migrate to @contractspec/lib.contracts-spec/notifications or @contractspec/lib.notification.
 - Any duplicated navigation arrays, route labels, icon maps, access-control checks, and active-state logic.
 - Any in-page summary/table-of-contents components that should become PageOutline data.
 - Web-only assumptions that would block Expo/React Native adaptation.
@@ -124,25 +209,28 @@ Refactor plan:
 1. Define a single typed navigation source for primary nav, grouped sidebar nav, nested children, labels, icons, badges, disabled states, and permissions.
 2. Map existing command/search behavior into grouped command actions with search text and quick actions.
 3. Map existing route metadata into breadcrumbs.
-4. Convert page table-of-contents or section summary data into PageOutline items with a maximum of three levels.
-5. Wrap app routes in AppShell while keeping page content components route-local.
-6. Move primary mobile destinations into bottom navigation and deeper/account actions into a menu or drawer.
-7. Add or preserve .native.tsx adapters when the app targets Expo.
+4. Move canonical notification contracts to @contractspec/lib.contracts-spec/notifications and reusable helpers to @contractspec/lib.notification; keep the old module shim only for compatibility imports that still need the legacy module id.
+5. Convert notification query results into ShellNotificationCenter items with unreadCount, loading, empty state, onSelect, onMarkRead, and onMarkAllRead callbacks.
+6. Convert page table-of-contents or section summary data into PageOutline items with a maximum of three levels.
+7. Wrap app routes in AppShell while keeping page content components route-local.
+8. Move primary mobile destinations into bottom navigation and deeper/account/notification actions into a menu or drawer.
+9. Add or preserve .native.tsx adapters when the app targets Expo.
 
 Preserve behavior:
 - Existing route URLs and access rules.
 - Existing keyboard shortcuts where they are public behavior.
 - Existing analytics or telemetry events on navigation and command actions.
+- Existing notification delivery semantics, unread count semantics, deep links, and mark-read behavior.
 - Existing auth/logout behavior.
 - Existing responsive breakpoints unless there is a documented design-system breakpoint to adopt.
 
 Quality gates:
 - Add regression tests around current visible navigation before removing old shell code when coverage is missing.
-- Test active nav state, nested nav expansion, command search/action invocation, breadcrumbs, auth menu, mobile bottom navigation, and PageOutline anchor behavior.
+- Test active nav state, nested nav expansion, command search/action invocation, breadcrumbs, notification unread badge/loading/empty/callback behavior, auth menu, mobile bottom navigation, and PageOutline anchor behavior.
 - Run lint, typecheck, and the app's relevant test/build command.
 - Remove dead app-specific shell components only after the shared shell path is verified.
 
 Output:
 - List old shell files removed or simplified.
 - List new shared shell integration points.
-- Include before/after route coverage and verification commands.`,m=[{title:"Sidebar",body:"Desktop owns brand, command entry, grouped navigation, nested items, and account actions in one persistent scanning area."},{title:"Topbar",body:"Breadcrumbs stay visible while the current route changes. The command trigger can live here when the sidebar is collapsed or hidden."},{title:"PageOutline",body:"The right-side in-page navigator replaces ad hoc tables of contents. It supports three levels of section anchors and active state."},{title:"Mobile adapters",body:"Small web and native surfaces move primary destinations to bottom navigation and reserve drawers or menus for deep navigation and account actions."}];export{c as shellUsageExample,m as shellParts,d as scratchPrompt,p as refactorPrompt};
+- Include before/after route coverage and verification commands.`,u=[{title:"Contracts stay canonical",body:"Use @contractspec/lib.contracts-spec/notifications for operation models, feature metadata, and contract-level compatibility."},{title:"Runtime helpers stay reusable",body:"Use @contractspec/lib.notification for schema contribution, channel adapters, templates, and i18n without importing the deprecated module shim in new code."},{title:"Apps own live state",body:"Fetch, subscribe, persist, mutate, and reconcile notification state in the host app or runtime layer where auth and tenancy are known."},{title:"Shell receives view state",body:"Pass AppShell a ShellNotificationCenter with render-ready items, counts, loading state, and callbacks; the design system only renders affordances."}],h=[{title:"Sidebar",body:"Desktop owns brand, command entry, grouped navigation, nested items, and account actions in one persistent scanning area."},{title:"Topbar",body:"Breadcrumbs stay visible while the current route changes. Command search and notification affordances can live here when the sidebar is collapsed or hidden."},{title:"PageOutline",body:"The right-side in-page navigator replaces ad hoc tables of contents. It supports three levels of section anchors and active state."},{title:"Notifications",body:"The shell renders unread badges, item lists, loading/empty states, mark-read actions, and deep-link selection from host-owned notification state."},{title:"Mobile adapters",body:"Small web and native surfaces move primary destinations to bottom navigation and reserve drawers or menus for deep navigation, notifications, and account actions."}];export{l as shellUsageExample,h as shellParts,p as scratchPrompt,m as refactorPrompt,u as notificationGuide,d as notificationCenterExample};