@contractspec/lib.surface-runtime 0.2.3 → 0.3.2

package/dist/node/spec/index.js

@@ -1,319 +1,11 @@
-// src/spec/validate-surface-patch.ts
-var VALID_OPS = [
-  "insert-node",
-  "replace-node",
-  "remove-node",
-  "move-node",
-  "resize-panel",
-  "set-layout",
-  "reveal-field",
-  "hide-field",
-  "promote-action",
-  "set-focus"
-];
-var VALID_NODE_KINDS = [
-  "metric-strip",
-  "data-view",
-  "entity-card",
-  "entity-header",
-  "entity-summary",
-  "entity-section",
-  "entity-field",
-  "entity-activity",
-  "entity-relations",
-  "entity-timeline",
-  "entity-comments",
-  "entity-attachments",
-  "entity-view-switcher",
-  "entity-automation-panel",
-  "rich-doc",
-  "chat-thread",
-  "assistant-panel",
-  "action-bar",
-  "timeline",
-  "board",
-  "table",
-  "calendar",
-  "form",
-  "chart",
-  "relation-graph",
-  "custom-widget"
-];
-function validateSurfaceNode(node, path) {
-  if (!node.nodeId || typeof node.nodeId !== "string") {
-    throw new Error(`${path}: nodeId must be a non-empty string`);
-  }
-  if (!node.kind || !VALID_NODE_KINDS.includes(node.kind)) {
-    throw new Error(`${path}: kind must be one of ${VALID_NODE_KINDS.join(", ")}`);
-  }
-  if (node.children) {
-    for (let i = 0;i < node.children.length; i++) {
-      const child = node.children[i];
-      if (child)
-        validateSurfaceNode(child, `${path}.children[${i}]`);
-    }
-  }
-}
-function validateSurfacePatchOp(op, index) {
-  const path = `ops[${index}]`;
-  if (!op || typeof op !== "object" || !("op" in op)) {
-    throw new Error(`${path}: must be an object with op field`);
-  }
-  const opType = op.op;
-  if (!VALID_OPS.includes(opType)) {
-    throw new Error(`${path}: op must be one of ${VALID_OPS.join(", ")}`);
-  }
-  switch (op.op) {
-    case "insert-node":
-      if (!op.slotId || typeof op.slotId !== "string") {
-        throw new Error(`${path}: insert-node requires slotId string`);
-      }
-      if (!op.node) {
-        throw new Error(`${path}: insert-node requires node`);
-      }
-      validateSurfaceNode(op.node, `${path}.node`);
-      if (op.index !== undefined && typeof op.index !== "number") {
-        throw new Error(`${path}: insert-node index must be number if present`);
-      }
-      break;
-    case "replace-node":
-      if (!op.nodeId || typeof op.nodeId !== "string") {
-        throw new Error(`${path}: replace-node requires nodeId string`);
-      }
-      if (!op.node) {
-        throw new Error(`${path}: replace-node requires node`);
-      }
-      validateSurfaceNode(op.node, `${path}.node`);
-      break;
-    case "remove-node":
-      if (!op.nodeId || typeof op.nodeId !== "string") {
-        throw new Error(`${path}: remove-node requires nodeId string`);
-      }
-      break;
-    case "move-node":
-      if (!op.nodeId || typeof op.nodeId !== "string") {
-        throw new Error(`${path}: move-node requires nodeId string`);
-      }
-      if (!op.toSlotId || typeof op.toSlotId !== "string") {
-        throw new Error(`${path}: move-node requires toSlotId string`);
-      }
-      if (op.index !== undefined && typeof op.index !== "number") {
-        throw new Error(`${path}: move-node index must be number if present`);
-      }
-      break;
-    case "resize-panel":
-      if (!op.persistKey || typeof op.persistKey !== "string") {
-        throw new Error(`${path}: resize-panel requires persistKey string`);
-      }
-      if (!Array.isArray(op.sizes) || op.sizes.some((s) => typeof s !== "number")) {
-        throw new Error(`${path}: resize-panel requires sizes number[]`);
-      }
-      break;
-    case "set-layout":
-      if (!op.layoutId || typeof op.layoutId !== "string") {
-        throw new Error(`${path}: set-layout requires layoutId string`);
-      }
-      break;
-    case "reveal-field":
-    case "hide-field":
-      if (!op.fieldId || typeof op.fieldId !== "string") {
-        throw new Error(`${path}: ${op.op} requires fieldId string`);
-      }
-      break;
-    case "promote-action": {
-      if (!op.actionId || typeof op.actionId !== "string") {
-        throw new Error(`${path}: promote-action requires actionId string`);
-      }
-      const validPlacements = ["header", "inline", "context", "assistant"];
-      if (!op.placement || !validPlacements.includes(op.placement)) {
-        throw new Error(`${path}: promote-action placement must be one of ${validPlacements.join(", ")}`);
-      }
-      break;
-    }
-    case "set-focus":
-      if (!op.targetId || typeof op.targetId !== "string") {
-        throw new Error(`${path}: set-focus requires targetId string`);
-      }
-      break;
-    default:
-      throw new Error(`${path}: unknown op "${opType}"`);
-  }
-}
-function validateSurfacePatch(ops) {
-  if (!Array.isArray(ops)) {
-    throw new Error("Patch ops must be an array");
-  }
-  for (let i = 0;i < ops.length; i++) {
-    const op = ops[i];
-    if (op)
-      validateSurfacePatchOp(op, i);
-  }
-}
-function validateSurfaceNodeAgainstKinds(node, allowedKinds, path) {
-  if (!allowedKinds.includes(node.kind)) {
-    throw new Error(`${path}: kind "${node.kind}" not in allowed list [${allowedKinds.join(", ")}]`);
-  }
-  if (node.children) {
-    for (let i = 0;i < node.children.length; i++) {
-      const child = node.children[i];
-      if (child)
-        validateSurfaceNodeAgainstKinds(child, allowedKinds, `${path}.children[${i}]`);
-    }
-  }
-}
-function validatePatchProposal(ops, constraints) {
-  if (!Array.isArray(ops)) {
-    throw new Error("Patch ops must be an array");
-  }
-  const { allowedOps, allowedSlots, allowedNodeKinds } = constraints;
-  for (let i = 0;i < ops.length; i++) {
-    const op = ops[i];
-    if (!op)
-      continue;
-    const path = `ops[${i}]`;
-    if (!allowedOps.includes(op.op)) {
-      throw new Error(`${path}: op "${op.op}" not in allowed list [${allowedOps.join(", ")}]`);
-    }
-    switch (op.op) {
-      case "insert-node":
-        if (!allowedSlots.includes(op.slotId)) {
-          throw new Error(`${path}: slotId "${op.slotId}" not in allowed slots [${allowedSlots.join(", ")}]`);
-        }
-        if (op.node) {
-          validateSurfaceNodeAgainstKinds(op.node, allowedNodeKinds, `${path}.node`);
-        }
-        break;
-      case "move-node":
-        if (!allowedSlots.includes(op.toSlotId)) {
-          throw new Error(`${path}: toSlotId "${op.toSlotId}" not in allowed slots [${allowedSlots.join(", ")}]`);
-        }
-        break;
-      case "replace-node":
-        if (op.node) {
-          validateSurfaceNodeAgainstKinds(op.node, allowedNodeKinds, `${path}.node`);
-        }
-        break;
-      default:
-        break;
-    }
-  }
-  validateSurfacePatch(ops);
-}
-// src/spec/validate-bundle.ts
-var KNOWN_NODE_KIND_RENDERERS = new Set([
-  "entity-section",
-  "entity-field",
-  "action-bar",
-  "table",
-  "timeline",
-  "rich-doc",
-  "chat-thread",
-  "assistant-panel",
-  "entity-card",
-  "entity-header",
-  "entity-summary",
-  "entity-activity",
-  "entity-relations",
-  "relation-graph",
-  "custom-widget"
-]);
-function collectSlotIdsFromRegion(node) {
-  const ids = [];
-  if (node.type === "slot") {
-    ids.push(node.slotId);
-  }
-  if (node.type === "panel-group" || node.type === "stack") {
-    for (const child of node.children) {
-      ids.push(...collectSlotIdsFromRegion(child));
-    }
-  }
-  if (node.type === "tabs") {
-    for (const tab of node.tabs) {
-      ids.push(...collectSlotIdsFromRegion(tab.child));
-    }
-  }
-  if (node.type === "floating") {
-    ids.push(node.anchorSlotId);
-    ids.push(...collectSlotIdsFromRegion(node.child));
-  }
-  return ids;
-}
-function validateLayoutSlots(surface) {
-  const declaredSlotIds = new Set(surface.slots.map((s) => s.slotId));
-  for (const layout of surface.layouts) {
-    const layoutSlotIds = collectSlotIdsFromRegion(layout.root);
-    for (const slotId of layoutSlotIds) {
-      if (!declaredSlotIds.has(slotId)) {
-        throw new Error(`Surface "${surface.surfaceId}" layout "${layout.layoutId}" references undeclared slot "${slotId}". Declared slots: ${[...declaredSlotIds].join(", ")}`);
-      }
-    }
-  }
-}
-function validateBundleNodeKinds(surface) {
-  const warnings = [];
-  for (const slot of surface.slots) {
-    for (const kind of slot.accepts) {
-      if (!KNOWN_NODE_KIND_RENDERERS.has(kind)) {
-        warnings.push(`Surface "${surface.surfaceId}" slot "${slot.slotId}" accepts "${kind}" which has no dedicated renderer (generic fallback used)`);
-      }
-    }
-  }
-  return { warnings };
-}
-
-// src/spec/define-module-bundle.ts
-function defineModuleBundle(spec) {
-  if (!spec.meta?.key || !spec.meta?.version || !spec.meta?.title) {
-    throw new Error("ModuleBundleSpec must have meta.key, meta.version, and meta.title");
-  }
-  if (!spec.routes?.length) {
-    throw new Error("ModuleBundleSpec must have at least one route");
-  }
-  if (!spec.surfaces || Object.keys(spec.surfaces).length === 0) {
-    throw new Error("ModuleBundleSpec must have at least one surface");
-  }
-  if (spec.entities) {
-    if (!spec.entities.entityTypes || typeof spec.entities.entityTypes !== "object") {
-      throw new Error("ModuleBundleSpec.entities must have entityTypes object when present");
-    }
-    if (!spec.entities.fieldKinds || typeof spec.entities.fieldKinds !== "object") {
-      throw new Error("ModuleBundleSpec.entities must have fieldKinds object when present");
-    }
-  }
-  const REQUIRED_DIMENSIONS = [
-    "guidance",
-    "density",
-    "dataDepth",
-    "control",
-    "media",
-    "pace",
-    "narrative"
-  ];
-  const MIN_DESCRIPTION_LENGTH = 10;
-  for (const surface of Object.values(spec.surfaces)) {
-    if (!surface.verification?.dimensions) {
-      throw new Error(`Surface "${surface.surfaceId}" must have verification.dimensions for all 7 preference dimensions`);
-    }
-    const dims = surface.verification.dimensions;
-    for (const d of REQUIRED_DIMENSIONS) {
-      const val = dims[d];
-      if (!val || typeof val !== "string") {
-        throw new Error(`Surface "${surface.surfaceId}" verification.dimensions.${d} must be a non-empty string`);
-      }
-      const trimmed = val.trim();
-      if (trimmed.length < MIN_DESCRIPTION_LENGTH) {
-        throw new Error(`Surface "${surface.surfaceId}" verification.dimensions.${d} must be at least ${MIN_DESCRIPTION_LENGTH} characters (got ${trimmed.length})`);
-      }
-    }
-    validateLayoutSlots(surface);
-  }
-  return spec;
-}
+export * from "./types";
+export { defineModuleBundle } from "./define-module-bundle";
 export {
-  validateSurfacePatchOp,
-  validateSurfacePatch,
-  validatePatchProposal,
   validateLayoutSlots,
-  validateBundleNodeKinds,
-  defineModuleBundle
-};
+  validateBundleNodeKinds
+} from "./validate-bundle";
+export {
+  validateSurfacePatch,
+  validateSurfacePatchOp,
+  validatePatchProposal
+} from "./validate-surface-patch";

package/dist/node/spec/validate-bundle.js

@@ -1,5 +1,4 @@
-// src/spec/validate-bundle.ts
-var KNOWN_NODE_KIND_RENDERERS = new Set([
+const KNOWN_NODE_KIND_RENDERERS = new Set([
   "entity-section",
   "entity-field",
   "action-bar",
@@ -37,7 +36,7 @@ function collectSlotIdsFromRegion(node) {
   }
   return ids;
 }
-function validateLayoutSlots(surface) {
+export function validateLayoutSlots(surface) {
   const declaredSlotIds = new Set(surface.slots.map((s) => s.slotId));
   for (const layout of surface.layouts) {
     const layoutSlotIds = collectSlotIdsFromRegion(layout.root);
@@ -48,7 +47,7 @@ function validateLayoutSlots(surface) {
     }
   }
 }
-function validateBundleNodeKinds(surface) {
+export function validateBundleNodeKinds(surface) {
   const warnings = [];
   for (const slot of surface.slots) {
     for (const kind of slot.accepts) {
@@ -59,7 +58,3 @@ function validateBundleNodeKinds(surface) {
   }
   return { warnings };
 }
-export {
-  validateLayoutSlots,
-  validateBundleNodeKinds
-};

package/dist/node/spec/validate-surface-patch.js

@@ -1,5 +1,4 @@
-// src/spec/validate-surface-patch.ts
-var VALID_OPS = [
+const VALID_OPS = [
   "insert-node",
   "replace-node",
   "remove-node",
@@ -11,7 +10,7 @@ var VALID_OPS = [
   "promote-action",
   "set-focus"
 ];
-var VALID_NODE_KINDS = [
+const VALID_NODE_KINDS = [
   "metric-strip",
   "data-view",
   "entity-card",
@@ -54,7 +53,7 @@ function validateSurfaceNode(node, path) {
     }
   }
 }
-function validateSurfacePatchOp(op, index) {
+export function validateSurfacePatchOp(op, index) {
   const path = `ops[${index}]`;
   if (!op || typeof op !== "object" || !("op" in op)) {
     throw new Error(`${path}: must be an object with op field`);
@@ -139,7 +138,7 @@ function validateSurfacePatchOp(op, index) {
       throw new Error(`${path}: unknown op "${opType}"`);
   }
 }
-function validateSurfacePatch(ops) {
+export function validateSurfacePatch(ops) {
   if (!Array.isArray(ops)) {
     throw new Error("Patch ops must be an array");
   }
@@ -161,7 +160,7 @@ function validateSurfaceNodeAgainstKinds(node, allowedKinds, path) {
     }
   }
 }
-function validatePatchProposal(ops, constraints) {
+export function validatePatchProposal(ops, constraints) {
   if (!Array.isArray(ops)) {
     throw new Error("Patch ops must be an array");
   }
@@ -199,8 +198,3 @@ function validatePatchProposal(ops, constraints) {
   }
   validateSurfacePatch(ops);
 }
-export {
-  validateSurfacePatchOp,
-  validateSurfacePatch,
-  validatePatchProposal
-};

package/dist/node/telemetry/index.js

@@ -1,20 +1,8 @@
-// src/telemetry/surface-metrics.ts
-import {
-  createCounter,
-  createHistogram
-} from "@contractspec/lib.observability/metrics";
-var METER_NAME = "@contractspec/lib.surface-runtime";
-var resolutionDurationMs = createHistogram("bundle_surface_resolution_duration_ms", "Time to resolve bundle spec to surface plan in milliseconds", METER_NAME);
-var patchAcceptanceCounter = createCounter("bundle_surface_patch_acceptance_total", "Total AI patch proposals accepted by user", METER_NAME);
-var patchRejectionCounter = createCounter("bundle_surface_patch_rejection_total", "Total AI patch proposals rejected by user", METER_NAME);
-var policyDenialCounter = createCounter("bundle_surface_policy_denial_total", "Total policy denials (actions denied by policy)", METER_NAME);
-var surfaceFallbackCounter = createCounter("bundle_surface_fallback_total", "Total surface or layout fallbacks during resolution", METER_NAME);
-var missingRendererCounter = createCounter("bundle_surface_renderer_missing_total", "Total slots with no renderer for requested node kind", METER_NAME);
 export {
-  surfaceFallbackCounter,
   resolutionDurationMs,
-  policyDenialCounter,
-  patchRejectionCounter,
   patchAcceptanceCounter,
+  patchRejectionCounter,
+  policyDenialCounter,
+  surfaceFallbackCounter,
   missingRendererCounter
-};
+} from "./surface-metrics";

package/dist/node/telemetry/surface-metrics.js

@@ -1,20 +1,11 @@
-// src/telemetry/surface-metrics.ts
 import {
   createCounter,
   createHistogram
 } from "@contractspec/lib.observability/metrics";
-var METER_NAME = "@contractspec/lib.surface-runtime";
-var resolutionDurationMs = createHistogram("bundle_surface_resolution_duration_ms", "Time to resolve bundle spec to surface plan in milliseconds", METER_NAME);
-var patchAcceptanceCounter = createCounter("bundle_surface_patch_acceptance_total", "Total AI patch proposals accepted by user", METER_NAME);
-var patchRejectionCounter = createCounter("bundle_surface_patch_rejection_total", "Total AI patch proposals rejected by user", METER_NAME);
-var policyDenialCounter = createCounter("bundle_surface_policy_denial_total", "Total policy denials (actions denied by policy)", METER_NAME);
-var surfaceFallbackCounter = createCounter("bundle_surface_fallback_total", "Total surface or layout fallbacks during resolution", METER_NAME);
-var missingRendererCounter = createCounter("bundle_surface_renderer_missing_total", "Total slots with no renderer for requested node kind", METER_NAME);
-export {
-  surfaceFallbackCounter,
-  resolutionDurationMs,
-  policyDenialCounter,
-  patchRejectionCounter,
-  patchAcceptanceCounter,
-  missingRendererCounter
-};
+const METER_NAME = "@contractspec/lib.surface-runtime";
+export const resolutionDurationMs = createHistogram("bundle_surface_resolution_duration_ms", "Time to resolve bundle spec to surface plan in milliseconds", METER_NAME);
+export const patchAcceptanceCounter = createCounter("bundle_surface_patch_acceptance_total", "Total AI patch proposals accepted by user", METER_NAME);
+export const patchRejectionCounter = createCounter("bundle_surface_patch_rejection_total", "Total AI patch proposals rejected by user", METER_NAME);
+export const policyDenialCounter = createCounter("bundle_surface_policy_denial_total", "Total policy denials (actions denied by policy)", METER_NAME);
+export const surfaceFallbackCounter = createCounter("bundle_surface_fallback_total", "Total surface or layout fallbacks during resolution", METER_NAME);
+export const missingRendererCounter = createCounter("bundle_surface_renderer_missing_total", "Total slots with no renderer for requested node kind", METER_NAME);

package/dist/react/BundleProvider.js

@@ -1,48 +1,40 @@
-// @bun
-// src/react/BundleProvider.tsx
-import { createContext, useContext } from "react";
-import { jsxDEV } from "react/jsx-dev-runtime";
 "use client";
-var BundlePlanContext = createContext(null);
-var PreferencesContext = createContext(null);
-var EditingContext = createContext(false);
-function BundleProvider({
+import { jsxDEV as jsxDEV_7x81h0kn } from "react/jsx-dev-runtime";
+import { createContext, useContext } from "react";
+const BundlePlanContext = createContext(null);
+const PreferencesContext = createContext(null);
+const EditingContext = createContext(false);
+export function BundleProvider({
   plan,
   children,
   isEditing = false
 }) {
   const preferences = plan.adaptation.appliedDimensions;
-  return /* @__PURE__ */ jsxDEV(BundlePlanContext.Provider, {
+  return /* @__PURE__ */ jsxDEV_7x81h0kn(BundlePlanContext.Provider, {
     value: plan,
-    children: /* @__PURE__ */ jsxDEV(PreferencesContext.Provider, {
+    children: /* @__PURE__ */ jsxDEV_7x81h0kn(PreferencesContext.Provider, {
       value: preferences,
-      children: /* @__PURE__ */ jsxDEV(EditingContext.Provider, {
+      children: /* @__PURE__ */ jsxDEV_7x81h0kn(EditingContext.Provider, {
         value: isEditing,
         children
       }, undefined, false, undefined, this)
     }, undefined, false, undefined, this)
   }, undefined, false, undefined, this);
 }
-function useIsEditing() {
+export function useIsEditing() {
   return useContext(EditingContext);
 }
-function useBundlePlan() {
+export function useBundlePlan() {
   const value = useContext(BundlePlanContext);
   if (!value) {
     throw new Error("useBundlePlan must be used inside BundleProvider.");
   }
   return value;
 }
-function useBundlePreferences() {
+export function useBundlePreferences() {
   const value = useContext(PreferencesContext);
   if (!value) {
     throw new Error("useBundlePreferences must be used inside BundleProvider.");
   }
   return value;
 }
-export {
-  useIsEditing,
-  useBundlePreferences,
-  useBundlePlan,
-  BundleProvider
-};

package/dist/react/BundleRenderer.d.ts

@@ -4,6 +4,8 @@ export interface BundleRendererProps {
     assistantSlotId?: string;
     /** Content for the assistant slot (e.g. ChatContainer with useChat). */
     assistantSlotContent?: React.ReactNode;
+    /** Override content for any slot. When provided, renders this instead of SlotRenderer for the given slotId. */
+    slotContent?: Partial<Record<string, React.ReactNode>>;
     /** Called when user accepts a patch proposal. Caller should apply patch and update plan. */
     onPatchAccept?: (proposalId: string) => void;
     /** Called when user rejects a patch proposal. Caller should remove from proposals and emit audit. */
@@ -19,4 +21,4 @@ export interface BundleRendererProps {
  * Composes RegionRenderer (layout tree), SlotRenderer, and motion tokens from pace.
  * When assistantSlotId is set and matches a slot, renders assistantSlotContent instead.
  */
-export declare function BundleRenderer({ assistantSlotId, assistantSlotContent, onPatchAccept, onPatchReject, onOverlayConflictResolve, }?: BundleRendererProps): import("react/jsx-runtime").JSX.Element;
+export declare function BundleRenderer({ assistantSlotId, assistantSlotContent, slotContent, onPatchAccept, onPatchReject, onOverlayConflictResolve, }?: BundleRendererProps): import("react/jsx-runtime").JSX.Element;