@contractspec/lib.surface-runtime 0.2.0

package/README.md

@@ -0,0 +1,164 @@
+# @contractspec/lib.surface-runtime
+
+AI-native surface specs and web runtime for adaptive ContractSpec surfaces.
+
+## Overview
+
+This library provides:
+
+- **ModuleBundleSpec** — TypeScript types for defining surface contracts (routes, slots, layouts, data recipes)
+- **defineModuleBundle** — Runtime validator for bundle specs
+- **resolveBundle** — Resolves a bundle spec + context into a ResolvedSurfacePlan
+- **resolvePreferenceProfile** — Resolves preferences by scope order (user → … → session)
+- **defaultPreferenceAdapter** — Stub `BundlePreferenceAdapter` (resolve + savePreferencePatch)
+- **applySurfacePatch** — Applies patch operations to a plan
+- **BundleProvider** / **BundleRenderer** — React components for rendering resolved plans
+- **RegionRenderer** / **SlotRenderer** — Layout tree and slot content rendering
+- **Adapters** — BlockNote, dnd-kit, Floating UI, Motion, resizable-panels, AI SDK (stubs)
+
+## Terminology (Glossary)
+
+- **Bundle spec** / **Surface spec** (ModuleBundleSpec): A contract type defining a surface (routes, slots, layouts). Not an architectural layer. Use "surface spec" in prose to avoid confusion.
+- **Bundle** (architectural): A domain package in `packages/bundles/` (e.g. bundle.workspace). Contains business logic.
+
+### Preference vs layout vs view vs overlay
+
+| Concept | Meaning | Storage |
+|---------|---------|---------|
+| **Preference** | Stable user intent (e.g. `density=dense`, `guidance=hints`). Orthogonal 7-dimension model. | User/workspace/surface scope via `BundlePreferenceAdapter`. |
+| **Layout snapshot** | Concrete arrangement (panel sizes, tab order, collapsed state). | Distinct from preferences; use `persistKey` + overlay-engine for durable layout. |
+| **View** | Data-shaping projection (filters, sort, visible columns). | Often session-scoped or view-state. |
+| **Overlay** | Durable mutation to the rendered contract (patches, field visibility). | `lib.overlay-engine` (OverlaySpec, merger). |
+
+Do not merge these into one blob. Preferences drive adaptation; layout snapshots persist geometry; overlays persist structural patches.
+
+### Preference scope resolution order
+
+Preferences are merged in this order (later overrides earlier):
+
+1. **user** — Global user defaults  
+2. **workspace-user** — Workspace-specific user defaults  
+3. **bundle** — Bundle-level defaults  
+4. **surface** — Surface-specific overrides  
+5. **entity** — Entity-context overrides  
+6. **session** — Session overrides (highest priority)
+
+### Dimension → runtime behavior (summary)
+
+| Dimension | Runtime effect |
+|-----------|----------------|
+| **guidance** | Hints, onboarding, progressive disclosure, assistant prompting style |
+| **density** | Spacing, panel expansion, table vs card layout, side rails |
+| **dataDepth** | Query shape, pagination size, inline expansion, raw payload access |
+| **control** | Visible toggles, advanced inspectors, batch ops, policy editor |
+| **media** | Text vs visual vs voice surfaces, charts vs prose, TTS |
+| **pace** | Animation duration, confirmation depth, skeleton persistence; respects `prefers-reduced-motion` |
+| **narrative** | Order of summary vs evidence, top-down vs bottom-up presentation |
+
+Every surface must declare `verification.dimensions` describing how it responds to each dimension. See [docs/verification-matrix.md](./docs/verification-matrix.md) for the verification matrix, review questions, and snapshot coverage.
+
+## Package Strategy
+
+### Hard dependencies
+
+- `@contractspec/lib.contracts-spec` — operations, capabilities, policies, presentations
+- `@contractspec/lib.overlay-engine` — typed, auditable overrides
+- `@contractspec/lib.observability` — tracing, metrics, lifecycle instrumentation
+- `zod` — schema validation
+
+### Interoperability (consumes or composes with)
+
+- `@contractspec/lib.contracts-runtime-client-react` — feature/form rendering
+- `@contractspec/lib.presentation-runtime-react` — workflow, list state
+- `@contractspec/lib.ai-agent` — agent orchestration (when assistant integration is added)
+- `@contractspec/lib.ai-providers` — planner model selection
+- `@contractspec/lib.metering` — when AI/chat features are used
+- `@contractspec/lib.personalization` — preference dimensions (or surface-runtime-owned until adopted)
+
+### Peer dependencies
+
+- `react`, `react-dom` — optional; required only for React renderer
+- UI libs (BlockNote, dnd-kit, Floating UI, Motion, resizable-panels) — optional; added as peers when adapters are implemented
+
+## Usage
+
+```ts
+import { defineModuleBundle } from "@contractspec/lib.surface-runtime/spec";
+import { resolveBundle } from "@contractspec/lib.surface-runtime/runtime";
+
+const PmWorkbenchBundle = defineModuleBundle({
+  meta: { key: "pm.workbench", version: "0.1.0", title: "PM Workbench" },
+  routes: [{ routeId: "pm-issue", path: "/operate/pm/issues/:issueId", defaultSurface: "issue-workbench" }],
+  surfaces: {
+    "issue-workbench": {
+      surfaceId: "issue-workbench",
+      kind: "workbench",
+      title: "Issue Workbench",
+      slots: [...],
+      layouts: [...],
+      data: [],
+      verification: { dimensions: { guidance: "...", density: "...", ... } },
+    },
+  },
+});
+
+const plan = await resolveBundle(PmWorkbenchBundle, ctx);
+```
+
+## Dependencies
+
+See [Package Strategy](#package-strategy) above. Core: contracts-spec, overlay-engine, observability, zod.
+
+## AI Chat Integration (07_ai_native_chat_and_generative_ui)
+
+The assistant slot can render chat UI from `@contractspec/module.ai-chat`. Wire as follows:
+
+1. **Assistant slot**: Declare a slot with `role: 'assistant'` in the surface spec. Set `SurfaceAiSpec.assistantSlotId` to that slot's `slotId`.
+
+2. **BundleRenderer + assistant slot**: When `SlotRenderer` receives `slotId === assistantSlotId`, the bundle should render `ChatContainer` from `@contractspec/module.ai-chat` instead of default slot content. Pass `useChat` from the same module for thread state.
+
+3. **Provider config**: Use `createProvider` from `@contractspec/lib.ai-providers` to build the model config. Pass it to the planner (ContractSpecAgent) and to the chat UI (useChat options).
+
+4. **Planner integration**: Use `compilePlannerPrompt` and `proposePatchToolConfig` from this package. Wire the propose-patch tool handler to `validatePatchProposal` before returning. Map planner output to `PlannerResponse` (summary, intent, patchProposals, blockDrafts).
+
+5. **Patch approval flow**: On accept, emit `patch.approved` audit event, call `applySurfacePatch`, then promote to session overlay. On reject, emit `patch.rejected`. Use `PatchApprovalHandler` for the callback signature.
+
+## Policy, Audit, and Rollback (10_policy_audit_and_safety)
+
+### Policy hooks
+
+Pass `policy` and `audit` to `resolveBundle` options:
+
+- **evaluateNode**: Return `UiPolicyDecision` (allow/deny/redact) per node. Stub: allow all.
+- **redactBinding**: Redact binding values. Stub: pass-through.
+- **evaluatePatchProposal**: Return allow/deny/require-approval for patch ops. Stub: allow.
+
+Use `evaluateAndEmitPatchPolicy` before applying patches to gate on policy and emit `policy.denied` when blocked.
+
+### Audit events
+
+Implement `BundleAuditEmitter` and pass to `resolveBundle` and patch approval flow. Events: `surface.resolved`, `patch.proposed`, `patch.approved`, `patch.rejected`, `overlay.saved`, `overlay.applied`, `overlay.failed`, `policy.denied`, `policy.redacted`. Use `emitPatchProposed`, `emitPatchApproved`, etc. from `./runtime`.
+
+### Rollback
+
+`applySurfacePatch` returns `inverseOps` for reversible ops (insert/remove, replace, set-layout, reveal/hide-field). Store `OverlayApprovalMeta` (forwardOps, inverseOps, actorId, approvedAt) with each approved overlay. Use `rollbackSurfacePatches(plan, approvalStack, count)` to revert last N patches.
+
+**Rollback limits**: move-node, resize-panel, set-focus, promote-action require previous state for full inverse; currently return null inverse. Document when storing approval metadata.
+
+## Rollout Status
+
+See [ROLLOUT.md](./ROLLOUT.md) for the phased rollout plan, performance budgets, risks, and pilot route (`/operate/pm/issues/:issueId`).
+
+**Current:** Phase 0–2 complete (scaffold, resolver, renderer). Phase 3–7 pending.
+
+## Adapter Rule (Lint)
+
+**Rule**: No direct third-party UI imports outside `src/adapters/`. BlockNote, dnd-kit, Floating UI, Motion, resizable-panels, AI SDK UI—all must be behind adapter boundaries.
+
+**Enforcement**: Run `bun run lint:adapters` to detect violations. Integrate into CI if desired.
+
+## Phase 2 Status
+
+Types, defineModuleBundle, resolveBundle, applySurfacePatch, BundleProvider, BundleRenderer, RegionRenderer, SlotRenderer, and adapter stubs are implemented. ResolvedSurfacePlan includes layoutRoot for rendering. Motion tokens map pace to duration/entrance. Panel persistence (persistKey) via localStorage. Full BlockNote/dnd-kit/Floating UI integrations deferred to later phases. Planner prompt compiler, propose-patch tool schema, and patch proposal validator added for AI chat integration.
+
+**Observability (09):** Tracing (`traceAsync`), metrics (`resolution_duration_ms`, patch acceptance/rejection, policy denial, surface fallback, missing renderer), structured logging. Golden-context harness for resolver evals with snapshot tests. Performance budget: resolver p95 <100ms (server). See [docs/evals-runbook.md](./docs/evals-runbook.md) and `./telemetry`.

package/dist/adapters/ai-sdk-stub.d.ts

@@ -0,0 +1,5 @@
+/**
+ * AI SDK adapter stub. Full planner/chat integration deferred to Phase 5.
+ */
+import type { AiSdkBundleAdapter } from './interfaces';
+export declare const aiSdkAdapterStub: AiSdkBundleAdapter;

package/dist/adapters/ai-sdk-stub.js

@@ -0,0 +1,13 @@
+// @bun
+// src/adapters/ai-sdk-stub.ts
+var aiSdkAdapterStub = {
+  startThread(_args) {
+    return null;
+  },
+  async requestPatches(_args) {
+    return [];
+  }
+};
+export {
+  aiSdkAdapterStub
+};

package/dist/adapters/blocknote-stub.d.ts

@@ -0,0 +1,6 @@
+/**
+ * BlockNote adapter stub. Full integration deferred.
+ * No direct BlockNote imports in Phase 2.
+ */
+import type { BlockNoteBundleAdapter } from './interfaces';
+export declare const blocknoteAdapterStub: BlockNoteBundleAdapter;

package/dist/adapters/blocknote-stub.js

@@ -0,0 +1,31 @@
+// @bun
+// src/adapters/blocknote-stub.tsx
+import { jsxDEV } from "react/jsx-dev-runtime";
+var blocknoteAdapterStub = {
+  supportsNode(_kind) {
+    return false;
+  },
+  createSchema(_registry) {
+    return {};
+  },
+  renderNode(node, _ctx) {
+    return /* @__PURE__ */ jsxDEV("div", {
+      "data-blocknote-stub": true,
+      "data-node-id": node.nodeId,
+      children: node.title ?? node.kind
+    }, undefined, false, undefined, this);
+  },
+  async serialize(node) {
+    return { nodeId: node.nodeId, kind: node.kind };
+  },
+  async deserialize(input) {
+    const o = input;
+    return {
+      nodeId: o?.nodeId ?? "stub",
+      kind: o?.kind ?? "custom-widget"
+    };
+  }
+};
+export {
+  blocknoteAdapterStub
+};

package/dist/adapters/dnd-kit-adapter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * dnd-kit adapter for customization mode. Wraps content in DndContext.
+ * Requires @dnd-kit/core (optional peer). Falls back to stub when not installed.
+ */
+import React from 'react';
+import type { SurfacePatchOp } from '../spec/types';
+import type { DragDropBundleAdapter } from './interfaces';
+export interface DndWrapperProps {
+    children: React.ReactNode;
+    mutableSlots: string[];
+    onPatch: (ops: SurfacePatchOp[]) => void;
+}
+export declare const dndKitAdapter: DragDropBundleAdapter;

package/dist/adapters/dnd-kit-adapter.js

@@ -0,0 +1,44 @@
+// @bun
+// src/adapters/dnd-kit-adapter.tsx
+import {
+  DndContext,
+  PointerSensor,
+  useSensor,
+  useSensors
+} from "@dnd-kit/core";
+import { jsxDEV } from "react/jsx-dev-runtime";
+"use client";
+var noop = () => {
+  return;
+};
+var _onPatch = noop;
+function handleDragEnd(event) {
+  const { active, over } = event;
+  if (!over)
+    return;
+  const fromId = active.id;
+  const toSlotId = over.id;
+  if (fromId && toSlotId) {
+    _onPatch([{ op: "move-node", nodeId: fromId, toSlotId }]);
+  }
+}
+function DndWrapperComponent({ children, onPatch }) {
+  _onPatch = onPatch;
+  const sensors = useSensors(useSensor(PointerSensor, {
+    activationConstraint: { distance: 8 }
+  }));
+  return /* @__PURE__ */ jsxDEV(DndContext, {
+    sensors,
+    onDragEnd: handleDragEnd,
+    children
+  }, undefined, false, undefined, this);
+}
+var dndKitAdapter = {
+  enableSurfaceEditing(args) {
+    _onPatch = args.onPatch;
+  },
+  DndWrapper: DndWrapperComponent
+};
+export {
+  dndKitAdapter
+};

package/dist/adapters/dnd-kit-stub.d.ts

@@ -0,0 +1,6 @@
+/**
+ * dnd-kit adapter stub. Full customization mode deferred to Phase 6.
+ * No direct dnd-kit imports in Phase 2.
+ */
+import type { DragDropBundleAdapter } from './interfaces';
+export declare const dndKitAdapterStub: DragDropBundleAdapter;

package/dist/adapters/dnd-kit-stub.js

@@ -0,0 +1,8 @@
+// @bun
+// src/adapters/dnd-kit-stub.ts
+var dndKitAdapterStub = {
+  enableSurfaceEditing(_args) {}
+};
+export {
+  dndKitAdapterStub
+};

package/dist/adapters/floating-ui-stub.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Floating UI adapter stub. Full implementation deferred.
+ * No direct Floating UI imports in Phase 2.
+ */
+import type { FloatingBundleAdapter } from './interfaces';
+export declare const floatingUiAdapterStub: FloatingBundleAdapter;

package/dist/adapters/floating-ui-stub.js

@@ -0,0 +1,19 @@
+// @bun
+// src/adapters/floating-ui-stub.tsx
+import { jsxDEV } from "react/jsx-dev-runtime";
+var floatingUiAdapterStub = {
+  renderAnchoredMenu({ anchorId, items }) {
+    return /* @__PURE__ */ jsxDEV("div", {
+      "data-floating-stub": true,
+      "data-anchor-id": anchorId,
+      role: "menu",
+      children: items.map((a) => /* @__PURE__ */ jsxDEV("div", {
+        role: "menuitem",
+        children: a.title
+      }, a.actionId, false, undefined, this))
+    }, undefined, false, undefined, this);
+  }
+};
+export {
+  floatingUiAdapterStub
+};

package/dist/adapters/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * UI library adapters. No direct third-party imports outside this directory.
+ */
+export type { AiSdkBundleAdapter, BlockNoteBundleAdapter, DragDropBundleAdapter, FieldRendererRegistry, FloatingBundleAdapter, MotionBundleAdapter, MotionTokens, PanelLayoutAdapter, RenderContext, RenderRegionFn, } from './interfaces';
+export { aiSdkAdapterStub } from './ai-sdk-stub';
+export { blocknoteAdapterStub } from './blocknote-stub';
+export { dndKitAdapterStub } from './dnd-kit-stub';
+export { dndKitAdapter } from './dnd-kit-adapter';
+export { floatingUiAdapterStub } from './floating-ui-stub';
+export { motionAdapterStub } from './motion-stub';
+export { resizablePanelsAdapterStub } from './resizable-panels-stub';

package/dist/adapters/index.js

@@ -0,0 +1,176 @@
+// @bun
+// src/adapters/ai-sdk-stub.ts
+var aiSdkAdapterStub = {
+  startThread(_args) {
+    return null;
+  },
+  async requestPatches(_args) {
+    return [];
+  }
+};
+
+// src/adapters/blocknote-stub.tsx
+import { jsxDEV } from "react/jsx-dev-runtime";
+var blocknoteAdapterStub = {
+  supportsNode(_kind) {
+    return false;
+  },
+  createSchema(_registry) {
+    return {};
+  },
+  renderNode(node, _ctx) {
+    return /* @__PURE__ */ jsxDEV("div", {
+      "data-blocknote-stub": true,
+      "data-node-id": node.nodeId,
+      children: node.title ?? node.kind
+    }, undefined, false, undefined, this);
+  },
+  async serialize(node) {
+    return { nodeId: node.nodeId, kind: node.kind };
+  },
+  async deserialize(input) {
+    const o = input;
+    return {
+      nodeId: o?.nodeId ?? "stub",
+      kind: o?.kind ?? "custom-widget"
+    };
+  }
+};
+
+// src/adapters/dnd-kit-adapter.tsx
+import {
+  DndContext,
+  PointerSensor,
+  useSensor,
+  useSensors
+} from "@dnd-kit/core";
+import { jsxDEV as jsxDEV2 } from "react/jsx-dev-runtime";
+"use client";
+var noop = () => {
+  return;
+};
+var _onPatch = noop;
+function handleDragEnd(event) {
+  const { active, over } = event;
+  if (!over)
+    return;
+  const fromId = active.id;
+  const toSlotId = over.id;
+  if (fromId && toSlotId) {
+    _onPatch([{ op: "move-node", nodeId: fromId, toSlotId }]);
+  }
+}
+function DndWrapperComponent({ children, onPatch }) {
+  _onPatch = onPatch;
+  const sensors = useSensors(useSensor(PointerSensor, {
+    activationConstraint: { distance: 8 }
+  }));
+  return /* @__PURE__ */ jsxDEV2(DndContext, {
+    sensors,
+    onDragEnd: handleDragEnd,
+    children
+  }, undefined, false, undefined, this);
+}
+var dndKitAdapter = {
+  enableSurfaceEditing(args) {
+    _onPatch = args.onPatch;
+  },
+  DndWrapper: DndWrapperComponent
+};
+
+// src/adapters/dnd-kit-stub.ts
+var dndKitAdapterStub = {
+  enableSurfaceEditing(_args) {}
+};
+
+// src/adapters/floating-ui-stub.tsx
+import { jsxDEV as jsxDEV3 } from "react/jsx-dev-runtime";
+var floatingUiAdapterStub = {
+  renderAnchoredMenu({ anchorId, items }) {
+    return /* @__PURE__ */ jsxDEV3("div", {
+      "data-floating-stub": true,
+      "data-anchor-id": anchorId,
+      role: "menu",
+      children: items.map((a) => /* @__PURE__ */ jsxDEV3("div", {
+        role: "menuitem",
+        children: a.title
+      }, a.actionId, false, undefined, this))
+    }, undefined, false, undefined, this);
+  }
+};
+
+// src/adapters/motion-stub.ts
+var PACE_TOKENS = {
+  deliberate: {
+    durationMs: 300,
+    enableEntrance: true,
+    layout: true
+  },
+  balanced: {
+    durationMs: 150,
+    enableEntrance: true,
+    layout: true
+  },
+  rapid: {
+    durationMs: 50,
+    enableEntrance: false,
+    layout: false
+  }
+};
+var motionAdapterStub = {
+  getTokens(pace) {
+    return PACE_TOKENS[pace] ?? PACE_TOKENS.balanced;
+  }
+};
+
+// src/adapters/resizable-panels-stub.tsx
+import { jsxDEV as jsxDEV4 } from "react/jsx-dev-runtime";
+var LAYOUT_STORAGE_KEY = "surface-runtime:panel-layout:";
+var resizablePanelsAdapterStub = {
+  renderPanelGroup(region, ctx, renderChild) {
+    const direction = region.direction === "horizontal" ? "row" : "column";
+    return /* @__PURE__ */ jsxDEV4("div", {
+      "data-panel-group": true,
+      "data-persist-key": region.persistKey,
+      style: {
+        display: "flex",
+        flexDirection: direction,
+        flex: 1,
+        minHeight: 0
+      },
+      children: region.children.map((child, i) => /* @__PURE__ */ jsxDEV4("div", {
+        style: { flex: 1, minWidth: 0, minHeight: 0 },
+        children: renderChild(child, ctx)
+      }, i, false, undefined, this))
+    }, undefined, false, undefined, this);
+  },
+  async restoreLayout(persistKey) {
+    if (typeof localStorage === "undefined")
+      return null;
+    try {
+      const raw = localStorage.getItem(LAYOUT_STORAGE_KEY + persistKey);
+      if (!raw)
+        return null;
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  },
+  async saveLayout(persistKey, sizes) {
+    if (typeof localStorage === "undefined")
+      return;
+    try {
+      localStorage.setItem(LAYOUT_STORAGE_KEY + persistKey, JSON.stringify(sizes));
+    } catch {}
+  }
+};
+export {
+  resizablePanelsAdapterStub,
+  motionAdapterStub,
+  floatingUiAdapterStub,
+  dndKitAdapterStub,
+  dndKitAdapter,
+  blocknoteAdapterStub,
+  aiSdkAdapterStub
+};

package/dist/adapters/interfaces.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Adapter interfaces for third-party UI libraries.
+ * No direct imports of BlockNote, dnd-kit, Floating UI, Motion, etc. outside adapters/.
+ * Aligns with 06_ui_composition_and_adapters.md.
+ */
+import type { ComponentType, ReactElement } from 'react';
+import type { FieldRendererRegistry } from '../runtime/field-renderer-registry';
+import type { ResolvedSurfacePlan } from '../runtime/resolve-bundle';
+import type { ActionSpec, BundleNodeKind, PanelGroupRegion, PreferenceDimensions, RegionNode, SurfaceNode, SurfacePatchOp, SurfacePatchProposal } from '../spec/types';
+/** Context passed to renderers. */
+export interface RenderContext {
+    plan: ResolvedSurfacePlan;
+    bindings: Record<string, unknown>;
+    preferences: PreferenceDimensions;
+}
+/** Field renderer registry for entity surfaces. See runtime/field-renderer-registry. */
+export type { FieldRendererRegistry };
+/** BlockNote adapter for rich document surfaces. Stub in Phase 2. */
+export interface BlockNoteBundleAdapter {
+    supportsNode(kind: BundleNodeKind): boolean;
+    createSchema(registry: FieldRendererRegistry): unknown;
+    renderNode(node: SurfaceNode, ctx: RenderContext): ReactElement;
+    serialize(node: SurfaceNode): Promise<unknown>;
+    deserialize(input: unknown): Promise<SurfaceNode>;
+}
+/** dnd-kit adapter for drag-and-drop. Stub in Phase 2; full impl in Phase 6. */
+export interface DragDropBundleAdapter {
+    enableSurfaceEditing(args: {
+        mutableSlots: string[];
+        onPatch: (ops: SurfacePatchOp[]) => void;
+    }): void;
+    /** When provided, wrap children for DnD when customization mode is on. */
+    DndWrapper?: ComponentType<{
+        children: React.ReactNode;
+        mutableSlots: string[];
+        onPatch: (ops: SurfacePatchOp[]) => void;
+    }>;
+}
+/** Floating UI adapter for anchored menus and popovers. Stub in Phase 2. */
+export interface FloatingBundleAdapter {
+    renderAnchoredMenu(args: {
+        anchorId: string;
+        items: ActionSpec[];
+    }): ReactElement;
+}
+/** Motion tokens derived from pace preference. */
+export interface MotionTokens {
+    durationMs: number;
+    enableEntrance: boolean;
+    layout: boolean;
+}
+/** Motion adapter for layout transitions. Maps pace to tokens. */
+export interface MotionBundleAdapter {
+    getTokens(pace: PreferenceDimensions['pace']): MotionTokens;
+}
+/** Renders a child region. Passed to panel adapter to avoid adapter→renderer cycle. */
+export type RenderRegionFn = (region: RegionNode, ctx: RenderContext) => ReactElement;
+/** Panels adapter for split-pane workbench layouts. */
+export interface PanelLayoutAdapter {
+    renderPanelGroup(region: PanelGroupRegion, ctx: RenderContext, renderChild: RenderRegionFn): ReactElement;
+    restoreLayout(persistKey: string): Promise<number[] | null>;
+    saveLayout(persistKey: string, sizes: number[]): Promise<void>;
+}
+/** AI SDK adapter for planner/chat integration. Stub in Phase 2. */
+export interface AiSdkBundleAdapter {
+    startThread(args: {
+        plannerId: string;
+        systemPrompt: string;
+        tools: Record<string, unknown>;
+    }): unknown;
+    requestPatches(args: {
+        currentPlan: ResolvedSurfacePlan;
+        userMessage: string;
+    }): Promise<SurfacePatchProposal[]>;
+}

package/dist/adapters/interfaces.js

@@ -0,0 +1 @@
+// @bun

package/dist/adapters/motion-stub.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Motion adapter stub. Maps pace preference to motion tokens.
+ * Aligns with 01_preference_dimensions.md animation mapping.
+ * No direct Motion imports in Phase 2 — tokens drive CSS or future Motion usage.
+ */
+import type { MotionBundleAdapter } from './interfaces';
+export declare const motionAdapterStub: MotionBundleAdapter;

package/dist/adapters/motion-stub.js

@@ -0,0 +1,27 @@
+// @bun
+// src/adapters/motion-stub.ts
+var PACE_TOKENS = {
+  deliberate: {
+    durationMs: 300,
+    enableEntrance: true,
+    layout: true
+  },
+  balanced: {
+    durationMs: 150,
+    enableEntrance: true,
+    layout: true
+  },
+  rapid: {
+    durationMs: 50,
+    enableEntrance: false,
+    layout: false
+  }
+};
+var motionAdapterStub = {
+  getTokens(pace) {
+    return PACE_TOKENS[pace] ?? PACE_TOKENS.balanced;
+  }
+};
+export {
+  motionAdapterStub
+};

package/dist/adapters/motion-stub.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapters/resizable-panels-stub.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resizable panels adapter stub.
+ * Renders panel groups with flex layout. Full react-resizable-panels integration deferred.
+ */
+import type { PanelLayoutAdapter } from './interfaces';
+export declare const resizablePanelsAdapterStub: PanelLayoutAdapter;