@contractspec/bundle.library 3.9.7 → 3.9.9

package/src/components/docs/libraries/LibrariesDesignSystemPage.tsx

@@ -88,10 +88,115 @@ const FOCUSED_SUBPATHS_EXAMPLE = `import { themeSpecToTailwindPreset } from '@co
 import { Select } from '@contractspec/lib.design-system/controls';
 import { FormDialog } from '@contractspec/lib.design-system/forms';
 import { HStack } from '@contractspec/lib.design-system/layout';
+import { AdaptivePanel } from '@contractspec/lib.design-system/components/overlays';
+import { ObjectReferenceHandler } from '@contractspec/lib.design-system/components/object-reference';
 
 // Root imports remain supported:
 import { Button, DataTable } from '@contractspec/lib.design-system';`;
 
+const OBJECT_REFERENCE_EXAMPLE = `import {
+  ObjectReferenceHandler,
+  createDefaultObjectReferenceActions,
+  createMapsReferenceActions,
+  type ObjectReferenceDescriptor,
+  type ObjectReferenceOpenHrefHandler,
+} from '@contractspec/lib.design-system';
+
+const customerContact: ObjectReferenceDescriptor = {
+  id: 'user.amina',
+  kind: 'user',
+  label: 'Amina Laurent',
+  description: 'Customer success owner',
+  href: '/customers/acme/users/amina',
+  properties: [
+    {
+      id: 'user.amina.email',
+      kind: 'email',
+      label: 'Email',
+      value: 'amina@example.com',
+    },
+    {
+      id: 'user.amina.phone',
+      kind: 'phone',
+      label: 'Phone',
+      value: '+33 1 23 45 67 89',
+    },
+  ],
+  sections: [
+    {
+      id: 'customer-site',
+      title: 'Primary site',
+      properties: [
+        {
+          id: 'customer-site.address',
+          kind: 'address',
+          label: 'Paris office',
+          value: '10 rue de Rivoli, 75001 Paris',
+          actions: createMapsReferenceActions({
+            id: 'customer-site.address',
+            kind: 'address',
+            label: 'Paris office',
+            value: '10 rue de Rivoli, 75001 Paris',
+          }),
+        },
+      ],
+    },
+  ],
+};
+
+const openHref: ObjectReferenceOpenHrefHandler = (href, _event, options) => {
+  if (options.target === 'new-page') {
+    window.open(href, '_blank', 'noopener,noreferrer');
+    return;
+  }
+
+  window.location.assign(href);
+};
+
+<ObjectReferenceHandler
+  reference={customerContact}
+  actions={createDefaultObjectReferenceActions(customerContact)}
+  interactivityVisibility="icon"
+  openTarget="same-page"
+  panelMode="responsive"
+  mobilePanelMode="drawer"
+  desktopPanelMode="sheet"
+  responsiveBreakpoint="md"
+  openHref={openHref}
+/>;`;
+
+const ADAPTIVE_PANEL_EXAMPLE = `import { AdaptivePanel } from '@contractspec/lib.design-system/components/overlays';
+
+<AdaptivePanel
+  open={open}
+  onOpenChange={setOpen}
+  trigger={<button type="button">Edit</button>}
+  title="Edit customer"
+  description="Update contact and site details."
+  mode="responsive"
+  mobileMode="drawer"
+  desktopMode="sheet"
+  breakpoint="md"
+  sheetSide="right"
+  drawerDirection="bottom"
+>
+  {content}
+</AdaptivePanel>;`;
+
+const OBJECT_REFERENCE_PROMPT = `Find every user-facing address, phone number, email, user, customer, file, URL, and tenant-specific object reference currently rendered as inert text.
+
+Replace each one with ObjectReferenceHandler from @contractspec/lib.design-system. Keep descriptors data-only: id, kind, label, value, href, openTarget, properties, sections, metadata, iconKey, and ariaLabel are allowed; React callbacks belong in handler props only.
+
+Use properties and sections for rich references. For example, a user reference can expose email, phone, address, files, and customer links in one panel instead of rendering separate disconnected strings.
+
+Use panelMode="responsive" by default. Let desktop render a sheet and small screens render a bottom drawer through AdaptivePanel. Do not call Sheet or Drawer directly for this interaction unless a lower-level primitive is being implemented.
+
+Use openTarget="same-page" unless product requirements explicitly require a new page. Put custom copy, navigation, analytics, permissions, or tenant-specific actions in copyHandler, openHref, actionHandlers, onAction, and onActionError.
+
+For addresses, use createMapsReferenceActions so users can choose Google Maps, Apple Maps, or Waze. For email and phone references, prefer createDefaultObjectReferenceActions unless a product-specific action set is required.
+
+After replacing references, verify keyboard access, visible affordance choice (none, underline, or icon), safe href behavior, mobile drawer layout, and desktop sheet layout.`;
+
 export function LibrariesDesignSystemPage() {
 	return (
 		<div className="space-y-8">
@@ -134,6 +239,15 @@ export function LibrariesDesignSystemPage() {
 						<strong>Platform Utilities</strong>: Hooks for responsive and
 						adaptive design
 					</li>
+					<li>
+						<strong>Object References</strong>: Clickable references for
+						addresses, phone numbers, users, customers, files, URLs, and custom
+						objects
+					</li>
+					<li>
+						<strong>Adaptive Panels</strong>: One panel API that resolves to a
+						desktop sheet or mobile drawer
+					</li>
 					<li>
 						<strong>Theme Bridge</strong>: ThemeSpec to Tailwind variables,
 						presets, CSS text, and runtime light/dark mode
@@ -165,6 +279,118 @@ export function LibrariesDesignSystemPage() {
 				<CodeBlock language="tsx" code={FOCUSED_SUBPATHS_EXAMPLE} />
 			</div>
 
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Actionable object references</h2>
+				<p className="text-muted-foreground">
+					Use <code>ObjectReferenceHandler</code> whenever a product surface
+					renders an object that may need quick interaction: addresses, phone
+					numbers, emails, users, customers, files, URLs, and tenant-specific
+					objects. The goal is to avoid inert references while keeping the
+					descriptor contract declarative enough for OSS consumers and future
+					contract-generated surfaces.
+				</p>
+				<div className="grid gap-4 md:grid-cols-2">
+					<div className="card-subtle p-4">
+						<h3 className="mb-2 font-semibold">Descriptor model</h3>
+						<ul className="list-inside list-disc space-y-1 text-muted-foreground text-sm">
+							<li>
+								References use data-only descriptors: <code>id</code>,{' '}
+								<code>kind</code>, <code>label</code>, <code>value</code>,{' '}
+								<code>href</code>, <code>openTarget</code>,{' '}
+								<code>metadata</code>, <code>iconKey</code>, and{' '}
+								<code>ariaLabel</code>.
+							</li>
+							<li>
+								Rich references use nested <code>properties</code> and{' '}
+								<code>sections</code>, so one user or customer can expose email,
+								phone, address, files, and links inside the same panel.
+							</li>
+							<li>
+								Reference kinds are <code>address</code>, <code>email</code>,{' '}
+								<code>phone</code>, <code>user</code>, <code>customer</code>,{' '}
+								<code>file</code>, <code>url</code>, and <code>custom</code>.
+							</li>
+						</ul>
+					</div>
+					<div className="card-subtle p-4">
+						<h3 className="mb-2 font-semibold">Runtime behavior</h3>
+						<ul className="list-inside list-disc space-y-1 text-muted-foreground text-sm">
+							<li>
+								Choose visibility with <code>interactivityVisibility</code>:
+								<code>none</code>, <code>underline</code>, or <code>icon</code>.
+							</li>
+							<li>
+								Detail navigation defaults to <code>same-page</code>; set{' '}
+								<code>openTarget="new-page"</code> on the handler, reference, or
+								action when a new page is required.
+							</li>
+							<li>
+								Host apps provide behavior through <code>copyHandler</code>,{' '}
+								<code>openHref</code>, <code>actionHandlers</code>,{' '}
+								<code>onAction</code>, and <code>onActionError</code>.
+							</li>
+						</ul>
+					</div>
+					<div className="card-subtle p-4">
+						<h3 className="mb-2 font-semibold">Default actions</h3>
+						<ul className="list-inside list-disc space-y-1 text-muted-foreground text-sm">
+							<li>
+								<code>createDefaultObjectReferenceActions</code> adds copy,
+								open, email, phone, and map actions when the descriptor supports
+								them.
+							</li>
+							<li>
+								<code>createMapsReferenceActions</code> creates Google Maps,
+								Apple Maps, Waze, or geo actions for address references.
+							</li>
+							<li>
+								Safe href handling allows expected app, web, email, phone, and
+								map URLs while rejecting unsafe schemes.
+							</li>
+						</ul>
+					</div>
+					<div className="card-subtle p-4">
+						<h3 className="mb-2 font-semibold">Extension points</h3>
+						<ul className="list-inside list-disc space-y-1 text-muted-foreground text-sm">
+							<li>
+								Use <code>renderTrigger</code>, <code>renderDetail</code>,{' '}
+								<code>renderAction</code>, <code>renderProperty</code>,{' '}
+								<code>renderSection</code>, and <code>iconRenderer</code> to
+								wrap or overload presentation.
+							</li>
+							<li>
+								Keep tenant-specific permissions, analytics, and integration
+								side effects at the host boundary through runtime handlers.
+							</li>
+						</ul>
+					</div>
+				</div>
+				<CodeBlock language="tsx" code={OBJECT_REFERENCE_EXAMPLE} />
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Adaptive panels</h2>
+				<p className="text-muted-foreground">
+					<code>AdaptivePanel</code> is the shared overlay decision for surfaces
+					that should feel native on both desktop and small screens. Its default
+					responsive mode renders a sheet at the configured desktop breakpoint
+					and a drawer below it. <code>ObjectReferenceHandler</code> uses this
+					panel contract through <code>panelMode</code>,{' '}
+					<code>mobilePanelMode</code>, <code>desktopPanelMode</code>, and{' '}
+					<code>responsiveBreakpoint</code>.
+				</p>
+				<CodeBlock language="tsx" code={ADAPTIVE_PANEL_EXAMPLE} />
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Prompt for adoption work</h2>
+				<p className="text-muted-foreground">
+					Use this prompt when asking an agent or downstream OSS consumer to
+					replace inert references across an application.
+				</p>
+				<CodeBlock language="text" code={OBJECT_REFERENCE_PROMPT} />
+			</div>
+
 			<div className="space-y-4">
 				<h2 className="font-bold text-2xl">Data table example</h2>
 				<p className="text-muted-foreground">
@@ -187,6 +413,7 @@ export function LibrariesDesignSystemPage() {
 					<div className="card-subtle p-4">
 						<h3 className="mb-2 font-semibold">Organisms</h3>
 						<ul className="space-y-1 text-muted-foreground text-sm">
+							<li>AppShell, PageOutline</li>
 							<li>AppLayout, AppHeader, AppSidebar</li>
 							<li>MarketingLayout, HeroSection</li>
 							<li>ListCardPage, ListTablePage</li>
@@ -217,6 +444,15 @@ export function LibrariesDesignSystemPage() {
 							<li>PackageManagerProvider</li>
 						</ul>
 					</div>
+					<div className="card-subtle p-4">
+						<h3 className="mb-2 font-semibold">References & Overlays</h3>
+						<ul className="space-y-1 text-muted-foreground text-sm">
+							<li>ObjectReferenceHandler</li>
+							<li>createDefaultObjectReferenceActions</li>
+							<li>createMapsReferenceActions</li>
+							<li>AdaptivePanel</li>
+						</ul>
+					</div>
 				</div>
 			</div>
 
@@ -224,6 +460,14 @@ export function LibrariesDesignSystemPage() {
 				<h2 className="font-bold text-2xl">Where this layer fits</h2>
 				<p className="text-muted-foreground">
 					Read{' '}
+					<Link
+						href="/docs/libraries/application-shell"
+						className="text-[color:var(--rust)] underline underline-offset-4"
+					>
+						Application shell
+					</Link>{' '}
+					for the shared sidebar, topbar, command search, mobile navigation, and{' '}
+					<code>PageOutline</code> pattern. Read{' '}
 					<Link
 						href="/docs/libraries/cross-platform-ui"
 						className="text-[color:var(--rust)] underline underline-offset-4"

package/src/components/docs/libraries/LibrariesOverviewPage.tsx

@@ -30,6 +30,12 @@ const libraryGroups = [
 					'Run typed capability surfaces, execute policies, and connect runtime adapters.',
 				href: '/docs/libraries/runtime',
 			},
+			{
+				title: '@contractspec/lib.translation-runtime',
+				description:
+					'Resolve ContractSpec TranslationSpec catalogs with ICU formatting, SSR snapshots, BCP 47 locales, overrides, and optional i18next projection.',
+				href: '/docs/libraries/translation-runtime',
+			},
 			{
 				title: '@contractspec/lib.ui-kit',
 				description:
@@ -45,9 +51,15 @@ const libraryGroups = [
 			{
 				title: '@contractspec/lib.design-system',
 				description:
-					'Build higher-level product surfaces and documented marketing/docs primitives on top of the web and native UI packages.',
+					'Build higher-level product surfaces, actionable object references, adaptive panels, and documented marketing/docs primitives on top of the web and native UI packages.',
 				href: '/docs/libraries/design-system',
 			},
+			{
+				title: 'Application shell',
+				description:
+					'Adopt the shared sidebar, topbar, command search, notifications, mobile navigation, and PageOutline patterns for product apps.',
+				href: '/docs/libraries/application-shell',
+			},
 			{
 				title: 'Cross-platform UI',
 				description:

package/src/components/docs/libraries/LibrariesPersonalizationPage.tsx

@@ -1,31 +1,93 @@
 import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import { HStack, VStack } from '@contractspec/lib.design-system/layout';
+import {
+	Code,
+	H1,
+	H2,
+	P,
+	Text,
+} from '@contractspec/lib.design-system/typography';
 import Link from '@contractspec/lib.ui-link';
 import { ChevronRight } from 'lucide-react';
 
+const DATA_VIEW_PREFERENCE_EXAMPLE = `import { DataViewRenderer } from '@contractspec/lib.design-system';
+import { resolveDataViewPreferences } from '@contractspec/lib.personalization/data-view-preferences';
+
+const resolved = resolveDataViewPreferences({
+  spec: AccountsDataView,
+  preferences: profile.canonical,
+  insights,
+  record: savedAccountViewPreference,
+});
+
+return (
+  <DataViewRenderer
+    spec={AccountsDataView}
+    items={accounts}
+    defaultViewMode={resolved.viewMode}
+    defaultDensity={resolved.density}
+    defaultDataDepth={resolved.dataDepth}
+    pagination={{
+      page,
+      pageSize: resolved.pageSize ?? 25,
+      total,
+    }}
+  />
+);`;
+
+const DATA_VIEW_TRACKING_EXAMPLE = `tracker.trackDataViewInteraction({
+  dataViewKey: AccountsDataView.meta.key,
+  dataViewVersion: AccountsDataView.meta.version,
+  action: 'view_mode_changed',
+  viewMode: 'grid',
+});
+
+tracker.trackDataViewInteraction({
+  dataViewKey: AccountsDataView.meta.key,
+  action: 'data_depth_changed',
+  dataDepth: 'detailed',
+});
+
+tracker.trackDataViewInteraction({
+  dataViewKey: AccountsDataView.meta.key,
+  action: 'filter_changed',
+  filterKey: 'status',
+});`;
+
+const DATA_VIEW_PERSONALIZATION_PROMPT = `Add DataView personalization for <screen>.
+
+Acceptance criteria:
+- Resolve viewMode, density, dataDepth, and pageSize with resolveDataViewPreferences.
+- Apply resolved values to DataViewRenderer as default or controlled props.
+- Track opened, view_mode_changed, density_changed, data_depth_changed, search_changed, filter_changed, sort_changed, and page_changed actions with trackDataViewInteraction.
+- Persist only the dimensions allowed by view.collection.personalization.persist.
+- Ignore behavior-derived modes that are not allowed by view.collection.viewModes.allowedModes.
+- Do not import React or design-system code into @contractspec/lib.personalization helpers.`;
+
 export function LibrariesPersonalizationPage() {
 	return (
-		<div className="space-y-8">
-			<div className="space-y-4">
-				<h1 className="font-bold text-4xl">
+		<VStack className="space-y-8">
+			<VStack className="space-y-4">
+				<H1 className="font-bold text-4xl">
 					@contractspec/lib.personalization
-				</h1>
-				<p className="text-lg text-muted-foreground">
+				</H1>
+				<P className="text-lg text-muted-foreground">
 					Track field/feature/workflow usage, analyze drop-offs, and convert
 					insights into OverlaySpecs or workflow tweaks.
-				</p>
-			</div>
+				</P>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Installation</h2>
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Installation</H2>
 				<InstallCommand package="@contractspec/lib.personalization" />
-			</div>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Tracker</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Tracker</H2>
+				<P className="text-muted-foreground">
 					Buffer events per tenant/user and emit OpenTelemetry counters
 					automatically.
-				</p>
+				</P>
 				<CodeBlock
 					language="typescript"
 					code={`import { createBehaviorTracker } from '@contractspec/lib.personalization';
@@ -38,29 +100,65 @@ const tracker = createBehaviorTracker({
 tracker.trackFieldAccess({ operation: 'billing.createOrder', field: 'items' });
 tracker.trackWorkflowStep({ workflow: 'invoice', step: 'review', status: 'entered' });`}
 				/>
-			</div>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">DataView Preferences</H2>
+				<P className="text-muted-foreground">
+					Use <Code>resolveDataViewPreferences</Code> when a collection DataView
+					should honor a user's preferred list/grid/table mode, compact or
+					comfortable density, data depth, and page size. The helper returns
+					plain values that can be passed into the renderer without coupling the
+					design-system package to personalization. Start from the{' '}
+					<Link
+						href="/docs/libraries/data-views"
+						className="text-[color:var(--rust)] underline underline-offset-4"
+					>
+						<Text>DataViews runtime guide</Text>
+					</Link>{' '}
+					when you need the contract and renderer shape.
+				</P>
+				<CodeBlock language="tsx" code={DATA_VIEW_PREFERENCE_EXAMPLE} />
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Analyzer</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">DataView Interaction Events</H2>
+				<P className="text-muted-foreground">
+					Track <Code>data_view_interaction</Code> events for view mode,
+					density, data depth, search, filters, sorting, and pagination. The
+					in-memory store summarizes those events, and the analyzer can derive a
+					scoped preferred collection mode from valid interaction counts.
+				</P>
+				<CodeBlock language="typescript" code={DATA_VIEW_TRACKING_EXAMPLE} />
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Analyzer</H2>
+				<P className="text-muted-foreground">
 					Summarize events and highlight unused UI, frequent fields, and
 					workflow bottlenecks.
-				</p>
+				</P>
 				<CodeBlock
 					language="typescript"
 					code={`import { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';
 
 const analyzer = new BehaviorAnalyzer(store);
 const insights = await analyzer.analyze({ tenantId: 'acme', userId: 'ops-42' });
-// { unusedFields: ['internalNotes'], workflowBottlenecks: [...] }`}
+// {
+//   unusedFields: ['internalNotes'],
+//   workflowBottlenecks: [...],
+//   dataViewPreferences: {
+//     'crm.accounts': { preferredViewMode: 'grid' }
+//   }
+// }`}
 				/>
-			</div>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Adapter</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Adapter</H2>
+				<P className="text-muted-foreground">
 					Convert insights into overlays or workflow extension hints.
-				</p>
+				</P>
 				<CodeBlock
 					language="typescript"
 					code={`import { insightsToOverlaySuggestion } from '@contractspec/lib.personalization/adapter';
@@ -71,16 +169,28 @@ const overlay = insightsToOverlaySuggestion(insights, {
   capability: 'billing.createOrder',
 });`}
 				/>
-			</div>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Agent Prompt</H2>
+				<P className="text-muted-foreground">
+					Use this when asking an agent to wire DataView preferences while
+					preserving the personalization/design-system boundary.
+				</P>
+				<CodeBlock
+					language="markdown"
+					code={DATA_VIEW_PERSONALIZATION_PROMPT}
+				/>
+			</VStack>
 
-			<div className="flex items-center gap-4 pt-4">
+			<HStack className="items-center gap-4 pt-4">
 				<Link href="/docs/libraries" className="btn-ghost">
-					Back to Libraries
+					<Text>Back to Libraries</Text>
 				</Link>
 				<Link href="/docs/libraries/overlay-engine" className="btn-primary">
-					Next: Overlay Engine <ChevronRight size={16} />
+					<Text>Next: Overlay Engine</Text> <ChevronRight size={16} />
 				</Link>
-			</div>
-		</div>
+			</HStack>
+		</VStack>
 	);
 }

package/src/components/docs/libraries/LibrariesTranslationRuntimePage.content.ts

@@ -0,0 +1,78 @@
+export const translationRuntimeInstall = [
+	'@contractspec/lib.contracts-spec',
+	'@contractspec/lib.translation-runtime',
+];
+
+export const translationRuntimeExample = `import { createTranslationRuntime } from '@contractspec/lib.translation-runtime';
+import { checkoutMessages } from './translations/checkout.messages';
+
+const runtime = createTranslationRuntime({
+  catalogs: [checkoutMessages],
+  locale: 'fr-FR',
+  fallbackLocales: ['fr', 'en-US'],
+  onDiagnostic: (diagnostic) => reportTranslationIssue(diagnostic),
+});
+
+const label = runtime.t('checkout.pay', {
+  amount: 4200,
+  currency: 'EUR',
+});`;
+
+export const i18nextAdapterExample = `import { createInstance } from 'i18next';
+import {
+  createI18nextInitOptions,
+  exportContractSpecToI18next,
+} from '@contractspec/lib.translation-runtime/i18next';
+
+const exported = exportContractSpecToI18next([checkoutMessages], {
+  locale: 'en-US',
+  assumeIcuFormatter: true,
+});
+const { options, diagnostics } = createI18nextInitOptions(exported, {
+  lng: 'en-US',
+});
+
+const i18next = createInstance();
+await i18next.init(options);
+reportAdapterDiagnostics(diagnostics);`;
+
+export const ssrHydrationExample = `// Server: negotiate once, preload catalogs, and serialize the runtime snapshot.
+const runtime = createTranslationRuntime({
+  catalogs,
+  locale: negotiatedLocale,
+  fallbackLocales,
+});
+const snapshot = runtime.createSnapshot();
+
+// Client: hydrate from the same snapshot so locale, resources, and fallback state match.
+const hydratedRuntime = createTranslationRuntime({ snapshot });`;
+
+export const translationRuntimeChecks = [
+	'Keep TranslationSpec as the source of truth; do not flatten metadata into i18next JSON as the canonical model.',
+	'Keep stable bundle identity in TranslationSpec.meta.key and keep BCP 47 language tags in TranslationSpec.locale.',
+	'Use ICU messages for plural, select, selectordinal, number, date, currency, list, and relative-time formatting.',
+	'Create one runtime per SSR request when tenant, project, or user overrides are involved.',
+	'Serialize the same runtime snapshot or exported adapter resources used by the server for hydration.',
+	'Configure an ICU-capable i18next formatter plugin when rendering ContractSpec ICU messages through i18next.',
+	'Treat adapter diagnostics as release blockers in production pipelines instead of silently rendering raw keys.',
+];
+
+export const translationRuntimePrompt = `You are integrating ContractSpec translations into a production app.
+Use @contractspec/lib.contracts-spec/translations as the canonical contract layer and @contractspec/lib.translation-runtime as the runtime layer.
+Keep locale variants separate from stable bundle keys, support BCP 47 tags, preserve ICU plural/select/selectordinal messages, and use request-scoped runtime instances for SSR.
+If the app already uses i18next, use @contractspec/lib.translation-runtime/i18next only as a downstream adapter. Do not make i18next the canonical translation model. Include diagnostics, fallback behavior, tenant/user override isolation, and hydration snapshot handling in the implementation and tests.`;
+
+export const translationRuntimeLayers = [
+	{
+		title: 'Spec layer',
+		body: 'TranslationSpec owns keys, locales, domains, versions, owners, fallback declarations, direction, and validation metadata.',
+	},
+	{
+		title: 'Runtime layer',
+		body: 'Runtime instances negotiate locales, apply fallback chains, resolve overrides, cache compiled messages, report diagnostics, and serialize SSR snapshots.',
+	},
+	{
+		title: 'Adapter layer',
+		body: 'The i18next adapter projects ContractSpec specs or snapshots to resources and manifests for caller-owned i18next instances.',
+	},
+];