@contractspec/bundle.library 0.0.0-canary-20260206014742

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

@@ -0,0 +1,72 @@
+// export const metadata: Metadata = {
+//   title: 'Studio – Getting Started',
+//   description:
+//     'Create your first ContractSpec Studio project, add specs, and deploy to shared infrastructure.',
+// };
+
+const steps = [
+  {
+    title: '1. Create a Studio workspace',
+    body: 'Sign in, pick “Studio managed” as product, and invite teammates. We provision the workspace plus default shared environments.',
+  },
+  {
+    title: '2. Add your first project',
+    body: 'Click “New project”, choose Starter tier, and keep BYOK disabled for the trial. You can upgrade later.',
+  },
+  {
+    title: '3. Author a spec',
+    body: 'Use the Visual Builder or Spec Editor. Pick “Capability” as type and describe the operation (e.g., capture donation).',
+  },
+  {
+    title: '4. Deploy to shared infra',
+    body: 'Open the deployment panel, select Development, and hit Deploy. Studio provisions the runtime slice automatically.',
+  },
+  {
+    title: '5. Wire integrations',
+    body: 'From Integration Hub, connect one provider (e.g., PostHog). Starter plan supports two providers.',
+  },
+];
+
+export function StudioGettingStartedPage() {
+  return (
+    <main className="space-y-12 py-12">
+      <header className="space-y-3">
+        <p className="text-xs font-semibold tracking-[0.3em] text-violet-400 uppercase">
+          Getting started
+        </p>
+        <h1 className="text-4xl font-bold">Launch your first Studio project</h1>
+        <p className="text-muted-foreground max-w-3xl text-lg">
+          This short guide takes you from workspace creation to the first
+          deployment. Every step is mobile-friendly and safe to undo.
+        </p>
+      </header>
+      <section className="grid gap-4">
+        {steps.map((step) => (
+          <article key={step.title} className="card-subtle space-y-2 p-6">
+            <h2 className="text-xl font-semibold">{step.title}</h2>
+            <p className="text-muted-foreground text-sm">{step.body}</p>
+          </article>
+        ))}
+      </section>
+      <section className="space-y-4">
+        <h2 className="text-2xl font-semibold">CLI helper (optional)</h2>
+        <p className="text-muted-foreground text-sm">
+          Prefer automation? Use the CLI to pull specs and push overlays.
+        </p>
+        <pre className="bg-muted/40 border-border overflow-auto rounded-xl border p-4 text-left font-mono text-sm">
+          {`# Authenticate
+cs login
+
+# List projects
+cs studio projects list
+
+# Pull specs locally
+cs studio specs pull <project-id>
+
+# Push after editing
+cs studio specs push <project-id>`}
+        </pre>
+      </section>
+    </main>
+  );
+}

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

@@ -0,0 +1,53 @@
+// export const metadata: Metadata = {
+//   title: 'Studio – Integration Hub Guide',
+//   description:
+//     'Connect providers, manage BYOK credentials, and sync data in the Studio Integration Hub.',
+// };
+
+const flow = [
+  {
+    title: 'Connect a provider',
+    body: 'Choose a provider from the marketplace, enter credentials, and run the test connection. Studio encrypts secrets immediately.',
+  },
+  {
+    title: 'Schedule syncs',
+    body: 'Define sync cadence (manual, hourly, daily). Studio tracks usage count and last sync timestamp.',
+  },
+  {
+    title: 'Index knowledge',
+    body: 'Add documentation or API specs as knowledge sources. Reindex whenever files change.',
+  },
+];
+
+export function StudioIntegrationsPage() {
+  return (
+    <main className="space-y-12 py-12">
+      <header className="space-y-3">
+        <p className="text-xs font-semibold tracking-[0.3em] text-violet-400 uppercase">
+          Integration hub
+        </p>
+        <h1 className="text-4xl font-bold">Unified connections with BYOK</h1>
+        <p className="text-muted-foreground max-w-3xl text-lg">
+          Manage SaaS providers and knowledge sources without scattering secrets
+          across tools. Studio gives you a simple card layout plus CLI
+          automation.
+        </p>
+      </header>
+      <section className="grid gap-4 md:grid-cols-3">
+        {flow.map((step) => (
+          <article key={step.title} className="card-subtle space-y-2 p-6">
+            <h2 className="text-xl font-semibold">{step.title}</h2>
+            <p className="text-muted-foreground text-sm">{step.body}</p>
+          </article>
+        ))}
+      </section>
+      <section className="space-y-2">
+        <h2 className="text-2xl font-semibold">Monitoring</h2>
+        <p className="text-muted-foreground text-sm">
+          Every integration exposes sync logs and failure alerts. Use the
+          webhook to forward sync events to Slack or PagerDuty.
+        </p>
+      </section>
+    </main>
+  );
+}

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

@@ -0,0 +1,69 @@
+import Link from '@contractspec/lib.ui-link';
+
+// export const metadata: Metadata = {
+//   title: 'Studio Documentation – ContractSpec',
+//   description:
+//     'Official ContractSpec Studio documentation. Jump into getting started, visual builder, deployments, BYOK, and integration guides.',
+// };
+
+const sections = [
+  {
+    title: '1. Getting started',
+    body: 'Provision your Studio workspace, create a project, and run the first deployment.',
+    href: '/docs/studio/getting-started',
+  },
+  {
+    title: '2. Visual builder',
+    body: 'Learn the canvas controls, component palette, and spec validation workflow.',
+    href: '/docs/studio/visual-builder',
+  },
+  {
+    title: '3. Deployments',
+    body: 'Switch between shared and dedicated environments, monitor health, and roll back safely.',
+    href: '/docs/studio/deployments',
+  },
+  {
+    title: '4. BYOK security',
+    body: 'Configure your vault, rotate keys, and audit credential access.',
+    href: '/docs/studio/byok',
+  },
+  {
+    title: '5. Integration hub',
+    body: 'Connect third-party providers, sync data, and index knowledge sources.',
+    href: '/docs/studio/integrations',
+  },
+];
+
+export function StudioOverviewPage() {
+  return (
+    <main className="space-y-16 py-16">
+      <section className="section-padding">
+        <p className="text-xs font-semibold tracking-[0.3em] text-violet-400 uppercase">
+          Studio docs
+        </p>
+        <h1 className="mt-4 text-4xl font-bold">
+          Everything you need to run Studio.
+        </h1>
+        <p className="text-muted-foreground mt-4 max-w-3xl text-lg">
+          ContractSpec Studio pairs a visual builder with managed
+          infrastructure. These guides keep teams aligned—especially when
+          engineers and operators share the same console.
+        </p>
+      </section>
+      <section className="section-padding grid gap-4">
+        {sections.map((section) => (
+          <Link
+            key={section.href}
+            href={section.href}
+            className="card-subtle group space-y-2 p-6 transition hover:border-violet-500/40"
+          >
+            <h2 className="text-xl font-semibold group-hover:text-violet-400">
+              {section.title}
+            </h2>
+            <p className="text-muted-foreground text-sm">{section.body}</p>
+          </Link>
+        ))}
+      </section>
+    </main>
+  );
+}

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

@@ -0,0 +1,78 @@
+import Image from 'next/image';
+
+// export const metadata: Metadata = {
+//   title: 'Studio – Visual Builder Guide',
+//   description:
+//     'Understand the Studio visual builder: canvas controls, component palette, bindings, and validation.',
+// };
+
+const tips = [
+  'Use two-finger drag on touch devices to pan the canvas.',
+  'Tap a component to open the spec sidebar and edit props.',
+  'The timeline records every change; tap a dot to roll back.',
+  'Validation runs automatically before deploy. Errors show inline.',
+];
+
+export function StudioVisualBuilderPage() {
+  return (
+    <main className="space-y-12 py-12">
+      <header className="space-y-3">
+        <p className="text-xs font-semibold tracking-[0.3em] text-violet-400 uppercase">
+          Visual builder
+        </p>
+        <h1 className="text-4xl font-bold">Canvas, palette, and spec editor</h1>
+        <p className="text-muted-foreground max-w-3xl text-lg">
+          Studio’s builder keeps designers, operators, and engineers in sync.
+          Every action updates the underlying spec and can be undone.
+        </p>
+      </header>
+      <section className="border-border bg-card rounded-2xl border p-6">
+        <Image
+          src="/assets/images/studio/visual-builder.png"
+          alt="Studio visual builder overview"
+          width={1024}
+          height={576}
+          className="border-border rounded-xl border"
+        />
+      </section>
+      <section className="grid gap-4 md:grid-cols-2">
+        <article className="card-subtle space-y-2 p-6">
+          <h2 className="text-2xl font-semibold">Canvas controls</h2>
+          <p className="text-muted-foreground text-sm">
+            Drag to pan, scroll/ pinch to zoom. The right panel shows a tree
+            view.
+          </p>
+        </article>
+        <article className="card-subtle space-y-2 p-6">
+          <h2 className="text-2xl font-semibold">Component palette</h2>
+          <p className="text-muted-foreground text-sm">
+            Search by intent (“capture payment”) or category. Drag components or
+            tap to add.
+          </p>
+        </article>
+        <article className="card-subtle space-y-2 p-6">
+          <h2 className="text-2xl font-semibold">Spec editor</h2>
+          <p className="text-muted-foreground text-sm">
+            Toggle between visual and code views. Changes stay in sync and
+            include diff previews.
+          </p>
+        </article>
+        <article className="card-subtle space-y-2 p-6">
+          <h2 className="text-2xl font-semibold">Deploy panel</h2>
+          <p className="text-muted-foreground text-sm">
+            Choose environment, review validations, and deploy with one button.
+            Rollback is one tap away.
+          </p>
+        </article>
+      </section>
+      <section className="space-y-3">
+        <h2 className="text-2xl font-semibold">Tips</h2>
+        <ul className="space-y-2 text-sm">
+          {tips.map((tip) => (
+            <li key={tip}>• {tip}</li>
+          ))}
+        </ul>
+      </section>
+    </main>
+  );
+}

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

@@ -0,0 +1,6 @@
+export { StudioOverviewPage } from './StudioOverviewPage';
+export { StudioGettingStartedPage } from './StudioGettingStartedPage';
+export { StudioVisualBuilderPage } from './StudioVisualBuilderPage';
+export { StudioIntegrationsPage } from './StudioIntegrationsPage';
+export { StudioDeploymentsPage } from './StudioDeploymentsPage';
+export { StudioBYOKPage } from './StudioBYOKPage';

package/src/components/docs/tech/contracts/tech-docs.docblocks.ts

@@ -0,0 +1,18 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+export const techContractsDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.tech.contracts.index',
+    title: 'Contracts tech docs',
+    summary: 'Entry for ContractSpec contracts technical documentation.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/tech/contracts',
+    tags: ['tech', 'contracts'],
+    body: `# Contracts Tech Docs
+
+Reference docs for ContractSpec contracts: app-config, capabilities, data-views, integrations, policy, presentations, overlays, and more.`,
+  },
+];
+registerDocBlocks(techContractsDocBlocks);

package/src/components/integrations/index.ts

@@ -0,0 +1,4 @@
+export * from './molecules/IntegrationCard';
+export * from './organisms/IntegrationMarketplace';
+export * from './organisms/IntegrationSettings';
+export * from './organisms/KnowledgeSourceList';

package/src/components/integrations/molecules/IntegrationCard.tsx

@@ -0,0 +1,81 @@
+import * as React from 'react';
+import { PlugZap, ToggleRight } from 'lucide-react';
+import { Button } from '@contractspec/lib.design-system';
+
+export interface IntegrationCardProps {
+  id: string;
+  provider: string;
+  name: string;
+  category?: string;
+  enabled?: boolean;
+  lastSyncAt?: string | null;
+  status?: 'connected' | 'disconnected' | 'error';
+  onToggle?: (id: string, enabled: boolean) => void;
+  onConfigure?: (id: string) => void;
+}
+
+export function IntegrationCard({
+  id,
+  provider,
+  name,
+  category,
+  enabled = true,
+  lastSyncAt,
+  status = 'connected',
+  onToggle,
+  onConfigure,
+}: IntegrationCardProps) {
+  const tone =
+    status === 'connected'
+      ? 'text-emerald-500 bg-emerald-500/10 border-emerald-500/30'
+      : status === 'error'
+        ? 'text-red-500 bg-red-500/10 border-red-500/30'
+        : 'text-gray-500 bg-gray-500/10 border-gray-500/30';
+
+  return (
+    <div className="border-border bg-card flex flex-col gap-4 rounded-2xl border p-4 shadow-sm">
+      <header className="flex items-center justify-between">
+        <div>
+          <p className="text-xl font-semibold">{name}</p>
+          <p className="text-muted-foreground text-sm">{provider}</p>
+        </div>
+        <Button
+          variant="outline"
+          size="sm"
+          className={`inline-flex items-center gap-2 rounded-full border px-3 py-1 text-xs font-semibold tracking-wide uppercase ${tone}`}
+          onPress={() => onToggle?.(id, !enabled)}
+        >
+          <ToggleRight className="h-3.5 w-3.5" />
+          {enabled ? 'Enabled' : 'Disabled'}
+        </Button>
+      </header>
+      <div className="text-muted-foreground text-sm">
+        {category && <span className="font-medium">{category}</span>}
+        <div className="mt-2 flex flex-wrap items-center gap-3 text-xs tracking-wide uppercase">
+          <span className="inline-flex items-center gap-1">
+            <PlugZap className="h-3 w-3" />
+            {status}
+          </span>
+          <span>
+            Last sync:{' '}
+            {lastSyncAt
+              ? new Date(lastSyncAt).toLocaleString()
+              : 'Not synced yet'}
+          </span>
+        </div>
+      </div>
+      <footer className="flex items-center gap-2">
+        <Button className="flex-1" onPress={() => onConfigure?.(id)}>
+          Configure
+        </Button>
+        <Button
+          variant="ghost"
+          className="flex-1"
+          onPress={() => onToggle?.(id, !enabled)}
+        >
+          {enabled ? 'Disconnect' : 'Connect'}
+        </Button>
+      </footer>
+    </div>
+  );
+}

package/src/components/integrations/organisms/IntegrationMarketplace.tsx

@@ -0,0 +1,133 @@
+import * as React from 'react';
+import { Boxes, Search } from 'lucide-react';
+import { IntegrationCard } from '../molecules/IntegrationCard';
+import { Input } from '@contractspec/lib.design-system';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@contractspec/lib.ui-kit-web/ui/select';
+
+export interface MarketplaceIntegration {
+  id: string;
+  provider: string;
+  name: string;
+  category: string;
+  enabled?: boolean;
+  status?: 'connected' | 'disconnected' | 'error';
+  lastSyncAt?: string | null;
+}
+
+export interface IntegrationMarketplaceProps {
+  integrations: MarketplaceIntegration[];
+  onToggle?: (id: string, enabled: boolean) => void;
+  onConfigure?: (id: string) => void;
+}
+
+export function IntegrationMarketplace({
+  integrations,
+  onToggle,
+  onConfigure,
+}: IntegrationMarketplaceProps) {
+  const [search, setSearch] = React.useState('');
+  const [category, setCategory] = React.useState('all');
+  // const integrationHubEnabled = Math.random() < 10 || useStudioFeatureFlag(
+  //   ContractSpecFeatureFlags.STUDIO_INTEGRATION_HUB
+  // );
+
+  const categories = React.useMemo(
+    () =>
+      Array.from(
+        new Set(integrations.map((integration) => integration.category))
+      ),
+    [integrations]
+  );
+
+  const filtered = integrations.filter((integration) => {
+    const matchesSearch =
+      integration.name.toLowerCase().includes(search.toLowerCase()) ||
+      integration.provider.toLowerCase().includes(search.toLowerCase());
+    const matchesCategory =
+      category === 'all' ? true : integration.category === category;
+    return matchesSearch && matchesCategory;
+  });
+
+  // if (!integrationHubEnabled) {
+  //   return (
+  //     <div className="border-border bg-card/40 rounded-2xl border border-dashed p-8 text-center">
+  //       <FeatureGateNotice
+  //         title="Integration hub is still locked"
+  //         description="Enable STUDIO_INTEGRATION_HUB to connect third-party providers and route credentials via BYOK."
+  //         actionLabel="Talk to sales"
+  //       />
+  //     </div>
+  //   );
+  // }
+
+  return (
+    <div className="border-border bg-card space-y-4 rounded-2xl border p-4">
+      <header className="flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <p className="text-sm font-semibold tracking-wide uppercase">
+            Integration marketplace
+          </p>
+          <p className="text-muted-foreground text-sm">
+            Connect AI providers, payments, analytics, and internal tools with
+            BYOK controls.
+          </p>
+        </div>
+        <Boxes className="text-muted-foreground h-5 w-5" />
+      </header>
+      <div className="flex flex-wrap gap-3">
+        <div className="relative min-w-[200px] flex-1">
+          <Search className="text-muted-foreground pointer-events-none absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2" />
+          <Input
+            type="search"
+            aria-label="Search providers"
+            className="w-full py-2 pr-3 pl-9 text-sm"
+            value={search}
+            onChange={(event) => setSearch(event.target.value)}
+            placeholder="Search providers"
+          />
+        </div>
+        <Select value={category} onValueChange={setCategory}>
+          <SelectTrigger className="w-[200px]">
+            <SelectValue placeholder="All categories" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="all">All categories</SelectItem>
+            {categories.map((item) => (
+              <SelectItem key={item} value={item}>
+                {item}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+      <div className="grid gap-4 md:grid-cols-2">
+        {filtered.length ? (
+          filtered.map((integration) => (
+            <IntegrationCard
+              key={integration.id}
+              id={integration.id}
+              provider={integration.provider}
+              name={integration.name}
+              category={integration.category}
+              enabled={integration.enabled}
+              status={integration.status}
+              lastSyncAt={integration.lastSyncAt}
+              onToggle={onToggle}
+              onConfigure={onConfigure}
+            />
+          ))
+        ) : (
+          <div className="text-muted-foreground border-border rounded-xl border border-dashed p-6 text-center text-sm md:col-span-2">
+            No integrations match your filters.
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}