@contractspec/lib.surface-runtime 0.2.0

package/dist/node/examples/pm-workbench.bundle.js

@@ -0,0 +1,476 @@
+// 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;
+}
+// src/examples/pm-workbench.bundle.ts
+var PmWorkbenchBundle = defineModuleBundle({
+  meta: {
+    key: "pm.workbench",
+    version: "0.1.0",
+    title: "PM Workbench",
+    description: "AI-native PM workbench for relation-rich issues and saved views",
+    owners: ["team-pm-platform"],
+    tags: ["pm", "issues", "workbench", "ai-native"],
+    stability: "experimental"
+  },
+  routes: [
+    {
+      routeId: "pm-issue",
+      path: "/operate/pm/issues/:issueId",
+      defaultSurface: "issue-workbench"
+    }
+  ],
+  entities: {
+    entityTypes: {
+      "pm.issue": {
+        entityType: "pm.issue",
+        defaultSurfaceId: "issue-workbench",
+        detailBlueprints: ["balanced-three-pane", "dense-ops-mode"],
+        supportedViews: [
+          "minimal-summary",
+          "balanced-detail",
+          "dense-workbench"
+        ],
+        sectionsFromSchema: true,
+        fieldsFromSchema: true,
+        relationPanels: ["relations", "meeting-evidence", "decision-trail"]
+      }
+    },
+    fieldKinds: {
+      text: { fieldKind: "text", viewer: "text-viewer", editor: "text-editor" },
+      number: {
+        fieldKind: "number",
+        viewer: "number-viewer",
+        editor: "number-editor"
+      },
+      date: { fieldKind: "date", viewer: "date-viewer", editor: "date-editor" },
+      select: {
+        fieldKind: "select",
+        viewer: "select-viewer",
+        editor: "select-editor"
+      }
+    },
+    sectionKinds: {
+      overview: { sectionKind: "overview", renderer: "section-overview" },
+      details: { sectionKind: "details", renderer: "section-details" },
+      relations: { sectionKind: "relations", renderer: "section-relations" },
+      activity: { sectionKind: "activity", renderer: "section-activity" }
+    },
+    viewKinds: {
+      "minimal-summary": {
+        viewKind: "minimal-summary",
+        renderer: "view-minimal"
+      },
+      "balanced-detail": {
+        viewKind: "balanced-detail",
+        renderer: "view-balanced",
+        defaultLayoutId: "balanced-three-pane"
+      },
+      "dense-workbench": {
+        viewKind: "dense-workbench",
+        renderer: "view-dense",
+        defaultLayoutId: "dense-ops-mode"
+      }
+    }
+  },
+  surfaces: {
+    "issue-workbench": {
+      surfaceId: "issue-workbench",
+      kind: "workbench",
+      title: "Issue Workbench",
+      slots: [
+        {
+          slotId: "header",
+          role: "header",
+          accepts: ["action-bar"],
+          cardinality: "many"
+        },
+        {
+          slotId: "primary",
+          role: "primary",
+          accepts: ["entity-section", "table", "rich-doc"],
+          cardinality: "many",
+          mutableByAi: true,
+          mutableByUser: true
+        },
+        {
+          slotId: "secondary",
+          role: "secondary",
+          accepts: ["entity-section", "table", "timeline"],
+          cardinality: "many",
+          mutableByAi: true,
+          mutableByUser: true
+        },
+        {
+          slotId: "assistant",
+          role: "assistant",
+          accepts: ["assistant-panel", "chat-thread"],
+          cardinality: "many",
+          mutableByAi: true,
+          mutableByUser: true
+        },
+        {
+          slotId: "inspector",
+          role: "inspector",
+          accepts: ["entity-field", "relation-graph", "custom-widget"],
+          cardinality: "many",
+          mutableByAi: true,
+          mutableByUser: true
+        }
+      ],
+      layouts: [
+        {
+          layoutId: "balanced-three-pane",
+          title: "Balanced 3-pane",
+          root: {
+            type: "panel-group",
+            direction: "horizontal",
+            persistKey: "pm.issue.balanced-three-pane",
+            children: [
+              { type: "slot", slotId: "primary" },
+              {
+                type: "panel-group",
+                direction: "vertical",
+                persistKey: "pm.issue.right-stack",
+                children: [
+                  { type: "slot", slotId: "secondary" },
+                  { type: "slot", slotId: "assistant" }
+                ]
+              },
+              { type: "slot", slotId: "inspector" }
+            ]
+          }
+        }
+      ],
+      data: [
+        {
+          recipeId: "issue-core",
+          source: { kind: "entity", entityType: "pm.issue" },
+          requestedDepth: "detailed",
+          hydrateInto: "issue"
+        }
+      ],
+      verification: {
+        dimensions: {
+          guidance: "Can reveal walkthrough notes, field help, and AI explanations.",
+          density: "Can select compact, balanced, or dense multi-pane layouts.",
+          dataDepth: "Controls issue relation hydration, activity size, and inspector depth.",
+          control: "Shows advanced commands and raw config tabs only when allowed.",
+          media: "Supports text-first detail, visual graph, and hybrid assistant modes.",
+          pace: "Maps to motion tokens and confirmation behavior.",
+          narrative: "Can order issue summary before or after evidence/activity sections."
+        }
+      }
+    }
+  }
+});
+export {
+  PmWorkbenchBundle
+};

package/dist/node/i18n/catalogs/en.js

@@ -0,0 +1,71 @@
+// src/i18n/catalogs/en.ts
+import { defineTranslation } from "@contractspec/lib.contracts-spec/translations";
+var enMessages = defineTranslation({
+  meta: {
+    key: "surface-runtime.messages",
+    version: "1.0.0",
+    domain: "surface-runtime",
+    description: "User-facing strings for surface-runtime UI components",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "en",
+  fallback: "en",
+  messages: {
+    "overlay.conflicts.title": {
+      value: "Overlay conflicts",
+      description: "Title for overlay conflict resolution banner"
+    },
+    "overlay.conflicts.keepScope": {
+      value: "Keep {scope}",
+      description: "Button to keep overlay from scope A or B"
+    },
+    "patch.accept": {
+      value: "Accept",
+      description: "Accept patch proposal button"
+    },
+    "patch.reject": {
+      value: "Reject",
+      description: "Reject patch proposal button"
+    },
+    "patch.addWidget": {
+      value: "Add {title} to {slot}",
+      description: "Insert node proposal summary"
+    },
+    "patch.removeItem": {
+      value: "Remove item",
+      description: "Remove node proposal summary"
+    },
+    "patch.switchLayout": {
+      value: "Switch to {layoutId} layout",
+      description: "Set layout proposal summary"
+    },
+    "patch.showField": {
+      value: "Show field {fieldId}",
+      description: "Reveal field proposal summary"
+    },
+    "patch.hideField": {
+      value: "Hide field {fieldId}",
+      description: "Hide field proposal summary"
+    },
+    "patch.moveTo": {
+      value: "Move to {slot}",
+      description: "Move node proposal summary"
+    },
+    "patch.replaceItem": {
+      value: "Replace item",
+      description: "Replace node proposal summary"
+    },
+    "patch.promote": {
+      value: "Promote {actionId}",
+      description: "Promote action proposal summary"
+    },
+    "patch.changes": {
+      value: "{count} changes",
+      description: "Multiple patch ops summary"
+    }
+  }
+});
+export {
+  enMessages
+};

package/dist/node/i18n/catalogs/es.js

@@ -0,0 +1,32 @@
+// src/i18n/catalogs/es.ts
+import { defineTranslation } from "@contractspec/lib.contracts-spec/translations";
+var esMessages = defineTranslation({
+  meta: {
+    key: "surface-runtime.messages",
+    version: "1.0.0",
+    domain: "surface-runtime",
+    description: "User-facing strings for surface-runtime UI components",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "es",
+  fallback: "en",
+  messages: {
+    "overlay.conflicts.title": { value: "Conflictos de superposición" },
+    "overlay.conflicts.keepScope": { value: "Mantener {scope}" },
+    "patch.accept": { value: "Aceptar" },
+    "patch.reject": { value: "Rechazar" },
+    "patch.addWidget": { value: "Añadir {title} a {slot}" },
+    "patch.removeItem": { value: "Eliminar elemento" },
+    "patch.switchLayout": { value: "Cambiar a disposición {layoutId}" },
+    "patch.showField": { value: "Mostrar campo {fieldId}" },
+    "patch.hideField": { value: "Ocultar campo {fieldId}" },
+    "patch.moveTo": { value: "Mover a {slot}" },
+    "patch.replaceItem": { value: "Reemplazar elemento" },
+    "patch.promote": { value: "Promover {actionId}" },
+    "patch.changes": { value: "{count} cambios" }
+  }
+});
+export {
+  esMessages
+};

package/dist/node/i18n/catalogs/fr.js

@@ -0,0 +1,32 @@
+// src/i18n/catalogs/fr.ts
+import { defineTranslation } from "@contractspec/lib.contracts-spec/translations";
+var frMessages = defineTranslation({
+  meta: {
+    key: "surface-runtime.messages",
+    version: "1.0.0",
+    domain: "surface-runtime",
+    description: "User-facing strings for surface-runtime UI components",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "fr",
+  fallback: "en",
+  messages: {
+    "overlay.conflicts.title": { value: "Conflits de superposition" },
+    "overlay.conflicts.keepScope": { value: "Conserver {scope}" },
+    "patch.accept": { value: "Accepter" },
+    "patch.reject": { value: "Rejeter" },
+    "patch.addWidget": { value: "Ajouter {title} à {slot}" },
+    "patch.removeItem": { value: "Supprimer l'élément" },
+    "patch.switchLayout": { value: "Passer à la disposition {layoutId}" },
+    "patch.showField": { value: "Afficher le champ {fieldId}" },
+    "patch.hideField": { value: "Masquer le champ {fieldId}" },
+    "patch.moveTo": { value: "Déplacer vers {slot}" },
+    "patch.replaceItem": { value: "Remplacer l'élément" },
+    "patch.promote": { value: "Promouvoir {actionId}" },
+    "patch.changes": { value: "{count} modifications" }
+  }
+});
+export {
+  frMessages
+};