@contractspec/bundle.library 3.9.0 → 3.9.3

package/src/components/docs/generated/docs-index.workspace-cli.json

@@ -1,10 +1,10 @@
 [
-  {
-    "id": "workspace-cli/workspace-cli",
-    "title": "workspace-cli",
-    "summary": "Core CLI operations for managing ContractSpec workspaces\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: @lssm/core\n- **Tags**: cli, core\n- **File**: `packages/bundles/workspace/src/contracts/features/cli.feature.ts`",
-    "route": "/docs/reference/workspace-cli/workspace-cli",
-    "source": "generated",
-    "contentPath": "workspace-cli/workspace-cli.md"
-  }
-]
+	{
+		"id": "workspace-cli/workspace-cli",
+		"title": "workspace-cli",
+		"summary": "Core CLI operations for managing ContractSpec workspaces\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: @lssm/core\n- **Tags**: cli, core\n- **File**: `packages/bundles/workspace/src/contracts/features/cli.feature.ts`",
+		"route": "/docs/reference/workspace-cli/workspace-cli",
+		"source": "generated",
+		"contentPath": "workspace-cli/workspace-cli.md"
+	}
+]

package/src/components/docs/generated/index.ts

@@ -3,8 +3,23 @@ export type {
 	DocsIndexManifest,
 	DocsIndexSource,
 } from './docs-index.generated';
-export {
-	getDocsIndexManifest,
-	getGeneratedDocById,
-	listGeneratedDocs,
-} from './loader';
+
+import type { DocsIndexEntry, DocsIndexManifest } from './docs-index.generated';
+
+export async function getDocsIndexManifest(): Promise<DocsIndexManifest> {
+	const { getDocsIndexManifest: loadManifest } = await import('./loader');
+	return loadManifest();
+}
+
+export async function listGeneratedDocs(): Promise<readonly DocsIndexEntry[]> {
+	const { listGeneratedDocs: loadDocs } = await import('./loader');
+	return loadDocs();
+}
+
+export async function getGeneratedDocById(id: string): Promise<{
+	entry: DocsIndexEntry;
+	content: string;
+} | null> {
+	const { getGeneratedDocById: loadDoc } = await import('./loader');
+	return loadDoc(id);
+}

package/src/components/docs/generated/loader.ts

@@ -1,10 +1,14 @@
 import { readFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { DocsIndexEntry, DocsIndexManifest } from './docs-index.generated';
 import { DOCS_INDEX_MANIFEST } from './docs-index.generated';
 
-const baseDir = dirname(fileURLToPath(import.meta.url));
+const baseDir = path.dirname(fileURLToPath(import.meta.url));
+const generatedDocsContentRoot = path.join(
+	baseDir,
+	'../../../../../../../generated/docs'
+);
 let manifestPromise: Promise<DocsIndexManifest> | null = null;
 let docsPromise: Promise<DocsIndexEntry[]> | null = null;
 const chunkCache = new Map<string, Promise<DocsIndexEntry[]>>();
@@ -21,7 +25,7 @@ function chunkKeyForId(id: string): string {
 async function loadManifest(): Promise<DocsIndexManifest> {
 	if (!manifestPromise) {
 		manifestPromise = readFile(
-			join(baseDir, /* turbopackIgnore: true */ DOCS_INDEX_MANIFEST),
+			path.join(/*turbopackIgnore: true*/ baseDir, DOCS_INDEX_MANIFEST),
 			'utf8'
 		).then((content) => JSON.parse(content) as DocsIndexManifest);
 	}
@@ -30,7 +34,10 @@ async function loadManifest(): Promise<DocsIndexManifest> {
 
 function resolveContentRoot(manifest: DocsIndexManifest): string {
 	const root = manifest.contentRoot ?? '.';
-	return join(baseDir, /* turbopackIgnore: true */ root);
+	if (root === '../../../../../../../generated/docs') {
+		return generatedDocsContentRoot;
+	}
+	return path.join(/*turbopackIgnore: true*/ baseDir, root);
 }
 
 async function loadChunk(fileName: string): Promise<DocsIndexEntry[]> {
@@ -38,7 +45,7 @@ async function loadChunk(fileName: string): Promise<DocsIndexEntry[]> {
 	if (cached) return cached;
 
 	const load = readFile(
-		join(baseDir, /* turbopackIgnore: true */ fileName),
+		path.join(/*turbopackIgnore: true*/ baseDir, fileName),
 		'utf8'
 	).then((content) => JSON.parse(content) as DocsIndexEntry[]);
 	chunkCache.set(fileName, load);
@@ -76,9 +83,9 @@ export async function getGeneratedDocById(id: string): Promise<{
 	const entry = entries.find((doc) => doc.id === id);
 	if (!entry || !entry.contentPath) return null;
 
-	const contentPath = join(
-		resolveContentRoot(manifest),
-		/* turbopackIgnore: true */ entry.contentPath
+	const contentPath = path.join(
+		/*turbopackIgnore: true*/ resolveContentRoot(manifest),
+		entry.contentPath
 	);
 	try {
 		const content = await readFile(contentPath, 'utf8');

package/src/components/docs/getting-started/CompatibilityPage.tsx

@@ -59,6 +59,20 @@ export function CompatibilityPage() {
 						<li>Custom adapters for other SQL/NoSQL stores</li>
 					</ul>
 				</div>
+
+				<div className="card-subtle space-y-3 p-6">
+					<h2 className="font-bold text-2xl">Cross-platform UI architecture</h2>
+					<p className="text-muted-foreground">
+						Need the React and React Native component compatibility story? Read{' '}
+						<Link
+							href="/docs/libraries/cross-platform-ui"
+							className="text-[color:var(--rust)] underline underline-offset-4"
+						>
+							Cross-platform UI
+						</Link>{' '}
+						for the runtime and UI-layer split.
+					</p>
+				</div>
 			</div>
 
 			<div className="flex flex-wrap items-center gap-3 pt-2">

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

@@ -0,0 +1,252 @@
+export const layerCards = [
+	{
+		title: '@contractspec/lib.presentation-runtime-core',
+		body: 'Shared state, table models, workflow logic, visualization helpers, and the alias helpers consumed by web and native builds.',
+	},
+	{
+		title: '@contractspec/lib.presentation-runtime-react',
+		body: 'React-facing hooks such as useContractTable, useDataViewTable, and useWorkflow. This is the shared hook surface most product code starts from.',
+	},
+	{
+		title: '@contractspec/lib.presentation-runtime-react-native',
+		body: 'Native entrypoint for mobile apps. It re-exports the shared table and data-view hooks so the controller API stays aligned with the React package.',
+	},
+	{
+		title: '@contractspec/lib.ui-kit-web',
+		body: 'Browser-first primitives and accessibility helpers. Reach for this layer when you want direct control over the web renderer.',
+	},
+	{
+		title: '@contractspec/lib.ui-kit',
+		body: 'Native-first primitives for Expo and React Native. Reach for this layer when the render surface should stay mobile-native.',
+	},
+	{
+		title: '@contractspec/lib.design-system',
+		body: 'Composed components, ThemeSpec/TranslationSpec-aware controls, token helpers, and paired web/mobile implementations that sit on top of both UI kits.',
+	},
+] as const;
+export const hookCards = [
+	{
+		title: 'useContractTable',
+		body: 'Use this when your rows and column definitions already live in product code and you want one headless controller for sorting, pagination, selection, visibility, pinning, sizing, and expansion.',
+	},
+	{
+		title: 'useDataViewTable',
+		body: 'Use this when the table should stay driven by a DataViewSpec instead of hand-authored columns. It adapts the spec to the same generic controller model.',
+	},
+	{
+		title: 'Native re-export boundary',
+		body: 'On native apps, import the same hook names from @contractspec/lib.presentation-runtime-react-native when you want the import path itself to signal a mobile boundary.',
+	},
+] as const;
+export const aliasSetupCards = [
+	{
+		title: 'Next.js / Turbopack',
+		body: 'Use withPresentationTurbopackAliases as the default path in current Next.js apps. It patches nextConfig.turbopack instead of mutating a webpack config object.',
+	},
+	{
+		title: 'Next.js / Webpack fallback',
+		body: 'Use withPresentationWebpackAliases only when a Next.js app explicitly opts back into webpack via the CLI flags.',
+	},
+	{
+		title: 'Expo / Metro',
+		body: 'Use withPresentationMetroAliases on Metro when native platforms should resolve web ui-kit /ui imports and the shared React runtime root to native implementations.',
+	},
+] as const;
+export const designSystemHelperCards = [
+	{
+		title: 'withPlatformUI',
+		body: 'Use this lightweight adapter when a design-system surface needs one object that carries the current platform, tokens, and breakpoints.',
+	},
+	{
+		title: 'mapTokensForPlatform',
+		body: 'Use this when resolved tokens need to be mapped into platform-specific token shapes before the final renderer consumes them.',
+	},
+] as const;
+export const remapCards = [
+	{
+		title: 'What Webpack remaps',
+		items: [
+			'@contractspec/lib.ui-kit -> @contractspec/lib.ui-kit-web',
+			'@contractspec/lib.presentation-runtime-react-native -> @contractspec/lib.presentation-runtime-react',
+			'Prepends .web.js, .web.jsx, .web.ts, and .web.tsx to webpack resolve.extensions',
+		],
+	},
+	{
+		title: 'What Turbopack remaps',
+		items: [
+			'@contractspec/lib.ui-kit -> @contractspec/lib.ui-kit-web',
+			'@contractspec/lib.presentation-runtime-react-native -> @contractspec/lib.presentation-runtime-react',
+			'Initializes or merges turbopack.resolveExtensions with a web-first extension list',
+		],
+	},
+	{
+		title: 'What Metro remaps',
+		items: [
+			'@contractspec/lib.ui-kit-web/ui/* -> @contractspec/lib.ui-kit/ui/* on ios/android/native/mobile',
+			'Root @contractspec/lib.presentation-runtime-react -> @contractspec/lib.presentation-runtime-react-native',
+			'Enables package exports and expands platform resolution ordering',
+		],
+	},
+] as const;
+export const layoutRules = [
+	'Set gap, align, justify, and wrap explicitly in shared code because defaults are not identical between web and native.',
+	'Shared-safe subset: VStack, HStack, and Box with className, gap, align, justify, and wrap.',
+	'Web-only feature: as lets stack primitives emit semantic elements such as section, header, main, or article.',
+	'Native-only extras: spacing, width, and padding exist on the native stack primitives and should stay out of shared renderer code.',
+	'HStack and Box reverse-wrap tokens differ: wrapReverse on web, reverse on native. Prefer nowrap or wrap in shared code.',
+	'Box defaults to nowrap on web and wrap on native, so shared code should set wrap intentionally.',
+] as const;
+
+export const gotchas = [
+	'withPresentationNextAliases no longer exists. Use withPresentationTurbopackAliases for the default Next.js path or withPresentationWebpackAliases for explicit webpack fallback.',
+	'Prefer root runtime imports when alias helpers matter. Metro remaps the root @contractspec/lib.presentation-runtime-react package, not arbitrary deep hook subpaths.',
+	'Metro only rewrites @contractspec/lib.ui-kit-web/ui/* imports. Router-specific web packages and other web-only helpers still need platform-aware imports.',
+	'presentation-runtime-core is headless. It owns models and config helpers, not rendered React components.',
+	'design-system compatibility comes from paired .tsx / .mobile.tsx implementations and token helpers such as withPlatformUI and mapTokensForPlatform.',
+	'Form controls should come from @contractspec/lib.design-system when product code needs ThemeSpec or TranslationSpec support.',
+	'Stack primitives are similar across platforms, but the prop surface is not identical. Stay inside the common subset for shared renderers.',
+	'Alias helpers solve module resolution only. They do not replace app-level monorepo watchFolders, Expo Router setup, or other Next configuration.',
+] as const;
+
+export const markdownKitIntro =
+	'Copy these markdown snippets into your own AGENTS.md, LLM guide, README, or engineering playbook when you want to enforce the same cross-surface rules across customer projects.';
+
+export const turbopackAliasExample = `import { withPresentationTurbopackAliases } from '@contractspec/lib.presentation-runtime-core';
+
+/** @type {import('next').NextConfig} */
+const nextConfig = withPresentationTurbopackAliases({
+  turbopack: {
+    resolveAlias: {
+      fs: { browser: 'browserify-fs' },
+    },
+  },
+});
+
+export default nextConfig;`;
+
+export const webpackAliasExample = `import { withPresentationWebpackAliases } from '@contractspec/lib.presentation-runtime-core';
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  webpack: (config) => withPresentationWebpackAliases(config),
+};
+
+export default nextConfig;`;
+
+export const metroAliasExample = `const { getDefaultConfig } = require('expo/metro-config');
+const {
+  withPresentationMetroAliases,
+} = require('@contractspec/lib.presentation-runtime-core');
+
+const projectRoot = __dirname;
+const config = getDefaultConfig(projectRoot);
+
+module.exports = withPresentationMetroAliases(config);`;
+
+export const designSystemHelperExample = [
+	'import {',
+	'  defaultTokens,',
+	'  mapTokensForPlatform,',
+	'  withPlatformUI,',
+	"} from '@contractspec/lib.design-system';",
+	'',
+	"const nativeTokens = mapTokensForPlatform('native', defaultTokens);",
+	'',
+	'const ui = withPlatformUI({',
+	'  tokens: defaultTokens,',
+	"  platform: 'web',",
+	'});',
+	'',
+	'// ui is a lightweight config object for design-system consumers.',
+	'// nativeTokens is the mapped token shape for a native renderer.',
+].join('\n');
+
+export const stackExample = `import { Box, HStack, VStack } from '@contractspec/lib.ui-kit-web/ui/stack';
+
+export function AccountSummaryHeader() {
+  return (
+    <VStack gap="lg" align="stretch" className="w-full">
+      <HStack gap="sm" align="center" justify="between" wrap="wrap">
+        <Box gap="xs" align="center" justify="start" wrap="nowrap">
+          <StatusDot />
+          <Title />
+        </Box>
+        <Actions />
+      </HStack>
+      <Filters />
+    </VStack>
+  );
+}
+
+// In native-only files, swap the import to:
+// @contractspec/lib.ui-kit/ui/stack
+//
+// On web-only pages, VStack / HStack / Box also support:
+// <VStack as="section">...</VStack>`;
+
+export const renderingExample = `import { DataTable as DesignSystemTable } from '@contractspec/lib.design-system';
+import { DataTable as NativeTable } from '@contractspec/lib.ui-kit/ui/data-table';
+import { DataTable as WebTable } from '@contractspec/lib.ui-kit-web/ui/data-table';
+import { useContractTable } from '@contractspec/lib.presentation-runtime-react';
+
+export function useAccountsController(data, columns) {
+  return useContractTable({
+    data,
+    columns,
+    selectionMode: 'single',
+    initialState: {
+      sorting: [{ id: 'arr', desc: true }],
+      pagination: { pageIndex: 0, pageSize: 5 },
+    },
+  });
+}
+
+export function WebAccounts({ controller }) {
+  return <WebTable controller={controller} />;
+}
+
+export function NativeAccounts({ controller }) {
+  return <NativeTable controller={controller} />;
+}
+
+export function ProductAccounts({ controller }) {
+  return (
+    <DesignSystemTable
+      controller={controller}
+      title="Accounts"
+      description="Same controller, composed ContractSpec shell."
+    />
+  );
+}
+
+// If the table is spec-driven instead of hand-authored,
+// swap useContractTable for useDataViewTable.`;
+
+export const customerPolicyMarkdown = `# Cross-Surface Rendering Policy
+
+- Import runtime bundler helpers from \`@contractspec/lib.presentation-runtime-core\` root only.
+- Use \`withPresentationTurbopackAliases\` for default Next.js projects.
+- Use \`withPresentationWebpackAliases\` only when the app explicitly opts into webpack.
+- Use \`withPresentationMetroAliases\` for Expo and Metro builds.
+- Prefer \`@contractspec/lib.design-system\` for shared product-facing surfaces.
+- Use design-system controls when a field must respect ThemeSpec component variants or TranslationSpec messages.
+- Use \`@contractspec/lib.ui-kit-web\` only for web-specific primitive lanes.
+- Use \`@contractspec/lib.ui-kit\` only for native-specific primitive lanes.
+- Keep shared layout code inside the common \`VStack\` / \`HStack\` / \`Box\` subset.
+- Do not use removed \`withPresentationNextAliases\`.
+- Treat \`.tsx\` / \`.mobile.tsx\` pairs as the standard design-system compatibility boundary.`;
+
+export const customerChecklistMarkdown = `# Cross-Surface Rendering Checklist
+
+1. Configure the bundler aliases before sharing any UI code.
+2. Choose the controller layer:
+   - use \`useContractTable\` for app-owned rows and columns
+   - use \`useDataViewTable\` for DataViewSpec-driven tables
+3. Choose the renderer lane:
+   - web primitive: \`@contractspec/lib.ui-kit-web\`
+   - native primitive: \`@contractspec/lib.ui-kit\`
+   - shared product surface: \`@contractspec/lib.design-system\`
+4. Verify mirrored \`.tsx\` / \`.mobile.tsx\` implementations where the design-system owns the surface.
+5. Wrap product surfaces in \`DesignSystemThemeProvider\` and \`DesignSystemTranslationProvider\` when ThemeSpec or TranslationSpec data is available.
+6. In shared layout code, set \`gap\`, \`align\`, \`justify\`, and \`wrap\` explicitly.
+7. Check docs and examples for root imports and current helper names before copying them into product code.`;

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

@@ -0,0 +1,232 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import {
+	aliasSetupCards,
+	customerChecklistMarkdown,
+	customerPolicyMarkdown,
+	designSystemHelperCards,
+	designSystemHelperExample,
+	gotchas,
+	hookCards,
+	layerCards,
+	layoutRules,
+	markdownKitIntro,
+	metroAliasExample,
+	remapCards,
+	renderingExample,
+	stackExample,
+	turbopackAliasExample,
+	webpackAliasExample,
+} from './LibrariesCrossPlatformUIPage.content';
+
+export function LibrariesCrossPlatformUIPage() {
+	return (
+		<div className="space-y-8">
+			<div className="space-y-4">
+				<h1 className="font-bold text-4xl">Cross-platform UI</h1>
+				<p className="text-lg text-muted-foreground">
+					How ContractSpec keeps React and React Native components compatible by
+					splitting responsibility across shared runtime models, platform
+					primitives, resolver aliases, and the composed design-system layer.
+				</p>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">What cross-platform means here</h2>
+				<p className="text-muted-foreground">
+					The shared rendering story is layered: the core package owns models
+					and resolver helpers, the React packages own hook APIs, the UI kits
+					own raw primitives, and the design-system owns the higher-level
+					product surfaces that pair web and mobile implementations.
+				</p>
+				<div className="grid gap-4 md:grid-cols-2">
+					{layerCards.map((card) => (
+						<div
+							key={card.title}
+							className="rounded-[20px] border border-border/70 p-4"
+						>
+							<h3 className="font-semibold text-base">{card.title}</h3>
+							<p className="mt-2 text-muted-foreground text-sm leading-7">
+								{card.body}
+							</p>
+						</div>
+					))}
+				</div>
+
+				<div className="grid gap-4 md:grid-cols-3">
+					{hookCards.map((card) => (
+						<div key={card.title} className="card-subtle p-4">
+							<h3 className="font-semibold">{card.title}</h3>
+							<p className="mt-2 text-muted-foreground text-sm leading-7">
+								{card.body}
+							</p>
+						</div>
+					))}
+				</div>
+
+				<div className="grid gap-4 lg:grid-cols-[1.1fr_0.9fr]">
+					<div className="grid gap-4 md:grid-cols-2">
+						{designSystemHelperCards.map((card) => (
+							<div key={card.title} className="card-subtle p-4">
+								<h3 className="font-semibold">{card.title}</h3>
+								<p className="mt-2 text-muted-foreground text-sm leading-7">
+									{card.body}
+								</p>
+							</div>
+						))}
+					</div>
+					<CodeBlock
+						language="typescript"
+						filename="design-system-platform.ts"
+						code={designSystemHelperExample}
+					/>
+				</div>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Resolver and alias setup</h2>
+				<p className="text-muted-foreground">
+					Teach the bundler what “web” and “native” mean before you try to share
+					component code. These helpers are public from the root
+					<code> @contractspec/lib.presentation-runtime-core </code>
+					entrypoint.
+				</p>
+				<div className="grid gap-4 md:grid-cols-2">
+					{aliasSetupCards.map((card) => (
+						<div key={card.title} className="card-subtle p-4">
+							<h3 className="font-semibold">{card.title}</h3>
+							<p className="mt-2 text-muted-foreground text-sm leading-7">
+								{card.body}
+							</p>
+						</div>
+					))}
+				</div>
+				<div className="grid gap-4 xl:grid-cols-3">
+					<CodeBlock
+						language="typescript"
+						filename="next.config.mjs"
+						code={turbopackAliasExample}
+					/>
+					<CodeBlock
+						language="typescript"
+						filename="next.config.mjs"
+						code={webpackAliasExample}
+					/>
+					<CodeBlock
+						language="javascript"
+						filename="metro.config.js"
+						code={metroAliasExample}
+					/>
+				</div>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">How the remapping works</h2>
+				<p className="text-muted-foreground">
+					The helpers are intentionally asymmetric because Turbopack patches the
+					Next config object, Webpack mutates a resolver config, and Metro maps
+					modules at request time for native platforms.
+				</p>
+				<div className="grid gap-4 xl:grid-cols-3">
+					{remapCards.map((card) => (
+						<div key={card.title} className="card-subtle p-4">
+							<h3 className="font-semibold">{card.title}</h3>
+							<ul className="mt-2 space-y-2 text-muted-foreground text-sm leading-7">
+								{card.items.map((item) => (
+									<li key={item}>{item}</li>
+								))}
+							</ul>
+						</div>
+					))}
+				</div>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Layout primitives</h2>
+				<p className="text-muted-foreground">
+					<code>VStack</code>, <code>HStack</code>, and <code>Box</code> are the
+					closest thing to a shared layout vocabulary, but their defaults and a
+					few props still differ across the web and native packages.
+				</p>
+				<div className="grid gap-4 md:grid-cols-2">
+					{layoutRules.map((rule) => (
+						<div
+							key={rule}
+							className="card-subtle p-4 text-muted-foreground text-sm leading-7"
+						>
+							{rule}
+						</div>
+					))}
+				</div>
+				<CodeBlock
+					language="tsx"
+					filename="stack-layout.tsx"
+					code={stackExample}
+				/>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Rendering patterns</h2>
+				<p className="text-muted-foreground">
+					Keep the controller stable, then decide whether the final surface
+					should be a raw web primitive, a raw native primitive, or a composed
+					design-system wrapper.
+				</p>
+				<CodeBlock
+					language="tsx"
+					filename="cross-platform-rendering.tsx"
+					code={renderingExample}
+				/>
+				<div className="card-subtle p-4 text-muted-foreground text-sm leading-7">
+					For higher-level shared rendering, use the design-system surfaces that
+					already ship paired implementations such as{' '}
+					<code>DataViewRenderer</code>, <code>ListTablePage</code>, and{' '}
+					<code>DataTable</code>. The web and mobile files stay separate inside
+					the package while your app imports one design-system boundary.
+				</div>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Gotchas and boundaries</h2>
+				<ul className="space-y-2 text-muted-foreground leading-7">
+					{gotchas.map((item) => (
+						<li key={item}>{item}</li>
+					))}
+				</ul>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Customer markdown kit</h2>
+				<p className="text-muted-foreground">{markdownKitIntro}</p>
+				<div className="grid gap-4 xl:grid-cols-2">
+					<CodeBlock
+						language="markdown"
+						filename="cross-surface-policy.md"
+						code={customerPolicyMarkdown}
+					/>
+					<CodeBlock
+						language="markdown"
+						filename="cross-surface-checklist.md"
+						code={customerChecklistMarkdown}
+					/>
+				</div>
+			</div>
+
+			<div className="flex flex-wrap items-center gap-3 pt-2">
+				<Link href="/docs/libraries/runtime" className="btn-ghost">
+					Runtime libraries
+				</Link>
+				<Link href="/docs/libraries/ui-kit" className="btn-ghost">
+					UI Kit
+				</Link>
+				<Link href="/docs/libraries/ui-kit-web" className="btn-ghost">
+					UI Kit Web
+				</Link>
+				<Link href="/docs/libraries/design-system" className="btn-primary">
+					Design System <ChevronRight size={16} />
+				</Link>
+			</div>
+		</div>
+	);
+}