@contractspec/bundle.library 0.0.0-canary-20260206014742

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

@@ -0,0 +1,90 @@
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function LibrariesOverlayEnginePage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Overlay Engine</h1>
+        <p className="text-muted-foreground text-lg">
+          `@contractspec/lib.overlay-engine` keeps OverlaySpecs typed, signed,
+          and auditable across tenants, roles, users, and devices.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand package="@contractspec/lib.overlay-engine" />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Define + Sign</h2>
+        <CodeBlock
+          language="typescript"
+          code={`import { defineOverlay } from '@contractspec/lib.overlay-engine/spec';
+import { signOverlay } from '@contractspec/lib.overlay-engine/signer';
+
+const overlay = defineOverlay({
+  overlayId: 'acme-order-form',
+  version: '1.0.0',
+  appliesTo: { capability: 'billing.createOrder', tenantId: 'acme' },
+  modifications: [{ type: 'hideField', field: 'internalNotes' }],
+});
+
+const signed = await signOverlay(overlay, privateKeyPem);`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Runtime</h2>
+        <p className="text-muted-foreground">
+          `OverlayRegistry` stores signed overlays with specificity scoring.
+          `OverlayEngine` merges modifications and emits audit events.
+        </p>
+        <CodeBlock
+          language="typescript"
+          code={`const registry = new OverlayRegistry();
+registry.register(signed);
+
+const engine = new OverlayEngine({
+  registry,
+  audit: (event) => auditLog.write(event),
+});
+
+const result = engine.apply({
+  target: { fields },
+  capability: 'billing.createOrder',
+  tenantId: 'acme',
+});`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">React Hooks</h2>
+        <p className="text-muted-foreground">
+          Render overlays in React/React Native via `useOverlay`.
+        </p>
+        <CodeBlock
+          language="typescript"
+          code={`import { useOverlay } from '@contractspec/lib.overlay-engine/react';
+
+const { target } = useOverlay(engine, {
+  target: { fields },
+  capability: 'billing.createOrder',
+  tenantId: 'acme',
+});`}
+        />
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries" className="btn-ghost">
+          Back to Libraries
+        </Link>
+        <Link href="/docs/libraries/workflow-composer" className="btn-primary">
+          Next: Workflow Composer <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,310 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Libraries: ContractSpec Docs',
+//   description:
+//     'Explore the LSSM library ecosystem for building type-safe, policy-enforced applications.',
+// };
+
+export function LibrariesOverviewPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Libraries Overview</h1>
+        <p className="text-muted-foreground">
+          The LSSM ecosystem provides a comprehensive set of TypeScript
+          libraries for building modern web and mobile applications. All
+          libraries are designed to work together seamlessly while remaining
+          modular and independently useful.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Core Libraries</h2>
+        <div className="grid gap-4 md:grid-cols-2">
+          <Link
+            href="/docs/libraries/contracts"
+            className="card-subtle group p-6 transition-colors hover:border-violet-500/50"
+          >
+            <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+              @contractspec/lib.contracts
+            </h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Define operations, events, and policies in pure TypeScript.
+              Runtime adapters serve them as REST/GraphQL/MCP endpoints.
+            </p>
+            <div className="mt-3 flex items-center gap-2 text-sm text-violet-400">
+              Learn more <ChevronRight size={14} />
+            </div>
+          </Link>
+
+          <Link
+            href="/docs/libraries/schema"
+            className="card-subtle group p-6 transition-colors hover:border-violet-500/50"
+          >
+            <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+              @contractspec/lib.schema
+            </h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Type-safe schema models that export to Zod, Pothos GraphQL, and
+              JSON Schema from a single source.
+            </p>
+            <div className="mt-3 flex items-center gap-2 text-sm text-violet-400">
+              Learn more <ChevronRight size={14} />
+            </div>
+          </Link>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="flex items-center gap-2 text-2xl font-bold">
+          AI-Native Operations
+          <span className="badge badge-secondary text-xs">Featured</span>
+        </h2>
+        <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
+          {[
+            {
+              title: '@contractspec/lib.ai-agent',
+              description:
+                'Agent specs, runner, memory, and approval workflow for safe AI copilots.',
+              href: '/docs/libraries/ai-agent',
+            },
+            {
+              title: '@contractspec/lib.support-bot',
+              description:
+                'Classification, RAG resolver, auto-responder, and performance loop for L1 automation.',
+              href: '/docs/libraries/support-bot',
+            },
+            {
+              title: '@contractspec/lib.content-gen',
+              description:
+                'Blog, landing, email, social, and SEO generators powered by ContentBriefs.',
+              href: '/docs/libraries/content-gen',
+            },
+            {
+              title: '@contractspec/lib.analytics',
+              description:
+                'Funnels, cohorts, churn scoring, and hypothesis generation without a warehouse.',
+              href: '/docs/libraries/analytics',
+            },
+            {
+              title: '@contractspec/lib.growth',
+              description:
+                'Experiment registry, runner, tracker, and stats engine for deterministic A/B tests.',
+              href: '/docs/libraries/growth',
+            },
+            {
+              title: '@contractspec/lib.design-system',
+              description:
+                'Now includes ApprovalQueue + AgentMonitor for human-in-the-loop decisions.',
+              href: '/docs/libraries/design-system',
+            },
+          ].map((lib) => (
+            <Link
+              key={lib.title}
+              href={lib.href}
+              className="card-subtle group p-6 transition-colors hover:border-violet-500/50"
+            >
+              <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+                {lib.title}
+              </h3>
+              <p className="text-muted-foreground mt-2 text-sm">
+                {lib.description}
+              </p>
+              <div className="mt-3 flex items-center gap-2 text-sm text-violet-400">
+                Learn more <ChevronRight size={14} />
+              </div>
+            </Link>
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="flex items-center gap-2 text-2xl font-bold">
+          Personalization & Customization
+          <span className="badge badge-primary text-xs">Featured</span>
+        </h2>
+        <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
+          {[
+            {
+              title: '@contractspec/lib.personalization',
+              description:
+                'Track behavior, analyze unused UI, and feed overlay/workflow adapters.',
+              href: '/docs/libraries/personalization',
+            },
+            {
+              title: '@contractspec/lib.overlay-engine',
+              description:
+                'Signed overlays with validator, registry, runtime engine, and React hooks.',
+              href: '/docs/libraries/overlay-engine',
+            },
+            {
+              title: '@contractspec/lib.workflow-composer',
+              description:
+                'Tenant-aware workflow extensions with step injection helpers.',
+              href: '/docs/libraries/workflow-composer',
+            },
+          ].map((lib) => (
+            <Link
+              key={lib.title}
+              href={lib.href}
+              className="card-subtle group p-6 transition-colors hover:border-violet-500/50"
+            >
+              <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+                {lib.title}
+              </h3>
+              <p className="text-muted-foreground mt-2 text-sm">
+                {lib.description}
+              </p>
+              <div className="mt-3 flex items-center gap-2 text-sm text-violet-400">
+                Learn more <ChevronRight size={14} />
+              </div>
+            </Link>
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">UI Libraries</h2>
+        <div className="grid gap-4 md:grid-cols-2">
+          <Link
+            href="/docs/libraries/ui-kit"
+            className="card-subtle group p-6 transition-colors hover:border-violet-500/50"
+          >
+            <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+              @contractspec/lib.ui-kit
+            </h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Universal UI components for React Native and Web, built on
+              NativeWind and @rn-primitives.
+            </p>
+            <div className="mt-3 flex items-center gap-2 text-sm text-violet-400">
+              Learn more <ChevronRight size={14} />
+            </div>
+          </Link>
+
+          <Link
+            href="/docs/libraries/design-system"
+            className="card-subtle group p-6 transition-colors hover:border-violet-500/50"
+          >
+            <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+              @contractspec/lib.design-system
+            </h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              High-level design system components, patterns, and layouts. Built
+              on top of ui-kit.
+            </p>
+            <div className="mt-3 flex items-center gap-2 text-sm text-violet-400">
+              Learn more <ChevronRight size={14} />
+            </div>
+          </Link>
+
+          <Link
+            href="/docs/libraries/accessibility"
+            className="card-subtle group p-6 transition-colors hover:border-violet-500/50"
+          >
+            <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+              @contractspec/lib.accessibility
+            </h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Accessibility primitives for WCAG compliance: skip links, live
+              regions, focus management, and more.
+            </p>
+            <div className="mt-3 flex items-center gap-2 text-sm text-violet-400">
+              Learn more <ChevronRight size={14} />
+            </div>
+          </Link>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Data & Backend</h2>
+        <div className="grid gap-4 md:grid-cols-3">
+          <div className="card-subtle p-4">
+            <h3 className="font-semibold">@contractspec/app.cli-database</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Prisma wrapper and CLI for schema management
+            </p>
+          </div>
+          <div className="card-subtle p-4">
+            <h3 className="font-semibold">@contractspec/lib.bus</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Type-safe event bus for in-memory and distributed events
+            </p>
+          </div>
+          <div className="card-subtle p-4">
+            <h3 className="font-semibold">@contractspec/lib.logger</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Structured logging optimized for Bun with Elysia integration
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">GraphQL</h2>
+        <div className="grid gap-4 md:grid-cols-3">
+          <div className="card-subtle p-4">
+            <h3 className="font-semibold">@contractspec/lib.graphql-core</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Shared Pothos builder with plugins
+            </p>
+          </div>
+          <div className="card-subtle p-4">
+            <h3 className="font-semibold">@contractspec/lib.graphql-prisma</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Prisma integration for Pothos schemas
+            </p>
+          </div>
+          <div className="card-subtle p-4">
+            <h3 className="font-semibold">
+              @contractspec/lib.graphql-federation
+            </h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Apollo Federation support for Pothos
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Philosophy</h2>
+        <p className="text-muted-foreground">
+          All LSSM libraries follow these principles:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>Type Safety First</strong>: Full TypeScript support with
+            strict types.
+          </li>
+          <li>
+            <strong>Modular</strong>: Use only what you need, tree-shake the
+            rest.
+          </li>
+          <li>
+            <strong>Platform Aware</strong>: Optimized for both Web and Native
+            where applicable.
+          </li>
+          <li>
+            <strong>Single Source of Truth</strong>: Avoid duplication between
+            layers (REST, GraphQL, Zod).
+          </li>
+          <li>
+            <strong>Developer Experience</strong>: Clear APIs, comprehensive
+            docs, and helpful error messages.
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries/contracts" className="btn-primary">
+          Explore Contracts <ChevronRight size={16} />
+        </Link>
+        <Link href="/docs/getting-started" className="btn-ghost">
+          Getting Started
+        </Link>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,86 @@
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function LibrariesPersonalizationPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">
+          @contractspec/lib.personalization
+        </h1>
+        <p className="text-muted-foreground text-lg">
+          Track field/feature/workflow usage, analyze drop-offs, and convert
+          insights into OverlaySpecs or workflow tweaks.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand package="@contractspec/lib.personalization" />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Tracker</h2>
+        <p className="text-muted-foreground">
+          Buffer events per tenant/user and emit OpenTelemetry counters
+          automatically.
+        </p>
+        <CodeBlock
+          language="typescript"
+          code={`import { createBehaviorTracker } from '@contractspec/lib.personalization';
+
+const tracker = createBehaviorTracker({
+  store,
+  context: { tenantId: ctx.tenant.id, userId: ctx.identity.id },
+});
+
+tracker.trackFieldAccess({ operation: 'billing.createOrder', field: 'items' });
+tracker.trackWorkflowStep({ workflow: 'invoice', step: 'review', status: 'entered' });`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Analyzer</h2>
+        <p className="text-muted-foreground">
+          Summarize events and highlight unused UI, frequent fields, and
+          workflow bottlenecks.
+        </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: [...] }`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Adapter</h2>
+        <p className="text-muted-foreground">
+          Convert insights into overlays or workflow extension hints.
+        </p>
+        <CodeBlock
+          language="typescript"
+          code={`import { insightsToOverlaySuggestion } from '@contractspec/lib.personalization/adapter';
+
+const overlay = insightsToOverlaySuggestion(insights, {
+  overlayId: 'acme-order-form',
+  tenantId: 'acme',
+  capability: 'billing.createOrder',
+});`}
+        />
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries" className="btn-ghost">
+          Back to Libraries
+        </Link>
+        <Link href="/docs/libraries/overlay-engine" className="btn-primary">
+          Next: Overlay Engine <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,83 @@
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function LibrariesProgressiveDeliveryPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Progressive Delivery Library</h1>
+        <p className="text-muted-foreground text-lg">
+          The <code>@contractspec/lib.progressive-delivery</code> package helps
+          you ship new specs with confidence: canary + blue-green strategies,
+          metric guardrails, and rollback hooks in one place.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand package="@contractspec/lib.progressive-delivery" />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Define a Strategy</h2>
+        <CodeBlock
+          language="typescript"
+          code={`import { DeploymentCoordinator, createDefaultCanaryController, TrafficShifter, RollbackManager } from '@contractspec/lib.progressive-delivery';
+
+const strategy = {
+  target: { name: 'billing.createInvoice', version: 7 },
+  mode: 'canary',
+  thresholds: {
+    errorRate: 0.01,
+    latencyP99: 500,
+    latencyP95: 250,
+  },
+};`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Run the Coordinator</h2>
+        <CodeBlock
+          language="typescript"
+          code={`const eventBus = new DeploymentEventBus();
+const controller = createDefaultCanaryController(strategy, fetchMetrics, eventBus);
+const coordinator = new DeploymentCoordinator({
+  strategy,
+  controller,
+  trafficShifter: new TrafficShifter(strategy.mode),
+  rollbackManager: new RollbackManager({ rollback: revertSpec }),
+  applyTrafficSplit: updateFeatureFlag,
+  eventBus,
+});
+
+const result = await coordinator.run();`}
+        />
+        <p className="text-muted-foreground text-sm">
+          The coordinator emits <code>stage_started</code>,{' '}
+          <code>stage_failed</code>, and <code>rolled_back</code> events, making
+          it easy to power dashboards or alerting workflows.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Blue-Green Swap</h2>
+        <p className="text-muted-foreground text-sm">
+          Switch to <code>mode: 'blue-green'</code> to warm up the new stack in
+          parallel and cut over once smoke tests pass. The same guardrails apply
+          before the final swap.
+        </p>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries" className="btn-ghost">
+          Back to Libraries
+        </Link>
+        <Link href="/docs/libraries/resilience" className="btn-primary">
+          Next: Resilience <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,86 @@
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function LibrariesResiliencePage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Resilience Library</h1>
+        <p className="text-muted-foreground text-lg">
+          The <code>@contractspec/lib.resilience</code> library provides
+          primitives to handle failures gracefully.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand package="@contractspec/lib.resilience" />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Circuit Breaker</h2>
+        <p className="text-muted-foreground">
+          Prevent cascading failures by stopping calls to a failing dependency.
+        </p>
+        <CodeBlock
+          language="typescript"
+          code={`import { CircuitBreaker } from '@contractspec/lib.resilience/circuit-breaker';
+
+const breaker = new CircuitBreaker({
+  failureThreshold: 5,
+  resetTimeoutMs: 30000,
+});
+
+const result = await breaker.execute(async () => {
+  return await fetch('https://api.stripe.com/v1/charges');
+});`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Retry</h2>
+        <p className="text-muted-foreground">
+          Automatically retry transient failures with exponential backoff.
+        </p>
+        <CodeBlock
+          language="typescript"
+          code={`import { retry } from '@contractspec/lib.resilience/retry';
+
+const result = await retry(
+  async () => fetchUser(id),
+  3, // retries
+  1000, // initial delay
+  true // backoff
+);`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Timeout & Fallback</h2>
+        <p className="text-muted-foreground">
+          Set hard limits on execution time and provide default values on
+          failure.
+        </p>
+        <CodeBlock
+          language="typescript"
+          code={`import { timeout, fallback } from '@contractspec/lib.resilience';
+
+const result = await fallback(
+  () => timeout(slowOperation, 5000),
+  defaultValue
+);`}
+        />
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries" className="btn-ghost">
+          Back to Libraries
+        </Link>
+        <Link href="/docs/libraries/testing" className="btn-primary">
+          Next: Testing <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}