@contractspec/lib.surface-runtime 0.2.3 → 0.3.2

package/dist/spec/index.js

@@ -1,320 +1,11 @@
-// @bun
-// 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/spec/types.js

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

package/dist/spec/validate-bundle.js

@@ -1,6 +1,4 @@
-// @bun
-// 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",
@@ -38,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);
@@ -49,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) {
@@ -60,7 +58,3 @@ function validateBundleNodeKinds(surface) {
   }
   return { warnings };
 }
-export {
-  validateLayoutSlots,
-  validateBundleNodeKinds
-};

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

@@ -1,6 +1,4 @@
-// @bun
-// src/spec/validate-surface-patch.ts
-var VALID_OPS = [
+const VALID_OPS = [
   "insert-node",
   "replace-node",
   "remove-node",
@@ -12,7 +10,7 @@ var VALID_OPS = [
   "promote-action",
   "set-focus"
 ];
-var VALID_NODE_KINDS = [
+const VALID_NODE_KINDS = [
   "metric-strip",
   "data-view",
   "entity-card",
@@ -55,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`);
@@ -140,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");
   }
@@ -162,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");
   }
@@ -200,8 +198,3 @@ function validatePatchProposal(ops, constraints) {
   }
   validateSurfacePatch(ops);
 }
-export {
-  validateSurfacePatchOp,
-  validateSurfacePatch,
-  validatePatchProposal
-};

package/dist/spec/verification-snapshot-types.js

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

package/dist/telemetry/index.js

@@ -1,21 +1,8 @@
-// @bun
-// 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/telemetry/surface-metrics.js

@@ -1,21 +1,11 @@
-// @bun
-// 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.surface-runtime",
-  "version": "0.2.3",
+  "version": "0.3.2",
   "description": "AI-native surface specs and web runtime for adaptive ContractSpec surfaces",
   "keywords": [
     "contractspec",
@@ -21,7 +21,7 @@
     "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
     "publish:pkg:canary": "bun publish:pkg --tag canary",
     "build": "bun run prebuild && bun run build:bundle && bun run build:types",
-    "build:bundle": "contractspec-bun-build transpile",
+    "build:bundle": "contractspec-bun-build transpile && node scripts/fix-use-client-directive.mjs",
     "build:types": "contractspec-bun-build types",
     "dev": "contractspec-bun-build dev",
     "clean": "rimraf dist .turbo",
@@ -35,9 +35,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.contracts-spec": "3.4.3",
-    "@contractspec/lib.overlay-engine": "3.4.3",
-    "@contractspec/lib.observability": "3.4.3",
+    "@contractspec/lib.contracts-spec": "3.5.2",
+    "@contractspec/lib.overlay-engine": "3.5.2",
+    "@contractspec/lib.observability": "3.5.2",
     "zod": "^4.3.5"
   },
   "peerDependencies": {
@@ -57,10 +57,10 @@
     }
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.4.3",
+    "@contractspec/tool.typescript": "3.5.2",
     "@dnd-kit/core": "^6.3.1",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.4.3"
+    "@contractspec/tool.bun": "3.5.2"
   },
   "exports": {
     ".": {