@contractspec/bundle.library 3.8.9 → 3.8.11

package/src/components/docs/specs/SpecsModuleBundlesPage.tsx

@@ -0,0 +1,223 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+
+const bundleCapabilities = [
+	'declared routes, surfaces, layouts, slots, actions, and data recipes',
+	'entity registries and field renderers for relation-heavy workbenches',
+	'preference-aware adaptation across guidance, density, data depth, control, media, pace, and narrative',
+	'auditable overlays and bounded AI patch proposals instead of free-form JSX generation',
+];
+
+const adoptionLoop = [
+	'Define one `ModuleBundleSpec` with `defineModuleBundle` and keep the route and surface map explicit.',
+	'Resolve the bundle with `resolveBundle` for a real user, route, device, and preference profile.',
+	'Render the plan through `BundleProvider` and `BundleRenderer` so the UI stays downstream of the resolved spec.',
+	'Add overlays, policy hooks, planner proposals, and telemetry only after the base route resolves cleanly.',
+	'Pilot one dense domain first, such as a PM or operations workbench, before expanding the abstraction across the app.',
+];
+
+export function SpecsModuleBundlesPage() {
+	return (
+		<div className="space-y-10">
+			<section className="space-y-3">
+				<p className="editorial-kicker">Spec pack</p>
+				<h1 className="font-serif text-4xl tracking-[-0.04em] md:text-5xl">
+					Module bundles turn surface composition into a typed ContractSpec
+					runtime instead of a pile of bespoke page code.
+				</h1>
+				<p className="max-w-3xl text-lg text-muted-foreground leading-8">
+					The implemented package is{' '}
+					<code>@contractspec/lib.surface-runtime</code>. It lets you define a
+					bundle spec once, resolve it into a personalized surface plan, then
+					render that plan through React without letting AI or per-route custom
+					code bypass the declared system boundary.
+				</p>
+			</section>
+
+			<section className="editorial-proof-strip">
+				<div className="editorial-stat">
+					<span className="editorial-label">Runtime promise</span>
+					<span className="editorial-stat-value">
+						bundle spec → resolved surface plan
+					</span>
+				</div>
+				<p className="max-w-2xl text-muted-foreground text-sm leading-7">
+					The bundle spec owns what can render, where it can render, which
+					preferences matter, and how overlays and AI proposals stay bounded.
+				</p>
+			</section>
+
+			<section className="grid gap-4 md:grid-cols-2">
+				{bundleCapabilities.map((item) => (
+					<article key={item} className="editorial-panel space-y-3">
+						<h2 className="font-semibold text-xl">Bundle capability</h2>
+						<p className="text-muted-foreground text-sm leading-7">{item}</p>
+					</article>
+				))}
+			</section>
+
+			<section className="editorial-panel space-y-5">
+				<div className="space-y-2">
+					<h2 className="font-serif text-3xl tracking-[-0.03em]">
+						1) Define the bundle
+					</h2>
+					<p className="text-muted-foreground text-sm leading-7">
+						Start with a typed route and one surface. The runtime validates that
+						you declared routes, surfaces, and verification coverage for all
+						seven preference dimensions.
+					</p>
+				</div>
+				<CodeBlock
+					language="typescript"
+					filename="support.workbench.bundle.ts"
+					code={`import { defineModuleBundle } from "@contractspec/lib.surface-runtime/spec/define-module-bundle";
+
+export const SupportWorkbenchBundle = defineModuleBundle({
+  meta: {
+    key: "support.workbench",
+    version: "0.1.0",
+    title: "Support Workbench",
+  },
+  routes: [
+    {
+      routeId: "support-ticket",
+      path: "/operate/support/tickets/:ticketId",
+      defaultSurface: "ticket-workbench",
+    },
+  ],
+  surfaces: {
+    "ticket-workbench": {
+      surfaceId: "ticket-workbench",
+      kind: "workbench",
+      slots: [{ slotId: "primary", role: "primary", accepts: ["entity-section"], cardinality: "many" }],
+      layouts: [{ layoutId: "balanced", title: "Balanced", root: { type: "slot", slotId: "primary" } }],
+      data: [{ recipeId: "ticket-core", source: { kind: "entity", entityType: "support.ticket" }, hydrateInto: "ticket" }],
+      verification: {
+        dimensions: {
+          guidance: "Surface can reveal walkthrough or inline help states.",
+          density: "Layout supports compact and balanced detail modes.",
+          dataDepth: "Resolver can hydrate summary or detailed ticket context.",
+          control: "Advanced actions stay policy-gated.",
+          media: "Surface supports text-first and hybrid assist modes.",
+          pace: "Transitions and confirmations adapt to operator pace.",
+          narrative: "Summary and evidence ordering stay explicit.",
+        },
+      },
+    },
+  },
+});`}
+				/>
+			</section>
+
+			<section className="editorial-panel space-y-5">
+				<div className="space-y-2">
+					<h2 className="font-serif text-3xl tracking-[-0.03em]">
+						2) Resolve and render the plan
+					</h2>
+					<p className="text-muted-foreground text-sm leading-7">
+						The app renders the resolved plan, not the raw spec. That keeps
+						layout choice, data hydration, overlays, and AI proposals auditable.
+					</p>
+				</div>
+				<CodeBlock
+					language="tsx"
+					filename="SurfaceHost.tsx"
+					code={`import { BundleProvider, BundleRenderer } from "@contractspec/lib.surface-runtime/react";
+import { resolveBundle } from "@contractspec/lib.surface-runtime/runtime/resolve-bundle";
+
+const plan = await resolveBundle(SupportWorkbenchBundle, {
+  tenantId: "tenant_demo",
+  workspaceId: "workspace_ops",
+  actorId: "user_42",
+  route: "/operate/support/tickets/123",
+  params: { ticketId: "123" },
+  query: {},
+  device: "desktop",
+  locale: "en",
+  preferences: {
+    guidance: "hints",
+    density: "compact",
+    dataDepth: "detailed",
+    control: "advanced",
+    media: "hybrid",
+    pace: "balanced",
+    narrative: "top-down",
+  },
+  capabilities: ["tickets.read", "tickets.update"],
+});
+
+export function SurfaceHost() {
+  return (
+    <BundleProvider plan={plan}>
+      <BundleRenderer assistantSlotId="assistant" />
+    </BundleProvider>
+  );
+}`}
+				/>
+			</section>
+
+			<section className="grid gap-5 lg:grid-cols-2">
+				<article className="editorial-panel space-y-4">
+					<h2 className="font-serif text-3xl tracking-[-0.03em]">
+						Adoption loop
+					</h2>
+					<ol className="list-inside list-decimal space-y-3 text-muted-foreground text-sm leading-7">
+						{adoptionLoop.map((step) => (
+							<li key={step}>{step}</li>
+						))}
+					</ol>
+				</article>
+
+				<article className="editorial-panel space-y-4">
+					<h2 className="font-serif text-3xl tracking-[-0.03em]">
+						Guardrails that matter
+					</h2>
+					<ul className="editorial-list">
+						<li>
+							<span className="editorial-list-marker" />
+							<span>Do not stuff this behavior back into `lib.ui-kit`.</span>
+						</li>
+						<li>
+							<span className="editorial-list-marker" />
+							<span>
+								Do not let AI invent undeclared components or mutate raw DOM
+								state.
+							</span>
+						</li>
+						<li>
+							<span className="editorial-list-marker" />
+							<span>
+								Keep third-party UI libraries behind adapter subpaths only.
+							</span>
+						</li>
+						<li>
+							<span className="editorial-list-marker" />
+							<span>
+								Every surface still needs explicit verification coverage for the
+								seven preference dimensions.
+							</span>
+						</li>
+					</ul>
+				</article>
+			</section>
+
+			<section className="editorial-panel space-y-4">
+				<h2 className="font-serif text-3xl tracking-[-0.03em]">
+					Continue with overlays and runtime architecture
+				</h2>
+				<p className="text-muted-foreground text-sm leading-7">
+					Once the bundle resolves deterministically, move into safe
+					customization and the wider architecture that surrounds it.
+				</p>
+				<div className="flex flex-wrap gap-3">
+					<Link href="/docs/specs/overlays" className="btn-primary">
+						Overlays
+					</Link>
+					<Link href="/docs/architecture" className="btn-ghost">
+						Architecture overview
+					</Link>
+				</div>
+			</section>
+		</div>
+	);
+}

package/src/components/docs/specs/SpecsOverlaysPage.tsx

@@ -245,6 +245,26 @@ signature:
 				</ul>
 			</div>
 
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">
+					Where overlays fit in the runtime
+				</h2>
+				<p className="text-muted-foreground">
+					Overlays are safest when they sit on top of a declared bundle surface
+					instead of ad hoc page code. Use the module-bundles docs first, then
+					apply overlays as auditable customization on top of the resolved
+					surface plan.
+				</p>
+				<div className="flex flex-wrap gap-3">
+					<Link href="/docs/specs/module-bundles" className="btn-primary">
+						Module bundles
+					</Link>
+					<Link href="/docs/guides/first-module-bundle" className="btn-ghost">
+						Build a first module bundle
+					</Link>
+				</div>
+			</div>
+
 			<div className="flex items-center gap-4 pt-4">
 				<Link href="/docs/specs/policy" className="btn-ghost">
 					Previous: Policy

package/src/components/docs/specs/SpecsOverviewPage.tsx

@@ -34,6 +34,24 @@ const specTypes = [
 	},
 ];
 
+const implementedPacks = [
+	{
+		title: 'Module bundles',
+		body: 'Define typed surface bundles that resolve into auditable runtime plans instead of hand-built page logic.',
+		href: '/docs/specs/module-bundles',
+	},
+	{
+		title: 'ContractSpec Connect',
+		body: 'Put coding-agent edits and commands behind local-first context, verification, replay, and review artifacts.',
+		href: '/docs/specs/connect',
+	},
+	{
+		title: 'Builder control plane',
+		body: 'Coordinate multimodal authoring, provider routing, readiness, export, and mobile review on top of OSS and Studio.',
+		href: '/docs/specs/builder-control-plane',
+	},
+];
+
 export function SpecsOverviewPage() {
 	return (
 		<div className="space-y-10">
@@ -122,6 +140,32 @@ export function SpecsOverviewPage() {
 					))}
 				</div>
 			</section>
+
+			<section className="space-y-5">
+				<div className="space-y-2">
+					<h2 className="font-serif text-3xl tracking-[-0.03em]">
+						Implemented spec packs
+					</h2>
+					<p className="text-muted-foreground text-sm leading-7">
+						These packs combine multiple contract surfaces into higher-order
+						systems you can use directly today: agent enforcement, AI-native
+						surface runtime, and governed Builder authoring.
+					</p>
+				</div>
+				<div className="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+					{implementedPacks.map((item) => (
+						<Link key={item.title} href={item.href} className="editorial-panel">
+							<h3 className="font-semibold text-xl">{item.title}</h3>
+							<p className="mt-2 text-muted-foreground text-sm leading-7">
+								{item.body}
+							</p>
+							<div className="mt-4 flex items-center gap-2 text-[color:var(--rust)] text-sm">
+								Open pack <ChevronRight size={14} />
+							</div>
+						</Link>
+					))}
+				</div>
+			</section>
 		</div>
 	);
 }

package/src/components/docs/specs/SpecsWorkflowsPage.tsx

@@ -95,8 +95,16 @@ export function SpecsWorkflowsPage() {
 				<p className="text-muted-foreground">
 					Here's a simplified example of a payment workflow in TypeScript:
 				</p>
+				<p className="text-muted-foreground text-sm">
+					For Vercel Workflow and other VM-evaluated runtimes, author workflow
+					specs from{' '}
+					<code className="rounded bg-background/50 px-2 py-1">
+						@contractspec/lib.contracts-spec/workflow/spec
+					</code>{' '}
+					rather than the broad workflow barrel.
+				</p>
 				<div className="overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm">
-					<pre>{`import { defineWorkflow } from '@contractspec/lib.contracts-spec/workflow';
+					<pre>{`import { defineWorkflow } from '@contractspec/lib.contracts-spec/workflow/spec';
 import { ValidatePaymentMethod, ChargePayment, SendEmail } from './specs';
 
 export const PaymentFlow = defineWorkflow({

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

@@ -1,5 +1,8 @@
+export { SpecsBuilderControlPlanePage } from './SpecsBuilderControlPlanePage';
 export { SpecsCapabilitiesPage } from './SpecsCapabilitiesPage';
+export { SpecsConnectPage } from './SpecsConnectPage';
 export { SpecsDataViewsPage } from './SpecsDataViewsPage';
+export { SpecsModuleBundlesPage } from './SpecsModuleBundlesPage';
 export { SpecsOverlaysPage } from './SpecsOverlaysPage';
 export { SpecsOverviewPage } from './SpecsOverviewPage';
 export { SpecsPolicyPage } from './SpecsPolicyPage';

package/src/components/docs/studio/StudioOverviewPage.tsx

@@ -77,6 +77,32 @@ export function StudioOverviewPage() {
 				</article>
 			</section>
 
+			<section className="editorial-panel space-y-4">
+				<h2 className="font-serif text-3xl tracking-[-0.03em]">
+					Builder is the governed authoring layer
+				</h2>
+				<p className="text-muted-foreground text-sm leading-7">
+					If your team wants a concrete authoring control plane on top of the
+					OSS foundation, start with the Builder control-plane docs and the
+					workbench host guide before you dive into the larger Studio product
+					surface.
+				</p>
+				<div className="flex flex-wrap gap-3">
+					<Link
+						href="/docs/specs/builder-control-plane"
+						className="btn-primary"
+					>
+						Builder control plane
+					</Link>
+					<Link
+						href="/docs/guides/host-builder-workbench"
+						className="btn-ghost"
+					>
+						Host the Builder workbench
+					</Link>
+				</div>
+			</section>
+
 			<section className="editorial-panel space-y-4">
 				<h2 className="font-serif text-3xl tracking-[-0.03em]">
 					Go to the Studio product docs for the full product surface

package/src/infrastructure/elysia/logger.ts

@@ -1,11 +1,19 @@
 import { Logger, LogLevel } from '@contractspec/lib.logger';
 
+function resolveNodeEnvironment() {
+	return process.env.NODE_ENV === 'production' ||
+		process.env.NODE_ENV === 'test' ||
+		process.env.NODE_ENV === 'development'
+		? process.env.NODE_ENV
+		: 'development';
+}
+
 // Centralized logger configuration for the API
 export const createAppLogger = () =>
 	new Logger({
 		level:
 			process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
-		environment: process.env.NODE_ENV || 'development',
+		environment: resolveNodeEnvironment(),
 		enableTracing: true,
 		enableTiming: true,
 		enableContext: true,
@@ -18,7 +26,7 @@ export const appLogger = createAppLogger();
 // Logger specifically for database operations
 export const dbLogger = new Logger({
 	level: process.env.NODE_ENV === 'production' ? LogLevel.WARN : LogLevel.DEBUG,
-	environment: process.env.NODE_ENV || 'development',
+	environment: resolveNodeEnvironment(),
 	enableTracing: true,
 	enableTiming: true,
 	enableContext: true,
@@ -28,7 +36,7 @@ export const dbLogger = new Logger({
 // Logger for authentication operations
 export const authLogger = new Logger({
 	level: LogLevel.INFO, // Always log auth events
-	environment: process.env.NODE_ENV || 'development',
+	environment: resolveNodeEnvironment(),
 	enableTracing: true,
 	enableTiming: true,
 	enableContext: true,