@tangle-network/agent-app 0.43.56 → 0.43.57

package/dist/chunk-VYECQAGM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/design-canvas-react/engine/snap.ts","../src/design-canvas-react/engine/selection.ts","../src/design-canvas-react/engine/zoom-pan.ts","../src/design-canvas-react/export-math.ts","../src/design-canvas-react/insert-builders.ts"],"sourcesContent":["/**\n * 2-axis snap engine for the design-canvas editor. Targets come from element\n * AABBs (edges + centers), page edges + center, saved guides, and grid lines\n * near the moving bounds. Grid lines are generated lazily in the neighborhood\n * of the moving element, not the full page — avoids allocating thousands of\n * targets on large pages with fine grids.\n *\n * Threshold is a SCREEN distance (pixels), divided by zoom to convert to\n * document units — what \"feels close\" is a screen distance.\n *\n * Tie-breaking: non-grid kinds beat grid on equal distance; among equals of\n * the same priority the first in iteration order wins.\n */\n\nimport { elementAabb } from '../../design-canvas/model'\nimport type { Bounds, SceneElement, ScenePage } from '../../design-canvas/model'\nimport type { EditorSceneState, SnapEngine, SnapResult, SnapTarget, SnapTargetKind, SnapTargets } from '../contracts'\n\n/** Priority rank for tie-breaking: lower = higher priority (wins the tie). */\nconst KIND_PRIORITY: Record<SnapTargetKind, number> = {\n  'guide':          0,\n  'page-edge':      1,\n  'page-center':    2,\n  'element-edge':   3,\n  'element-center': 4,\n  'grid':           5,\n}\n\n/** Build a SnapEngine instance to manage snapping targets and behavior within an editor scene */\nexport function createSnapEngine(): SnapEngine {\n  return {\n    collectTargets(state: EditorSceneState, excludeIds: string[]): SnapTargets {\n      const page = state.document.pages.find((p) => p.id === state.activePageId)\n      if (!page) throw new Error(`collectTargets: active page ${state.activePageId} not found`)\n\n      const vertical: SnapTarget[] = []\n      const horizontal: SnapTarget[] = []\n      const excludeSet = new Set(excludeIds)\n\n      // Page edges + center\n      vertical.push({ position: 0, kind: 'page-edge' })\n      vertical.push({ position: page.width, kind: 'page-edge' })\n      vertical.push({ position: page.width / 2, kind: 'page-center' })\n      horizontal.push({ position: 0, kind: 'page-edge' })\n      horizontal.push({ position: page.height, kind: 'page-edge' })\n      horizontal.push({ position: page.height / 2, kind: 'page-center' })\n\n      // Saved ruler guides\n      for (const pos of page.guides.vertical) {\n        vertical.push({ position: pos, kind: 'guide' })\n      }\n      for (const pos of page.guides.horizontal) {\n        horizontal.push({ position: pos, kind: 'guide' })\n      }\n\n      // Element edges + centers (visible, unlocked, not excluded)\n      collectElementTargets(page.elements, excludeSet, vertical, horizontal)\n\n      // Grid lines (deferred to apply() with the moving bounds neighborhood)\n      // Grid targets are injected by collectGridTargets() when gridEnabled.\n\n      return { vertical, horizontal }\n    },\n\n    apply(bounds: Bounds, targets: SnapTargets, thresholdPx: number, zoom: number): SnapResult {\n      if (!Number.isFinite(zoom) || zoom <= 0) {\n        throw new Error(`snap.apply: zoom must be a positive finite number, got ${zoom}`)\n      }\n      if (!Number.isFinite(thresholdPx) || thresholdPx < 0) {\n        throw new Error(`snap.apply: thresholdPx must be a non-negative finite number, got ${thresholdPx}`)\n      }\n      const threshold = thresholdPx / zoom\n\n      const snappedX = snapAxis(bounds.x, bounds.x + bounds.width / 2, bounds.x + bounds.width, targets.vertical, threshold)\n      const snappedY = snapAxis(bounds.y, bounds.y + bounds.height / 2, bounds.y + bounds.height, targets.horizontal, threshold)\n\n      return {\n        x: snappedX !== null ? snappedX.docPosition - snappedX.elementOffset : bounds.x,\n        y: snappedY !== null ? snappedY.docPosition - snappedY.elementOffset : bounds.y,\n        activeVertical: snappedX !== null ? snappedX.target : null,\n        activeHorizontal: snappedY !== null ? snappedY.target : null,\n      }\n    },\n  }\n}\n\n/** Generate grid line targets within a neighborhood around the moving bounds.\n *  Call this and append to `SnapTargets.vertical`/`horizontal` before\n *  passing to `apply()` when `state.gridEnabled`. */\nexport function collectGridTargets(\n  bounds: Bounds,\n  gridSize: number,\n  page: ScenePage,\n  thresholdDocPx: number,\n): { vertical: SnapTarget[]; horizontal: SnapTarget[] } {\n  if (!Number.isFinite(gridSize) || gridSize <= 0) {\n    throw new Error(`collectGridTargets: gridSize must be positive finite, got ${gridSize}`)\n  }\n  const vertical: SnapTarget[] = []\n  const horizontal: SnapTarget[] = []\n\n  // Generate lines that fall within the bounds + threshold neighborhood\n  const xMin = Math.floor((bounds.x - thresholdDocPx) / gridSize) * gridSize\n  const xMax = Math.ceil((bounds.x + bounds.width + thresholdDocPx) / gridSize) * gridSize\n  for (let x = xMin; x <= xMax; x += gridSize) {\n    if (x >= 0 && x <= page.width) vertical.push({ position: x, kind: 'grid' })\n  }\n\n  const yMin = Math.floor((bounds.y - thresholdDocPx) / gridSize) * gridSize\n  const yMax = Math.ceil((bounds.y + bounds.height + thresholdDocPx) / gridSize) * gridSize\n  for (let y = yMin; y <= yMax; y += gridSize) {\n    if (y >= 0 && y <= page.height) horizontal.push({ position: y, kind: 'grid' })\n  }\n\n  return { vertical, horizontal }\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\ninterface SnapHit {\n  /** The snap target that won. */\n  target: SnapTarget\n  /** The document-coordinate position of the snap line. */\n  docPosition: number\n  /** How far the element's reference point (left/center/right or top/mid/bottom)\n   *  is from the element's x/y origin — used to reconstruct the new origin. */\n  elementOffset: number\n}\n\n/** Try snapping each of the three reference points (start/center/end) to the\n *  nearest target. Returns the best hit across all three, or null. */\nfunction snapAxis(start: number, center: number, end: number, targets: SnapTarget[], threshold: number): SnapHit | null {\n  const candidates: Array<{ value: number; offset: number }> = [\n    { value: start, offset: 0 },\n    { value: center, offset: center - start },\n    { value: end, offset: end - start },\n  ]\n\n  let best: SnapHit | null = null\n  let bestDistance = Infinity\n  let bestPriority = Infinity\n\n  for (const { value, offset } of candidates) {\n    for (const target of targets) {\n      const distance = Math.abs(target.position - value)\n      if (distance > threshold) continue\n      const priority = KIND_PRIORITY[target.kind]\n      if (\n        distance < bestDistance ||\n        (distance === bestDistance && priority < bestPriority)\n      ) {\n        bestDistance = distance\n        bestPriority = priority\n        best = { target, docPosition: target.position, elementOffset: offset }\n      }\n    }\n  }\n\n  return best\n}\n\nfunction collectElementTargets(\n  elements: SceneElement[],\n  excludeIds: Set<string>,\n  vertical: SnapTarget[],\n  horizontal: SnapTarget[],\n): void {\n  for (const el of elements) {\n    if (!el.visible || el.locked) continue\n    if (excludeIds.has(el.id)) continue\n\n    const aabb = elementAabb(el)\n    // Left, center, right\n    vertical.push({ position: aabb.x, kind: 'element-edge' })\n    vertical.push({ position: aabb.x + aabb.width / 2, kind: 'element-center' })\n    vertical.push({ position: aabb.x + aabb.width, kind: 'element-edge' })\n    // Top, middle, bottom\n    horizontal.push({ position: aabb.y, kind: 'element-edge' })\n    horizontal.push({ position: aabb.y + aabb.height / 2, kind: 'element-center' })\n    horizontal.push({ position: aabb.y + aabb.height, kind: 'element-edge' })\n\n    if (el.kind === 'group') {\n      collectElementTargets(el.children, excludeIds, vertical, horizontal)\n    }\n  }\n}\n","/**\n * Selection math for the design-canvas editor: marquee hit-tests, keyboard\n * nudge deltas, and the duplicate offset constant. Pure functions — no DOM, no\n * Konva, no React.\n *\n * Marquee inclusion: by default any element whose AABB intersects the marquee\n * rect is included (the \"touch\" model). Pass `requireFullContainment: true` for\n * the \"surround\" model where the marquee must fully contain the element. Locked\n * and invisible elements are never selected regardless.\n */\n\nimport { boundsIntersect, elementAabb } from '../../design-canvas/model'\nimport type { Bounds, SceneElement, ScenePage } from '../../design-canvas/model'\n\n// ---------------------------------------------------------------------------\n// Point hit-test (model-space)\n// ---------------------------------------------------------------------------\n\n/**\n * Top-most selectable element whose AABB contains the document-space point, or\n * null when the point is over empty space.\n *\n * This is the authoritative \"is the pointer over an element?\" test for the\n * pointer-down gesture router. It runs against the scene model in document\n * coordinates rather than Konva's hit-graph canvas, so it is independent of\n * clip groups, listening flags, and hit-canvas redraw timing — all of which\n * could make `stage.getIntersection` misclassify a press as empty space and\n * silently start a marquee instead of an element drag.\n *\n * Z-order: later elements paint on top, so we scan the array in reverse and\n * return the first hit. Groups descend into children (top child wins); a hit on\n * a group child resolves to the group itself, matching drag/selection which\n * operate on the group as a unit. Locked and invisible elements never hit.\n */\nexport function hitTestPoint(page: ScenePage, x: number, y: number): string | null {\n  return hitTestIn(page.elements, x, y, null)\n}\n\nfunction hitTestIn(\n  elements: SceneElement[],\n  x: number,\n  y: number,\n  resolveTo: string | null,\n): string | null {\n  for (let i = elements.length - 1; i >= 0; i -= 1) {\n    const el = elements[i]!\n    if (!el.visible || el.locked) continue\n    const aabb = elementAabb(el)\n    if (!pointInBounds(aabb, x, y)) continue\n    if (el.kind === 'group') {\n      // A press anywhere inside the group AABB selects the group as a unit,\n      // even over the gaps between children — the group is the draggable node.\n      const child = hitTestIn(el.children, x, y, el.id)\n      return child ?? el.id\n    }\n    return resolveTo ?? el.id\n  }\n  return null\n}\n\nfunction pointInBounds(b: Bounds, x: number, y: number): boolean {\n  return x >= b.x && x <= b.x + b.width && y >= b.y && y <= b.y + b.height\n}\n\n/** Define options to configure marquee selection behavior including containment requirements */\nexport interface MarqueeSelectOptions {\n  /** When true, the element's AABB must be fully inside the marquee; default is\n   *  intersection (any overlap selects). */\n  requireFullContainment?: boolean\n}\n\n/** Returns the ids of selectable elements on `page` whose AABB intersects (or\n *  is contained by) `rect`. Locked and invisible elements are excluded. */\nexport function marqueeSelect(page: ScenePage, rect: Bounds, opts: MarqueeSelectOptions = {}): string[] {\n  assertValidBounds(rect, 'marqueeSelect rect')\n  const result: string[] = []\n  collectMarqueeIds(page.elements, rect, opts.requireFullContainment ?? false, result)\n  return result\n}\n\nfunction collectMarqueeIds(\n  elements: SceneElement[],\n  rect: Bounds,\n  requireContainment: boolean,\n  result: string[],\n): void {\n  for (const el of elements) {\n    if (!el.visible || el.locked) continue\n    const aabb = elementAabb(el)\n\n    if (el.kind === 'group') {\n      // Groups are transparent to marquee: descend when the group AABB intersects\n      // the rect, collecting children individually. The group entity itself is\n      // never added — marquee selects leaf elements, not the group wrapper.\n      if (boundsIntersect(rect, aabb)) {\n        collectMarqueeIds(el.children, rect, requireContainment, result)\n      }\n      continue\n    }\n\n    const hit = requireContainment ? boundsContain(rect, aabb) : boundsIntersect(rect, aabb)\n    if (hit) result.push(el.id)\n  }\n}\n\n/** Returns true when `outer` fully contains `inner` (edges may touch). */\nfunction boundsContain(outer: Bounds, inner: Bounds): boolean {\n  return (\n    inner.x >= outer.x &&\n    inner.y >= outer.y &&\n    inner.x + inner.width <= outer.x + outer.width &&\n    inner.y + inner.height <= outer.y + outer.height\n  )\n}\n\n// ---------------------------------------------------------------------------\n// Keyboard nudge\n// ---------------------------------------------------------------------------\n\n/** Pixels to move per nudge step at normal and shifted speed. */\nconst NUDGE_NORMAL_PX = 1\nconst NUDGE_SHIFT_PX = 10\n\n/** Represent horizontal and vertical displacement values for nudging elements */\nexport interface NudgeDelta {\n  dx: number\n  dy: number\n}\n\n/** Map an arrow key to a document-px delta. `shift` engages the 10× step.\n *  Throws on unknown keys so callers handle only real nudge keys. */\nexport function nudgeDelta(key: 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown', shift: boolean): NudgeDelta {\n  const step = shift ? NUDGE_SHIFT_PX : NUDGE_NORMAL_PX\n  switch (key) {\n    case 'ArrowLeft':  return { dx: -step, dy: 0 }\n    case 'ArrowRight': return { dx: step,  dy: 0 }\n    case 'ArrowUp':    return { dx: 0,     dy: -step }\n    case 'ArrowDown':  return { dx: 0,     dy: step }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Duplicate offset\n// ---------------------------------------------------------------------------\n\n/** Document-px offset applied to duplicated elements so the copy is visually\n *  separated from the original (matching common design-tool convention). */\nexport const DUPLICATE_OFFSET: NudgeDelta = { dx: 10, dy: 10 }\n\n// ---------------------------------------------------------------------------\n// Internal\n// ---------------------------------------------------------------------------\n\nfunction assertValidBounds(bounds: Bounds, label: string): void {\n  if (!Number.isFinite(bounds.x) || !Number.isFinite(bounds.y) ||\n      !Number.isFinite(bounds.width) || !Number.isFinite(bounds.height)) {\n    throw new Error(`${label}: all fields must be finite numbers`)\n  }\n}\n","/**\n * Zoom + pan coordinate math for the design-canvas editor. Zoom is pixels-per-\n * document-px (e.g. 2 = 200% magnification). The key invariant for wheel-zoom\n * is that the document point under the cursor stays fixed in screen space:\n *\n *   docPoint = (screenPoint - pan) / zoom\n *   newPan   = screenPoint - docPoint * newZoom\n *\n * This module is pure math — no DOM, no Konva, no React.\n */\n\nimport type { ZoomPanMath } from '../contracts'\n\n/** Define configuration options for minimum and maximum zoom levels in a zoom-pan interface */\nexport interface ZoomPanConfig {\n  minZoom: number\n  maxZoom: number\n}\n\n/** Create zoom and pan math utilities enforcing valid zoom range constraints */\nexport function createZoomPanMath(config: ZoomPanConfig): ZoomPanMath {\n  const { minZoom, maxZoom } = config\n  if (!Number.isFinite(minZoom) || minZoom <= 0) {\n    throw new Error(`minZoom must be a positive finite number, got ${minZoom}`)\n  }\n  if (!Number.isFinite(maxZoom) || maxZoom <= minZoom) {\n    throw new Error(`maxZoom must be finite and greater than minZoom (${minZoom}), got ${maxZoom}`)\n  }\n\n  return {\n    minZoom,\n    maxZoom,\n\n    zoomAtPoint(\n      state: { zoom: number; panX: number; panY: number },\n      factor: number,\n      screenX: number,\n      screenY: number,\n    ): { zoom: number; panX: number; panY: number } {\n      if (!Number.isFinite(factor) || factor <= 0) {\n        throw new Error(`zoomAtPoint: factor must be a positive finite number, got ${factor}`)\n      }\n      if (!Number.isFinite(screenX) || !Number.isFinite(screenY)) {\n        throw new Error(`zoomAtPoint: screenX/screenY must be finite numbers`)\n      }\n      if (!Number.isFinite(state.zoom) || state.zoom <= 0) {\n        throw new Error(`zoomAtPoint: state.zoom must be a positive finite number, got ${state.zoom}`)\n      }\n\n      const newZoom = Math.min(maxZoom, Math.max(minZoom, state.zoom * factor))\n\n      // The document point under the cursor must remain fixed:\n      //   docX = (screenX - panX) / zoom\n      //   newPanX = screenX - docX * newZoom\n      const docX = (screenX - state.panX) / state.zoom\n      const docY = (screenY - state.panY) / state.zoom\n      const panX = screenX - docX * newZoom\n      const panY = screenY - docY * newZoom\n\n      return { zoom: newZoom, panX, panY }\n    },\n\n    fitPage(\n      page: { width: number; height: number },\n      viewport: { width: number; height: number },\n      paddingPx = 48,\n    ): { zoom: number; panX: number; panY: number } {\n      if (!Number.isFinite(page.width) || page.width <= 0) {\n        throw new Error(`fitPage: page.width must be a positive finite number, got ${page.width}`)\n      }\n      if (!Number.isFinite(page.height) || page.height <= 0) {\n        throw new Error(`fitPage: page.height must be a positive finite number, got ${page.height}`)\n      }\n      if (!Number.isFinite(viewport.width) || viewport.width <= 0) {\n        throw new Error(`fitPage: viewport.width must be a positive finite number, got ${viewport.width}`)\n      }\n      if (!Number.isFinite(viewport.height) || viewport.height <= 0) {\n        throw new Error(`fitPage: viewport.height must be a positive finite number, got ${viewport.height}`)\n      }\n      if (!Number.isFinite(paddingPx) || paddingPx < 0) {\n        throw new Error(`fitPage: paddingPx must be a non-negative finite number, got ${paddingPx}`)\n      }\n\n      const availW = viewport.width - paddingPx * 2\n      const availH = viewport.height - paddingPx * 2\n      const zoom = Math.min(maxZoom, Math.max(minZoom, Math.min(availW / page.width, availH / page.height)))\n\n      // Center the page in the viewport\n      const panX = (viewport.width - page.width * zoom) / 2\n      const panY = (viewport.height - page.height * zoom) / 2\n\n      return { zoom, panX, panY }\n    },\n\n    documentToScreen(\n      state: { zoom: number; panX: number; panY: number },\n      x: number,\n      y: number,\n    ): { x: number; y: number } {\n      return { x: x * state.zoom + state.panX, y: y * state.zoom + state.panY }\n    },\n\n    screenToDocument(\n      state: { zoom: number; panX: number; panY: number },\n      x: number,\n      y: number,\n    ): { x: number; y: number } {\n      if (!Number.isFinite(state.zoom) || state.zoom === 0) {\n        throw new Error(`screenToDocument: zoom must be a non-zero finite number, got ${state.zoom}`)\n      }\n      return { x: (x - state.panX) / state.zoom, y: (y - state.panY) / state.zoom }\n    },\n  }\n}\n","/**\n * Pure export math for the design-canvas surface — no Konva, no DOM, no React.\n *\n * All stage-interaction code (save/restore, node visibility, toDataURL) lives\n * in export.ts and delegates the decision math here so it can be tested\n * without a canvas environment.\n */\n\nimport type { ScenePage } from '../design-canvas/model'\nimport {\n  bleedAwareExportBounds,\n  scaleForPreset,\n  type ExportCropRect,\n  type ExportPreset,\n} from '../design-canvas/export-presets'\n\n// ---------------------------------------------------------------------------\n// Re-exports so callers only import from one place\n// ---------------------------------------------------------------------------\n\nexport type { ExportCropRect, ExportPreset }\nexport { bleedAwareExportBounds, scaleForPreset }\n\n// ---------------------------------------------------------------------------\n// Overlay / transformer node name predicates\n// ---------------------------------------------------------------------------\n\n/** Returns true for any Konva node that must be hidden during export. Nodes\n *  whose names start with 'overlay:' are editor-only chrome (snap lines,\n *  selection indicators, rulers, bleed guides). The transformer node is\n *  identified by its canonical name 'Transformer'. */\nexport function isExportHiddenNodeName(name: string): boolean {\n  return name.startsWith('overlay:') || name === 'Transformer'\n}\n\n// ---------------------------------------------------------------------------\n// Crop rect + pixel ratio resolution\n// ---------------------------------------------------------------------------\n\n/** Define parameters required to resolve export settings including crop, pixel ratio, type, and quality */\nexport interface ResolvedExportParams {\n  cropRect: ExportCropRect\n  pixelRatio: number\n  mimeType: 'image/png' | 'image/jpeg'\n  quality: number | undefined\n}\n\n/**\n * Resolve the full set of toDataURL params from a page, format, pixel ratio,\n * bleed flag, and optional preset. When a preset is supplied it overrides\n * `pixelRatio` and `includeBleed` — the explicit args are ignored for those\n * two values so the preset is the single source of truth.\n *\n * `quality` is set to 0.92 for jpeg, undefined for png (Konva ignores it).\n */\nexport function resolveExportParams(\n  page: ScenePage,\n  opts: {\n    format: 'png' | 'jpeg'\n    pixelRatio?: number\n    includeBleed?: boolean\n    preset?: ExportPreset\n  },\n): ResolvedExportParams {\n  const includeBleed = opts.preset !== undefined\n    ? opts.preset.includeBleed\n    : (opts.includeBleed ?? false)\n\n  const cropRect = bleedAwareExportBounds(page, includeBleed)\n\n  const pixelRatio = opts.preset !== undefined\n    ? scaleForPreset(opts.preset, cropRect)\n    : (opts.pixelRatio ?? 1)\n\n  const format = opts.preset !== undefined ? opts.preset.format : opts.format\n  const mimeType: 'image/png' | 'image/jpeg' = format === 'jpeg' ? 'image/jpeg' : 'image/png'\n\n  return {\n    cropRect,\n    pixelRatio,\n    mimeType,\n    quality: format === 'jpeg' ? 0.92 : undefined,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// CORS taint detection\n// ---------------------------------------------------------------------------\n\n/**\n * Walk image nodes to find the src of any that may have caused a SecurityError\n * when the stage called toDataURL. Returns the first offending src found, or\n * null if none can be identified.\n *\n * `imageSrcs` is a flat list of { name, src } records collected from all image\n * nodes on the stage before calling toDataURL — export.ts builds it before\n * attempting the export so that if the SecurityError fires we have the data.\n */\nexport function identifyTaintedSrc(imageSrcs: ReadonlyArray<{ name: string; src: string }>): string | null {\n  // We cannot re-probe CORS from a caught SecurityError — the browser does not\n  // tell us which src triggered it. Return the first src that looks like a\n  // cross-origin resource the browser would taint: anything that is not a\n  // same-origin relative path or a data: URL.\n  for (const { src } of imageSrcs) {\n    if (isCrossOriginSrc(src)) return src\n  }\n  return null\n}\n\n/**\n * Heuristic: a src is potentially cross-origin when it is an absolute http(s)\n * URL. Same-origin relative paths (/api/...) and data: blobs are safe.\n * This is intentionally conservative — the taint check runs only after a\n * SecurityError fires, so a false positive is \"blamed\" without being silently\n * ignored. NOTE: same-origin https:// assets will also match; if a\n * SecurityError fires, the cross-origin culprit may be a different image than\n * the one this function flags first.\n */\nexport function isCrossOriginSrc(src: string): boolean {\n  return /^https?:\\/\\//i.test(src)\n}\n\n// ---------------------------------------------------------------------------\n// View state snapshot (used by save/restore helpers)\n// ---------------------------------------------------------------------------\n\n/** Minimal snapshot of stage view state that export.ts saves before mutating\n *  zoom/pan/visibility and restores afterward. */\nexport interface ExportViewSnapshot {\n  /** Stage scale factor before export. */\n  scaleX: number\n  scaleY: number\n  /** Stage translation before export. */\n  x: number\n  y: number\n  /** node name → prior visibility, for the nodes that were hidden. */\n  hiddenNodeNames: string[]\n}\n\n/**\n * Build the toDataURL crop rect translated to stage output coordinates.\n * Konva's `stage.toDataURL({ x, y, width, height })` takes STAGE OUTPUT\n * coordinates, not document coordinates. When the stage has been scaled to fit\n * (zoom × stageScale), the crop rect in document px must be multiplied by the\n * combined scale to land on the right pixels.\n *\n * `stageScale` is the stage's current uniform scale (scaleX == scaleY);\n * `pixelRatio` is separate and handed directly to toDataURL — Konva multiplies\n * it internally when rendering to the backing canvas, so we must NOT include\n * it in the stage-coordinate rect.\n */\nexport function documentCropToStageCoords(\n  cropRect: ExportCropRect,\n  stageScale: number,\n  stageX: number,\n  stageY: number,\n): { x: number; y: number; width: number; height: number } {\n  return {\n    x: stageX + cropRect.x * stageScale,\n    y: stageY + cropRect.y * stageScale,\n    width: cropRect.width * stageScale,\n    height: cropRect.height * stageScale,\n  }\n}\n","/**\n * Pure builders for the human \"add element to the canvas\" path — the math and\n * `SceneOperation` construction behind {@link CanvasInsertPanel}, separated from\n * the React/DOM layer so every insert is unit-testable without Konva or a\n * browser. The panel calls these to produce `add_element` operations and hands\n * them to the host's `onApplyOperations` (server-validated, undoable) — the same\n * pipeline every other edit flows through.\n *\n * Media boundary: image inserts must pass {@link assertSceneMediaSrc} (remote\n * http(s) or a rooted `/api/` path — never `data:` blobs or sandbox-local\n * files). Builders that take a src assert it up front so a bad url fails here,\n * not deep in the apply layer.\n */\n\nimport { assertSceneMediaSrc } from '../design-canvas/model'\nimport type {\n  EllipseElement,\n  ImageElement,\n  RectElement,\n  SceneElement,\n  TextElement,\n} from '../design-canvas/model'\nimport type { SceneOperation } from '../design-canvas/operations'\n\n/** Largest dimension (document px) a freshly inserted element is fitted to,\n *  before the page-size cap applies. Keeps a huge upload from filling the page. */\nexport const MAX_INSERT_DIMENSION = 600\n\n/** Active page geometry an insert lands into — drives centering and fitting. */\nexport interface InsertPageGeometry {\n  pageId: string\n  width: number\n  height: number\n  background?: string\n}\n\n/** Mint a DOM-safe element id. Prefers `crypto.randomUUID`; falls back to a\n *  time+random id where crypto is unavailable (older runtimes, some test envs). */\nexport function mintElementId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {\n    return crypto.randomUUID()\n  }\n  return `el-${Date.now()}-${Math.random().toString(36).slice(2)}`\n}\n\n/** Fit (naturalW, naturalH) under a max-dimension cap (further bounded by the\n *  page), preserving aspect ratio. Never upscales past natural size. */\nexport function fittedSize(\n  naturalW: number,\n  naturalH: number,\n  pageWidth: number,\n  pageHeight: number,\n): { width: number; height: number } {\n  const cap = Math.min(MAX_INSERT_DIMENSION, pageWidth * 0.8, pageHeight * 0.8)\n  const longest = Math.max(naturalW, naturalH)\n  const scale = naturalW > 0 && naturalH > 0 ? Math.min(1, cap / longest) : 1\n  const width = Math.max(1, Math.round((naturalW || cap) * scale))\n  const height = Math.max(1, Math.round((naturalH || cap) * scale))\n  return { width, height }\n}\n\n/** Top-left position that centers a (width, height) box on the page. */\nexport function centeredPosition(\n  width: number,\n  height: number,\n  pageWidth: number,\n  pageHeight: number,\n): { x: number; y: number } {\n  return {\n    x: Math.round((pageWidth - width) / 2),\n    y: Math.round((pageHeight - height) / 2),\n  }\n}\n\n/** Common element fields with a freshly minted id and unrotated/visible defaults. */\nfunction baseAttrs(name: string, x: number, y: number) {\n  return { id: mintElementId(), name, x, y, rotation: 0, opacity: 1, locked: false, visible: true }\n}\n\n/** Wrap a single element in an `add_element` op for the active page. */\nfunction addElementOp(pageId: string, element: SceneElement): SceneOperation {\n  return { type: 'add_element', pageId, element }\n}\n\nfunction hexLuminance(color: string | undefined): number | null {\n  if (!color) return null\n  const raw = color.trim()\n  const hex = raw.startsWith('#') ? raw.slice(1) : ''\n  const full = hex.length === 3\n    ? hex.split('').map((ch) => ch + ch).join('')\n    : hex.length === 6\n      ? hex\n      : ''\n  if (!/^[0-9a-fA-F]{6}$/.test(full)) return null\n  const channels = [0, 2, 4].map((start) => parseInt(full.slice(start, start + 2), 16) / 255)\n  const [r, g, b] = channels.map((value) => (\n    value <= 0.03928 ? value / 12.92 : Math.pow((value + 0.055) / 1.055, 2.4)\n  ))\n  return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!\n}\n\nfunction pageTextFill(page: InsertPageGeometry, tone: 'primary' | 'secondary'): string {\n  const luminance = hexLuminance(page.background)\n  if (luminance !== null && luminance < 0.35) {\n    return tone === 'primary' ? '#f8fafc' : '#cbd5e1'\n  }\n  return tone === 'primary' ? '#111827' : '#374151'\n}\n\n/**\n * Build an `add_element` op placing an image, fitted and centered on the page.\n * `naturalSize` is the probed image dimensions (the panel reads them in the\n * browser); pass `{ width: 0, height: 0 }` when unknown to fall back to the cap.\n *\n * Throws (via `assertSceneMediaSrc`) when `src` is not http(s) or a rooted\n * `/api/` path — callers should surface the error, never insert a `data:` src.\n */\nexport function buildInsertImageOp(\n  src: string,\n  naturalSize: { width: number; height: number },\n  page: InsertPageGeometry,\n): SceneOperation {\n  assertSceneMediaSrc(src, 'image src')\n  const { width, height } = fittedSize(naturalSize.width, naturalSize.height, page.width, page.height)\n  const { x, y } = centeredPosition(width, height, page.width, page.height)\n  const element: ImageElement = {\n    ...baseAttrs('Image', x, y),\n    kind: 'image',\n    width,\n    height,\n    src,\n    fit: 'contain',\n  }\n  return addElementOp(page.pageId, element)\n}\n\n/** A template the insert panel can drop without the agent. `build` is pure and\n *  produces the operations for the active page geometry. */\nexport interface InsertTemplate {\n  id: string\n  label: string\n  build(page: InsertPageGeometry): SceneOperation[]\n}\n\n/** The built-in starter templates (heading, body text, rectangle, ellipse).\n *  Consumers can pass their own list to {@link CanvasInsertPanel}; this is the\n *  default so every canvas gets a usable set out of the box. */\nexport const DEFAULT_INSERT_TEMPLATES: readonly InsertTemplate[] = [\n  {\n    id: 'heading',\n    label: 'Heading',\n    build(page) {\n      const width = Math.min(480, Math.round(page.width * 0.7))\n      const { x, y } = centeredPosition(width, 60, page.width, page.height)\n      const element: TextElement = {\n        ...baseAttrs('Heading', x, y),\n        kind: 'text',\n        text: 'Add a headline',\n        width,\n        fontFamily: 'Inter',\n        fontSize: 48,\n        fontStyle: 'bold',\n        fill: pageTextFill(page, 'primary'),\n        align: 'left',\n        lineHeight: 1.1,\n        letterSpacing: 0,\n      }\n      return [addElementOp(page.pageId, element)]\n    },\n  },\n  {\n    id: 'body',\n    label: 'Body text',\n    build(page) {\n      const width = Math.min(420, Math.round(page.width * 0.6))\n      const { x, y } = centeredPosition(width, 80, page.width, page.height)\n      const element: TextElement = {\n        ...baseAttrs('Body', x, y),\n        kind: 'text',\n        text: 'Add a paragraph of supporting copy.',\n        width,\n        fontFamily: 'Inter',\n        fontSize: 20,\n        fontStyle: 'normal',\n        fill: pageTextFill(page, 'secondary'),\n        align: 'left',\n        lineHeight: 1.4,\n        letterSpacing: 0,\n      }\n      return [addElementOp(page.pageId, element)]\n    },\n  },\n  {\n    id: 'rect',\n    label: 'Rectangle',\n    build(page) {\n      const width = Math.min(320, Math.round(page.width * 0.4))\n      const height = Math.min(200, Math.round(page.height * 0.3))\n      const { x, y } = centeredPosition(width, height, page.width, page.height)\n      const element: RectElement = {\n        ...baseAttrs('Rectangle', x, y),\n        kind: 'rect',\n        width,\n        height,\n        fill: '#6366f1',\n        cornerRadius: 12,\n      }\n      return [addElementOp(page.pageId, element)]\n    },\n  },\n  {\n    id: 'ellipse',\n    label: 'Ellipse',\n    build(page) {\n      const size = Math.min(220, Math.round(Math.min(page.width, page.height) * 0.3))\n      const { x, y } = centeredPosition(size, size, page.width, page.height)\n      const element: EllipseElement = {\n        ...baseAttrs('Ellipse', x, y),\n        kind: 'ellipse',\n        width: size,\n        height: size,\n        fill: '#10b981',\n      }\n      return [addElementOp(page.pageId, element)]\n    },\n  },\n]\n"],"mappings":"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","names":[]}

package/dist/{chunk-SIXYZ2FB.js → chunk-YJMCRXQQ.js}

@@ -98,4 +98,4 @@ export {
   persistedPartToPlan,
   parsePlanSubmittedEvent
 };
-//# sourceMappingURL=chunk-SIXYZ2FB.js.map
+//# sourceMappingURL=chunk-YJMCRXQQ.js.map

package/dist/chunk-YJMCRXQQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plans/index.ts"],"sourcesContent":["/**\n * Durable-plan application-shell contract.\n *\n * The sandbox SDK owns the authoritative plan lifecycle and decision APIs.\n * This module only projects that substrate state into chat events and\n * persisted message parts that products can render and restore.\n */\n\nexport const PLAN_SUBMITTED_EVENT = 'plan.submitted' as const\n\n/** Sandbox plan lifecycle. `preparing` is the transient submission state and\n * is retained in the projection even though the chat card normally starts at\n * `pending`. */\nexport type ChatPlanStatus = 'preparing' | 'pending' | 'approved' | 'rejected' | 'superseded' | 'withdrawn'\n\ntype ChatPlanBase = {\n  /** The sandbox SDK calls this field `id`; the transcript projection names\n   * it explicitly so it cannot collide with a message-part id. */\n  planId: string\n  revision: number\n  title?: string\n  body: string\n  submittedAt: string\n  /** Provider/Sandbox metadata is deliberately opaque to this package. */\n  metadata?: Record<string, unknown>\n  decidedBy?: string\n}\n\n/** Browser/persisted projection of the sandbox SDK's durable-plan union. */\nexport type ChatPlan = ChatPlanBase & (\n  | { status: 'preparing' }\n  | { status: 'pending' }\n  | { status: 'approved'; decidedAt: string }\n  | { status: 'rejected'; decidedAt: string; feedback: string }\n  | { status: 'superseded'; supersededAt: string; supersededByPlanId: string }\n  | { status: 'withdrawn'; withdrawnAt: string; withdrawnReason: string }\n)\n\n/** Canonical transcript part for one durable plan. */\nexport type ChatPlanPersistedPart = ChatPlan & { type: 'plan' }\n\n/** Resolve the result of parsing a plan submission into success with value or failure with error */\nexport type ParsePlanSubmittedResult =\n  | { succeeded: true; value: ChatPlan }\n  | { succeeded: false; error: string }\n\nconst PLAN_STATUSES: ReadonlySet<string> = new Set([\n  'preparing',\n  'pending',\n  'approved',\n  'rejected',\n  'superseded',\n  'withdrawn',\n])\n\nfunction asRecord(value: unknown): Record<string, unknown> | null {\n  return value && typeof value === 'object' && !Array.isArray(value)\n    ? value as Record<string, unknown>\n    : null\n}\n\nfunction requiredString(record: Record<string, unknown>, key: string): string | null {\n  const value = record[key]\n  return typeof value === 'string' && value ? value : null\n}\n\nfunction parsePlan(record: Record<string, unknown>, defaultStatus?: ChatPlanStatus): ChatPlan | null {\n  const planId = requiredString(record, 'planId') ?? requiredString(record, 'id')\n  const revision = record.revision\n  const body = requiredString(record, 'body')\n  const submittedAt = requiredString(record, 'submittedAt')\n  const status = typeof record.status === 'string' ? record.status : defaultStatus\n  if (\n    !planId ||\n    typeof revision !== 'number' ||\n    !Number.isInteger(revision) ||\n    revision < 1 ||\n    !body ||\n    !submittedAt ||\n    !status ||\n    !PLAN_STATUSES.has(status)\n  ) {\n    return null\n  }\n\n  const common = {\n    planId,\n    revision,\n    ...(typeof record.title === 'string' && record.title ? { title: record.title } : {}),\n    body,\n    submittedAt,\n    ...(record.metadata && typeof record.metadata === 'object' && !Array.isArray(record.metadata)\n      ? { metadata: record.metadata as Record<string, unknown> }\n      : {}),\n    ...(typeof record.decidedBy === 'string' && record.decidedBy ? { decidedBy: record.decidedBy } : {}),\n  }\n\n  if (status === 'preparing') return { ...common, status: 'preparing' }\n  if (status === 'pending') return { ...common, status: 'pending' }\n  if (status === 'approved') {\n    const decidedAt = requiredString(record, 'decidedAt')\n    return decidedAt ? { ...common, status, decidedAt } : null\n  }\n  if (status === 'rejected') {\n    const decidedAt = requiredString(record, 'decidedAt')\n    const feedback = requiredString(record, 'feedback')\n    return decidedAt && feedback ? { ...common, status, decidedAt, feedback } : null\n  }\n  if (status === 'superseded') {\n    const supersededAt = requiredString(record, 'supersededAt')\n    const supersededByPlanId = requiredString(record, 'supersededByPlanId')\n    return supersededAt && supersededByPlanId\n      ? { ...common, status, supersededAt, supersededByPlanId }\n      : null\n  }\n\n  const withdrawnAt = requiredString(record, 'withdrawnAt')\n  const withdrawnReason = requiredString(record, 'withdrawnReason') ?? requiredString(record, 'reason')\n  return withdrawnAt && withdrawnReason\n    ? { ...common, status: 'withdrawn', withdrawnAt, withdrawnReason }\n    : null\n}\n\n/** Generate a unique key string for a given plan identifier */\nexport function planPartKey(planId: string): string {\n  return `plan:${planId}`\n}\n\n/** Generate a unique key string for a plan based on its ID and revision number */\nexport function planRevisionKey(planId: string, revision: number): string {\n  return `plan:${planId}:revision:${revision}`\n}\n\n/** Generate a unique follow-up turn ID based on the plan ID and its outcome */\nexport function planFollowUpTurnId(planId: string, outcome: 'approved' | 'rejected'): string {\n  return `plan:${planId}:${outcome}`\n}\n\n/** Plan status is monotonic: only a pending plan can settle. */\nexport function canTransitionPlanStatus(from: ChatPlanStatus, to: ChatPlanStatus): boolean {\n  if (from === to) return true\n  if (from === 'preparing') return to === 'pending' || to === 'superseded' || to === 'withdrawn'\n  if (from === 'pending') return to === 'approved' || to === 'rejected' || to === 'superseded' || to === 'withdrawn'\n  return false\n}\n\n/** Resolve a ChatPlan into its persisted part representation for storage or transmission */\nexport function planToPersistedPart(plan: ChatPlan): ChatPlanPersistedPart {\n  return { type: 'plan', ...plan }\n}\n\n/** Resolve a persisted part object into a ChatPlan or return null if the type is not 'plan */\nexport function persistedPartToPlan(part: Record<string, unknown>): ChatPlan | null {\n  if (String(part.type ?? '') !== 'plan') return null\n  return parsePlan(part)\n}\n\n/** Parses both direct sandbox events (`data.plan`) and session envelopes\n * (`properties.plan`). Session identity is carried by the surrounding stream\n * and is deliberately not required in the payload. */\nexport function parsePlanSubmittedEvent(event: unknown): ParsePlanSubmittedResult {\n  const root = asRecord(event)\n  if (!root || root.type !== PLAN_SUBMITTED_EVENT) {\n    return { succeeded: false, error: 'event is not plan.submitted' }\n  }\n  const plan = asRecord(asRecord(root.properties)?.plan) ?? asRecord(asRecord(root.data)?.plan)\n  if (!plan) {\n    return { succeeded: false, error: 'plan.submitted event carried no plan' }\n  }\n  const parsed = parsePlan(plan, 'pending')\n  return parsed\n    ? { succeeded: true, value: parsed }\n    : { succeeded: false, error: 'plan.submitted event carried a malformed plan' }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-PJC4NXPA.js → chunk-YKBDH2UY.js}

@@ -1,6 +1,6 @@
 import {
   authenticateToolRequest
-} from "./chunk-7EVZUIHW.js";
+} from "./chunk-3EJ6SFJI.js";
 import {
   base64UrlDecodeText,
   base64UrlEncodeText,
@@ -10,7 +10,7 @@ import {
 import {
   dispatchAppTool,
   outcomeStatus
-} from "./chunk-MFRCM32T.js";
+} from "./chunk-7CTIUCQ4.js";
 
 // src/tools/capability.ts
 async function createCapabilityToken(userId, opts) {
@@ -126,4 +126,4 @@ export {
   restrictTaxonomy,
   handleAppToolRequest
 };
-//# sourceMappingURL=chunk-PJC4NXPA.js.map
+//# sourceMappingURL=chunk-YKBDH2UY.js.map

package/dist/chunk-YKBDH2UY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tools/capability.ts","../src/tools/gating.ts","../src/tools/http.ts"],"sourcesContent":["/**\n * Per-user capability token — the sandbox→app auth primitive behind the\n * `verifyToken` seam in {@link authenticateToolRequest}.\n *\n * An app-agent runs inside the sandbox and reaches the host app back over HTTP\n * (the app tools, the integration-invoke bridge). The route must act AS the\n * connecting user without trusting any model-supplied identity, so the turn\n * mints a short HMAC token bound to the user id and bakes it into the per-turn\n * MCP server header; the route verifies it to recover the user.\n *\n * `HMAC-SHA256(secret, \"user:<userId>\")`, base64url, with an app-chosen prefix.\n * The token encodes no scopes — the hub's policy engine authorizes per action.\n * Fail-closed: with no secret, no token is minted (the caller MUST omit the MCP\n * server rather than fake an authorized call). WebCrypto only — runs on\n * Workers, Node, and the browser with no Node `crypto` dependency.\n */\n\nimport {\n  base64UrlDecodeText,\n  base64UrlEncodeText,\n  constantTimeEqual,\n  hmacSha256Base64Url,\n} from '../crypto/web-token'\n\n/** Define options for creating and verifying capability tokens including secret and prefix */\nexport interface CapabilityTokenOptions {\n  /** Shared HMAC secret. When absent, mint returns undefined / verify returns false. */\n  secret?: string\n  /** Token prefix (namespaces the credential; lets verify reject foreign tokens\n   *  cheaply). Default `cap_`. */\n  prefix?: string\n}\n\n/** Mint a capability token for `userId`, or `undefined` when no secret is\n *  configured (fail-closed — the caller omits the MCP server rather than fake it). */\nexport async function createCapabilityToken(userId: string, opts: CapabilityTokenOptions): Promise<string | undefined> {\n  const secret = opts.secret?.trim()\n  if (!secret) return undefined\n  const prefix = opts.prefix ?? 'cap_'\n  return `${prefix}${await sign(userId, secret)}`\n}\n\n/** Verify a capability token against `userId`. Returns false (never throws) for\n *  an unconfigured secret, a wrong prefix, a malformed token, or a mismatch. */\nexport async function verifyCapabilityToken(userId: string, token: string, opts: CapabilityTokenOptions): Promise<boolean> {\n  const secret = opts.secret?.trim()\n  const prefix = opts.prefix ?? 'cap_'\n  if (!secret || !token.startsWith(prefix)) return false\n  const expected = `${prefix}${await sign(userId, secret)}`\n  return constantTimeEqual(token, expected)\n}\n\n/** Define options for capability tokens that expire after a specified lifetime in milliseconds */\nexport interface ExpiringCapabilityTokenOptions extends CapabilityTokenOptions {\n  /** Token lifetime. Expired tokens verify false regardless of signature. */\n  expiresInMs: number\n  /** Clock injection for tests; defaults to Date.now. */\n  now?: () => number\n}\n\n/**\n * Mint an EXPIRING capability token: `<prefix><base64url(payload)>.<sig>` where\n * the payload carries `{ sub, exp, n }` (subject, epoch-ms expiry, random\n * nonce) and the signature is HMAC-SHA256 over the encoded payload. Use this\n * for user-initiated scoped channels (e.g. a per-sequence MCP endpoint) where\n * a captured token must not stay valid past its window; the bare\n * {@link createCapabilityToken} remains for turn-scoped tool bridges whose\n * mint+verify happen inside one request cycle. Fail-closed like the bare\n * variant: no secret → no token.\n */\nexport async function createExpiringCapabilityToken(subject: string, opts: ExpiringCapabilityTokenOptions): Promise<string | undefined> {\n  const secret = opts.secret?.trim()\n  if (!secret) return undefined\n  if (!Number.isFinite(opts.expiresInMs) || opts.expiresInMs <= 0) throw new Error('expiresInMs must be a positive number')\n  const prefix = opts.prefix ?? 'cap_'\n  const now = opts.now ?? Date.now\n  const payload = base64UrlEncodeText(JSON.stringify({ sub: subject, exp: now() + opts.expiresInMs, n: crypto.randomUUID() }))\n  return `${prefix}${payload}.${await hmacSha256Base64Url(payload, secret)}`\n}\n\n/** Verify an expiring token against `subject`: prefix, payload integrity,\n *  subject match, and expiry all checked; returns false (never throws) on any\n *  failure including a malformed payload. */\nexport async function verifyExpiringCapabilityToken(subject: string, token: string, opts: CapabilityTokenOptions & { now?: () => number }): Promise<boolean> {\n  const secret = opts.secret?.trim()\n  const prefix = opts.prefix ?? 'cap_'\n  if (!secret || !token.startsWith(prefix)) return false\n  const body = token.slice(prefix.length)\n  const dot = body.lastIndexOf('.')\n  if (dot <= 0 || dot === body.length - 1) return false\n  const payload = body.slice(0, dot)\n  const sig = body.slice(dot + 1)\n  if (!constantTimeEqual(sig, await hmacSha256Base64Url(payload, secret))) return false\n  let parsed: { sub?: unknown; exp?: unknown }\n  try {\n    parsed = JSON.parse(base64UrlDecodeText(payload)) as { sub?: unknown; exp?: unknown }\n  } catch {\n    return false\n  }\n  if (parsed.sub !== subject) return false\n  if (typeof parsed.exp !== 'number') return false\n  const now = opts.now ?? Date.now\n  return parsed.exp > now()\n}\n\nasync function sign(userId: string, secret: string): Promise<string> {\n  return hmacSha256Base64Url(`user:${userId}`, secret)\n}\n","/**\n * Capability gating — compose an agent session's tool surface from a\n * product-defined capability registry.\n *\n * Products that let users pick what an agent can do (a \"Studio\" agent with the\n * full build toolset vs a clean \"Assistant\" with none) all need the same\n * mechanics: a registry of named capabilities, each unlocking proposal types\n * and/or named tool groups, resolved against the product's\n * {@link AppToolTaxonomy} into the concrete tools to expose. The mechanics are\n * generic and live here; the capability VOCABULARY (ids, labels, which\n * proposal types, which tool groups) is the product's.\n */\n\nimport type { AppToolTaxonomy } from './types'\n\n/** One toggleable tool group in a product's capability registry. */\nexport interface ToolCapability {\n  id: string\n  label: string\n  description: string\n  /** Proposal types this capability unlocks (intersected with the taxonomy,\n   *  so a capability can never widen the product's proposal surface). */\n  proposalTypes?: readonly string[]\n  /** Unlocks every taxonomy proposal type beyond the base set — the domain's\n   *  specialized long tail (risk_assessment, vuln_report, …). */\n  domainActions?: boolean\n  /** Named product tool groups (e.g. 'sandbox', 'integrations') this\n   *  capability unlocks. The vocabulary is the product's; the resolver only\n   *  unions them. */\n  toolGroups?: readonly string[]\n}\n\n/** Resolve options for determining tool capabilities based on taxonomy, capabilities, and enabled IDs */\nexport interface ResolveToolCapabilitiesOptions {\n  taxonomy: AppToolTaxonomy\n  /** The product's full capability registry. */\n  capabilities: readonly ToolCapability[]\n  /** Enabled capability ids. `undefined` means full access (legacy callers\n   *  that don't send a capability set); an explicit `[]` means a pure chat\n   *  agent with no tools. Unknown ids are ignored. */\n  enabled: readonly string[] | undefined\n  /** The shared base proposal types `domainActions` excludes. Defaults to\n   *  every type some capability names explicitly via `proposalTypes` — i.e.\n   *  \"domain actions\" are the taxonomy types no capability claims. */\n  baseProposalTypes?: readonly string[]\n}\n\n/** Describe resolved capabilities including proposal types and product tool groups to expose */\nexport interface ResolvedToolCapabilities {\n  /** Proposal types to keep — feed to {@link restrictTaxonomy}. */\n  proposalTypes: string[]\n  /** Product tool groups to expose (deduped union across enabled caps). */\n  toolGroups: string[]\n}\n\n/**\n * Resolve an enabled capability-id set against a taxonomy into the concrete\n * tool surface. Fail-closed: only types present in the taxonomy survive, and\n * an empty `enabled` set yields no tools at all.\n */\nexport function resolveToolCapabilities(\n  opts: ResolveToolCapabilitiesOptions,\n): ResolvedToolCapabilities {\n  const { taxonomy, capabilities, enabled } = opts\n  if (enabled === undefined) {\n    return {\n      proposalTypes: [...taxonomy.proposalTypes],\n      toolGroups: [...new Set(capabilities.flatMap((c) => c.toolGroups ?? []))],\n    }\n  }\n  const base = new Set(\n    opts.baseProposalTypes ?? capabilities.flatMap((c) => c.proposalTypes ?? []),\n  )\n  const domainTypes = taxonomy.proposalTypes.filter((t) => !base.has(t))\n  const byId = new Map(capabilities.map((c) => [c.id, c]))\n\n  const proposalTypes = new Set<string>()\n  const toolGroups = new Set<string>()\n  for (const id of enabled) {\n    const cap = byId.get(id)\n    if (!cap) continue\n    for (const t of cap.proposalTypes ?? []) {\n      if (taxonomy.proposalTypes.includes(t)) proposalTypes.add(t)\n    }\n    if (cap.domainActions) for (const t of domainTypes) proposalTypes.add(t)\n    for (const g of cap.toolGroups ?? []) toolGroups.add(g)\n  }\n  return { proposalTypes: [...proposalTypes], toolGroups: [...toolGroups] }\n}\n\n/**\n * Restrict a taxonomy to a subset of proposal types, intersecting the\n * regulated subset too — the regulated label survives restriction, so a\n * narrowed agent can never launder a regulated type into an unregulated one.\n */\nexport function restrictTaxonomy(\n  taxonomy: AppToolTaxonomy,\n  allowed: readonly string[],\n): AppToolTaxonomy {\n  const allow = new Set(allowed)\n  return {\n    proposalTypes: taxonomy.proposalTypes.filter((t) => allow.has(t)),\n    regulatedTypes: taxonomy.regulatedTypes.filter((t) => allow.has(t)),\n  }\n}\n","import { authenticateToolRequest, type ToolHeaderNames } from './auth'\nimport { dispatchAppTool, outcomeStatus, type DispatchOptions } from './dispatch'\nimport type { AppToolName } from './openai'\nimport type { AppToolDefinition } from './registry'\n\n/** Define options for handling tool requests including tool identification and token verification */\nexport interface HandleToolRequestOptions extends DispatchOptions {\n  /** Which app tool this route serves — a built-in name or a product-registered\n   *  {@link AppToolDefinition} (auto-added to `customTools` for dispatch). */\n  tool: AppToolName | AppToolDefinition\n  /** Verify the bearer capability token belongs to the header user. */\n  verifyToken: (userId: string, bearer: string) => Promise<boolean>\n  headerNames?: ToolHeaderNames\n  /** Optional success-message builder for a friendlier tool result. */\n  message?: (result: unknown) => string\n}\n\n/**\n * Handle one app-tool HTTP request end to end — the sandbox MCP path. The\n * agent's per-turn HTTP MCP server POSTs here; this authenticates (header user\n * + capability token), reads the args (MCP-alias tolerant), dispatches to the\n * product handler, and returns a JSON Response. A product's route file becomes\n * a one-liner: `export const action = ({ request }) => handleAppToolRequest(request, cfg)`.\n */\nexport async function handleAppToolRequest(request: Request, opts: HandleToolRequestOptions): Promise<Response> {\n  if (request.method !== 'POST') return Response.json({ error: 'Method not allowed' }, { status: 405 })\n\n  const auth = await authenticateToolRequest(request, { verifyToken: opts.verifyToken, headerNames: opts.headerNames })\n  if (!auth.ok) return auth.response\n\n  let body: { args?: Record<string, unknown>; arguments?: Record<string, unknown> } & Record<string, unknown>\n  try {\n    body = (await request.json()) as typeof body\n  } catch {\n    return Response.json({ error: 'Invalid JSON' }, { status: 400 })\n  }\n  const args = (body.args ?? body.arguments ?? body) as Record<string, unknown>\n\n  // A custom tool passed as `tool` is registered for this dispatch so the route\n  // file stays a one-liner (no separate customTools wiring needed).\n  const toolName = typeof opts.tool === 'string' ? opts.tool : opts.tool.name\n  const customTools =\n    typeof opts.tool === 'string' ? opts.customTools : [...(opts.customTools ?? []), opts.tool]\n  const outcome = await dispatchAppTool(toolName, args, auth.ctx, { ...opts, customTools })\n  if (!outcome.ok) {\n    return Response.json({ error: outcome.code, message: outcome.message }, { status: outcomeStatus(outcome) })\n  }\n  const payload = outcome.result as Record<string, unknown>\n  return Response.json({ ok: true, ...payload, ...(opts.message ? { message: opts.message(outcome.result) } : {}) })\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-XAWFPMAR.js → chunk-YKOM4ZLQ.js}

@@ -195,4 +195,4 @@ export {
   stampInteractionAnswers,
   persistedPartToInteraction
 };
-//# sourceMappingURL=chunk-XAWFPMAR.js.map
+//# sourceMappingURL=chunk-YKOM4ZLQ.js.map

package/dist/chunk-YKOM4ZLQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/interactions/contract.ts"],"sourcesContent":["// Shared contract for agent interaction events (kind: \"question\" et al) — the\n// generalized human-in-the-loop primitive on the chat stream. Framework-agnostic\n// (no server- or React-only imports) so a producer (chat route) and a consumer\n// (stream parser, transcript, question card) agree on one wire shape and one\n// persisted-part shape.\n//\n// An `interaction` event means the run is BLOCKED inside the sidecar's\n// InteractionBroker until the user answers, the agent withdraws the ask\n// (`interaction.cancel`), or the broker times out. A pending interaction is\n// \"waiting on the user\", not \"model working\".\n\nimport {\n  InteractionRequestSchema,\n  type InteractionData,\n  type InteractionField,\n  type InteractionOutcome,\n  type InteractionRequest,\n} from '@tangle-network/agent-interface'\n\nexport type { InteractionData, InteractionOutcome, InteractionRequest }\n\n// ---------------------------------------------------------------------------\n// Event names\n\n/** Sidecar → client: the agent raised an ask; data = `{ request }`. */\nexport const INTERACTION_EVENT = 'interaction' as const\n/** Sidecar → client: the ask was withdrawn; data = `{ id, reason? }`. */\nexport const INTERACTION_CANCEL_EVENT = 'interaction.cancel' as const\n/** An ask was answered; data = `{ id, status }`. In the wire contract so a\n *  server broadcast and a client-local mark share one event name. */\nexport const INTERACTION_RESOLVED_EVENT = 'interaction.resolved' as const\n\n/** Interaction kinds a product typically renders a card for. Anything else is\n *  auto-declined by the chat producer's safety net and never reaches a client.\n *  A pure default; a product may substitute its own renderable set. */\nconst RENDERABLE_INTERACTION_KINDS: ReadonlySet<string> = new Set(['question', 'plan'])\n\n/** Resolve if the given interaction kind is renderable within the application context */\nexport function isRenderableInteractionKind(kind: string): boolean {\n  return RENDERABLE_INTERACTION_KINDS.has(kind)\n}\n\n/** Answer/field keys the sidecar will accept: identifier-safe and never a\n *  prototype-pollution vector. */\nexport function isSafeInteractionFieldKey(key: string): boolean {\n  return /^[A-Za-z0-9_-]+$/.test(key) && key !== '__proto__' && key !== 'constructor' && key !== 'prototype'\n}\n\n// ---------------------------------------------------------------------------\n// Field types\n//\n// `allowCustom` (a select that also accepts a write-in value) is defined by\n// newer agent-interface schemas; older pinned schemas strip unknown keys on\n// parse. The wire/persisted field types below carry the flag so a card can gate\n// its write-in input, and `parseInteractionRequest` returns the RAW payload\n// (schema-validated, not schema-parsed) so the flag survives.\n\n/** Extract select-type interaction fields and optionally allow custom values */\nexport type ChatSelectField = Extract<InteractionField, { type: 'select' }> & {\n  allowCustom?: boolean\n}\n/** Resolve a chat interaction field excluding select types or including chat select fields */\nexport type ChatInteractionField = Exclude<InteractionField, { type: 'select' }> | ChatSelectField\n\n/** `InteractionRequest` whose select fields may carry `allowCustom`. */\nexport type InteractionRequestWire = Omit<InteractionRequest, 'answerSpec'> & {\n  answerSpec: { fields: ChatInteractionField[] }\n}\n\n// ---------------------------------------------------------------------------\n// Interaction lifecycle\n\n/** Define possible statuses representing the state of a chat interaction */\nexport type ChatInteractionStatus = 'pending' | 'answered' | 'declined' | 'cancelled' | 'expired'\n\n/** Accepted field selections keyed by answer-spec field name. */\n/** Accepted answer values. Select fields historically used `string[]`; the\n * wider scalar union is additive and lets durable stores preserve text,\n * numeric, and boolean answer fields without coercion. */\nexport type InteractionAnswerValue = string | number | boolean | string[]\n/** Map interaction identifiers to their corresponding answer values */\nexport type InteractionAnswers = Record<string, InteractionAnswerValue>\n\n/** Resolve the result of parsing interaction answers with success status and corresponding data or error message */\nexport type ParseInteractionAnswersResult =\n  | { succeeded: true; value: InteractionAnswers }\n  | { succeeded: false; error: string }\n\n/** Strictly validates and copies persisted answer selections. */\nexport function parseInteractionAnswers(value: unknown): ParseInteractionAnswersResult {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    return { succeeded: false, error: 'interaction answers must be an object' }\n  }\n  const answers: InteractionAnswers = {}\n  for (const [key, selection] of Object.entries(value as Record<string, unknown>)) {\n    if (!isSafeInteractionFieldKey(key)) {\n      return { succeeded: false, error: `interaction answers contain an unsafe field key: ${key}` }\n    }\n    const valid = typeof selection === 'string' || typeof selection === 'number' || typeof selection === 'boolean' ||\n      (Array.isArray(selection) && selection.every((item) => typeof item === 'string'))\n    if (!valid) {\n      return { succeeded: false, error: `interaction answer ${key} must be a string, number, boolean, or string array` }\n    }\n    answers[key] = Array.isArray(selection) ? [...selection] : selection\n  }\n  return { succeeded: true, value: answers }\n}\n\n/** The client/persisted view of one ask. `fields` come verbatim off the wire. */\nexport interface ChatInteraction {\n  id: string\n  kind: string\n  title: string\n  body?: string\n  fields: ChatInteractionField[]\n  status: ChatInteractionStatus\n  /** Accepted selections, restored with the transcript after reload. */\n  answers?: InteractionAnswers\n  /** Set when status came from an `interaction.cancel` (e.g. \"timeout\"). */\n  cancelReason?: string\n}\n\n/** Resolve if the interaction status is a terminal state excluding pending */\nexport function isTerminalInteractionStatus(status: ChatInteractionStatus): boolean {\n  return status !== 'pending'\n}\n\n/** Statuses only move forward (pending → terminal); a replayed/stale `pending`\n *  must never resurrect a resolved card. */\nexport function canTransitionInteractionStatus(\n  from: ChatInteractionStatus,\n  to: ChatInteractionStatus,\n): boolean {\n  return from === 'pending' && to !== from\n}\n\n/** Maps an `interaction.cancel` reason to the card's terminal status. */\nexport function cancelStatusFor(reason: string | undefined): ChatInteractionStatus {\n  return reason === 'timeout' ? 'expired' : 'cancelled'\n}\n\nfunction stableValue(value: unknown): unknown {\n  if (Array.isArray(value)) return value.map(stableValue)\n  if (!value || typeof value !== 'object') return value\n  return Object.fromEntries(\n    Object.entries(value as Record<string, unknown>)\n      .sort(([left], [right]) => left.localeCompare(right))\n      .map(([key, nested]) => [key, stableValue(nested)]),\n  )\n}\n\nfunction normalizedInteractionText(value: string | undefined): string {\n  return (value ?? '').replace(/\\s+/g, ' ').trim()\n}\n\n/** Content identity for duplicate safety nets. Excludes volatile ids/statuses. */\nexport function questionInteractionContentSignature(interaction: ChatInteraction): string | null {\n  if (interaction.kind !== 'question') return null\n  return JSON.stringify(stableValue({\n    kind: interaction.kind,\n    title: normalizedInteractionText(interaction.title),\n    body: normalizedInteractionText(interaction.body),\n    fields: interaction.fields,\n  }))\n}\n\n/** Remove duplicate question interactions based on their content signature to ensure uniqueness */\nexport function dedupeQuestionInteractionsByContent(interactions: ChatInteraction[]): ChatInteraction[] {\n  const seen = new Set<string>()\n  return interactions.filter((interaction) => {\n    const signature = questionInteractionContentSignature(interaction)\n    if (!signature) return true\n    if (seen.has(signature)) return false\n    seen.add(signature)\n    return true\n  })\n}\n\n// ---------------------------------------------------------------------------\n// Wire parsing — typed outcomes, fail loud at the caller (log + skip; never a\n// half-rendered card).\n\n/** Resolve interaction parsing outcome as success with value or failure with error message */\nexport type ParseInteractionResult =\n  | { succeeded: true; value: InteractionRequestWire }\n  | { succeeded: false; error: string }\n\n/** Parses an `interaction` event's data (`{ request }`). Validates the shape\n *  with the agent-interface schema but returns the raw request so a field a\n *  pinned schema predates (`allowCustom`) survives. */\nexport function parseInteractionRequest(data: Record<string, unknown> | undefined): ParseInteractionResult {\n  const request = data?.request\n  if (!request || typeof request !== 'object') {\n    return { succeeded: false, error: 'interaction event carried no request object' }\n  }\n  const validation = InteractionRequestSchema.safeParse(request)\n  if (!validation.success) {\n    return { succeeded: false, error: `malformed interaction request: ${validation.error.message}` }\n  }\n  return { succeeded: true, value: request as InteractionRequestWire }\n}\n\n/** Describe data required to cancel an interaction including its identifier and optional reason */\nexport interface InteractionCancelData {\n  id: string\n  reason?: string\n}\n\n/** Parse interaction cancel data and return success status with parsed value or error message */\nexport function parseInteractionCancel(\n  data: Record<string, unknown> | undefined,\n): { succeeded: true; value: InteractionCancelData } | { succeeded: false; error: string } {\n  const id = typeof data?.id === 'string' && data.id ? data.id : null\n  if (!id) return { succeeded: false, error: 'interaction.cancel event carried no id' }\n  const reason = typeof data?.reason === 'string' && data.reason ? data.reason : undefined\n  return { succeeded: true, value: { id, ...(reason ? { reason } : {}) } }\n}\n\n// ---------------------------------------------------------------------------\n// Composer-as-answer delivery: while asks are pending the composer never\n// blocks — typed text is delivered verbatim to every open ask and the agent\n// decides what it means. No interpretation here; the sidecar validates answers\n// fail-closed (invalid free text on an option-only ask → 400).\n\n/** Determine if a chat interaction field allows free text input */\nexport function fieldAcceptsFreeText(field: ChatInteractionField): boolean {\n  if (field.type === 'text') return true\n  if (field.type === 'select') return (field as ChatSelectField).allowCustom === true\n  return false\n}\n\n/** Define the structure for delivering answers linked to a specific chat interaction and field */\nexport interface ComposerAnswerDelivery {\n  interactionId: string\n  field: ChatInteractionField\n}\n\n/** One delivery per pending ask: the first free-text-capable field, else the\n *  first field. Zero-field asks are skipped (nothing to carry the text). */\nexport function composerAnswerDeliveries(pending: ChatInteraction[]): ComposerAnswerDelivery[] {\n  const deliveries: ComposerAnswerDelivery[] = []\n  for (const interaction of pending) {\n    // Only questions take a composer-routed answer. A non-question ask (a plan)\n    // is POSTed as outcome:\"accepted\" when answered — routing composer text to\n    // it would silently APPROVE it. Approval is an explicit card click, so the\n    // composer skips it and the plan card stays the only path.\n    if (interaction.kind !== 'question') continue\n    const field = interaction.fields.find(fieldAcceptsFreeText) ?? interaction.fields[0]\n    if (!field) continue\n    deliveries.push({ interactionId: interaction.id, field })\n  }\n  return deliveries\n}\n\n/** Shapes composer text into the respond payload for the routed field\n *  (select answers are string arrays on the wire; text answers are strings). */\nexport function composerAnswerData(field: ChatInteractionField, text: string): InteractionData {\n  return { [field.name]: field.type === 'select' ? [text] : text }\n}\n\n// ---------------------------------------------------------------------------\n// Part keys + codecs (persisted `messages.parts` entries and live stream parts\n// share these shapes).\n\n/** Generate a unique key string for an interaction using the given identifier */\nexport function interactionPartKey(id: string): string {\n  return `interaction:${id}`\n}\n\n/** Generate a unique key string for a notice using the given identifier */\nexport function noticePartKey(id: string): string {\n  return `notice:${id}`\n}\n\n/** Define specific string literals representing different kinds of notices */\nexport type NoticeKind = 'warning' | 'auto-declined'\n\n/**\n * Persisted-part shapes the codecs below produce — the SAME rows\n * `/chat-store`'s `ChatInteractionPart`/`ChatNoticePart` store, typed at the\n * source so a product pushing them into a `ChatMessagePart[]` transcript needs\n * no cast. Type aliases (not interfaces) on purpose: the implicit index\n * signature keeps them assignable to the `Record<string, unknown>` these\n * codecs previously returned, so existing consumers stay source-compatible.\n */\nexport type InteractionPersistedPart = {\n  type: 'interaction'\n  id: string\n  kind: string\n  title: string\n  body?: string\n  answerSpec: { fields: ChatInteractionField[] }\n  status: ChatInteractionStatus\n  answers?: InteractionAnswers\n  cancelReason?: string\n}\n\n/** Define a persisted notice part with type, id, kind, and text properties */\nexport type NoticePersistedPart = {\n  type: 'notice'\n  id: string\n  noticeKind: NoticeKind\n  text: string\n}\n\n/** Builds the persisted/streamed `notice` part — a one-line transcript notice\n *  explaining an out-of-band event (warning, auto-declined interaction). */\nexport function noticePart(noticeKind: NoticeKind, id: string, text: string): NoticePersistedPart {\n  return { type: 'notice', id, noticeKind, text }\n}\n\n/** Reads a wire request into the client's pending `ChatInteraction`. */\nexport function interactionFromWireRequest(request: InteractionRequestWire): ChatInteraction {\n  return {\n    id: request.id,\n    kind: request.kind,\n    title: request.title,\n    ...(request.body ? { body: request.body } : {}),\n    fields: request.answerSpec.fields,\n    status: 'pending',\n  }\n}\n\n/** Builds the persisted/streamed `interaction` part from a wire request. */\nexport function interactionToPersistedPart(\n  request: InteractionRequestWire,\n  status: ChatInteractionStatus,\n  cancelReason?: string,\n  answers?: InteractionAnswers,\n): InteractionPersistedPart {\n  const parsedAnswers = answers === undefined ? undefined : parseInteractionAnswers(answers)\n  if (parsedAnswers && !parsedAnswers.succeeded) throw new TypeError(parsedAnswers.error)\n  return {\n    type: 'interaction',\n    id: request.id,\n    kind: request.kind,\n    title: request.title,\n    ...(request.body ? { body: request.body } : {}),\n    answerSpec: { fields: request.answerSpec.fields },\n    status,\n    ...(parsedAnswers?.succeeded ? { answers: parsedAnswers.value } : {}),\n    ...(cancelReason ? { cancelReason } : {}),\n  }\n}\n\n/** Stamps accepted values onto matching persisted interaction parts without\n * mutating the caller's transcript or answer maps. */\nexport function stampInteractionAnswers(\n  parts: Array<Record<string, unknown>>,\n  answersByInteractionId: Readonly<Record<string, InteractionAnswers>>,\n): Array<Record<string, unknown>> {\n  return parts.map((part) => {\n    if (String(part.type ?? '') !== 'interaction' || typeof part.id !== 'string') return part\n    if (!Object.prototype.hasOwnProperty.call(answersByInteractionId, part.id)) return part\n    const rawAnswers = answersByInteractionId[part.id]\n    if (rawAnswers === undefined) return part\n    const parsed = parseInteractionAnswers(rawAnswers)\n    if (!parsed.succeeded) throw new TypeError(parsed.error)\n    return { ...part, answers: parsed.value }\n  })\n}\n\n/** Reads a persisted/streamed `interaction` part back into a `ChatInteraction`.\n *  Returns null (caller logs) when the part is not one of ours. */\nexport function persistedPartToInteraction(part: Record<string, unknown>): ChatInteraction | null {\n  if (String(part.type ?? '') !== 'interaction') return null\n  const id = typeof part.id === 'string' && part.id ? part.id : null\n  const kind = typeof part.kind === 'string' && part.kind ? part.kind : null\n  const title = typeof part.title === 'string' ? part.title : ''\n  const answerSpec = part.answerSpec as { fields?: unknown } | undefined\n  const fields = Array.isArray(answerSpec?.fields) ? (answerSpec.fields as ChatInteractionField[]) : null\n  const status = part.status as ChatInteractionStatus | undefined\n  const validStatus = status && ['pending', 'answered', 'declined', 'cancelled', 'expired'].includes(status)\n  const parsedAnswers = part.answers === undefined ? undefined : parseInteractionAnswers(part.answers)\n  if (!id || !kind || !fields || !validStatus || (parsedAnswers && !parsedAnswers.succeeded)) return null\n  return {\n    id,\n    kind,\n    title,\n    ...(typeof part.body === 'string' && part.body ? { body: part.body } : {}),\n    fields,\n    status,\n    ...(parsedAnswers?.succeeded ? { answers: parsedAnswers.value } : {}),\n    ...(typeof part.cancelReason === 'string' && part.cancelReason ? { cancelReason: part.cancelReason } : {}),\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-TKVJE63N.js → chunk-YRMLYFVR.js}

@@ -2,10 +2,10 @@ import {
   clearCookieHeader,
   readCookieValue,
   serializeCookie
-} from "./chunk-HFC4BTWJ.js";
+} from "./chunk-PTUMBMVH.js";
 import {
   isTangleBillingEnforcementDisabled
-} from "./chunk-7W5XSTUF.js";
+} from "./chunk-JML7WKWU.js";
 
 // src/platform/sso.ts
 var DEFAULT_STATE_TTL_SECONDS = 600;
@@ -301,4 +301,4 @@ export {
   createAdminGuard,
   assertBillableBalance
 };
-//# sourceMappingURL=chunk-TKVJE63N.js.map
+//# sourceMappingURL=chunk-YRMLYFVR.js.map

package/dist/chunk-YRMLYFVR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/platform/sso.ts","../src/platform/guards.ts"],"sourcesContent":["/**\n * Cross-site Tangle SSO for agent apps: signed-state CSRF cookies plus the\n * full start/callback orchestration against the platform's /cross-site\n * bridge. The platform wire client and account persistence are structural\n * seams (`TangleSsoAuthClient` / `TangleSsoAccountStore`), so this module\n * never imports agent-runtime, an auth framework, or a database driver.\n * WebCrypto only — runs in workerd without node compatibility flags.\n */\n\nimport { clearCookieHeader, readCookieValue, serializeCookie } from '../web/index'\n\nconst DEFAULT_STATE_TTL_SECONDS = 600\nconst DEFAULT_SESSION_TTL_SECONDS = 60 * 60 * 24 * 7\nconst DEFAULT_REDIRECT_PATH = '/app'\nconst DEFAULT_LOGIN_PATH = '/login'\nconst DEFAULT_SESSION_COOKIE = 'better-auth.session_token'\n\n// ── Signed state ────────────────────────────────────────────────────────────\n\n/** Define configuration options for managing SSO state including secret, lifetime, and clock injection */\nexport interface SsoStateConfig {\n  /** HMAC-SHA256 secret (e.g. the app's auth secret). */\n  secret: string\n  /** State lifetime in ms. Default 600 000. */\n  ttlMs?: number\n  /** Injectable clock (ms since epoch). Default Date.now. */\n  now?: () => number\n}\n\nfunction randomHex(bytes: number): string {\n  const buf = new Uint8Array(bytes)\n  crypto.getRandomValues(buf)\n  return Array.from(buf, (b) => b.toString(16).padStart(2, '0')).join('')\n}\n\nasync function hmacBytes(secret: string, value: string): Promise<Uint8Array> {\n  const key = await crypto.subtle.importKey(\n    'raw',\n    new TextEncoder().encode(secret),\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['sign'],\n  )\n  return new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(value)))\n}\n\nasync function hmacHex(secret: string, value: string): Promise<string> {\n  return Array.from(await hmacBytes(secret, value), (b) => b.toString(16).padStart(2, '0')).join('')\n}\n\nfunction constantTimeEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) return false\n  let diff = 0\n  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)\n  return diff === 0\n}\n\n/** Mint a `<randomHex32>.<timestamp36>.<hmacHex>` state value. The timestamp\n *  is inside the signed payload, so expiry survives cookie-attribute tampering. */\nexport async function createSignedSsoState(config: SsoStateConfig): Promise<string> {\n  if (!config.secret) throw new Error('SsoStateConfig.secret is required')\n  const now = config.now ?? Date.now\n  const payload = `${randomHex(16)}.${now().toString(36)}`\n  return `${payload}.${await hmacHex(config.secret, payload)}`\n}\n\n/** Verify the MAC (constant-time) and the signed TTL. */\nexport async function verifySignedSsoState(state: string, config: SsoStateConfig): Promise<boolean> {\n  if (!config.secret) throw new Error('SsoStateConfig.secret is required')\n  const parts = state.split('.')\n  if (parts.length !== 3) return false\n  const [random, timestamp, mac] = parts\n  if (!random || !timestamp || !mac) return false\n  const expected = await hmacHex(config.secret, `${random}.${timestamp}`)\n  if (!constantTimeEqual(mac, expected)) return false\n  const mintedAt = parseInt(timestamp, 36)\n  if (!Number.isFinite(mintedAt)) return false\n  const now = config.now ?? Date.now\n  const ttlMs = config.ttlMs ?? DEFAULT_STATE_TTL_SECONDS * 1000\n  return now() - mintedAt <= ttlMs\n}\n\n// ── Seams ───────────────────────────────────────────────────────────────────\n\n/** Describe the result of exchanging SSO credentials including API key, user info, and optional plan details */\nexport interface TangleSsoExchangeResult {\n  apiKey: string\n  user: { id: string; email: string; name?: string | null }\n  plan?: { tier: string } | null\n}\n\n/** Structural mirror of the platform auth wire client — any object with these\n *  two methods satisfies it without this module importing the concrete class. */\nexport interface TangleSsoAuthClient {\n  authorizeUrl(options: { state: string; redirectUri?: string }): string\n  exchange(code: string): Promise<TangleSsoExchangeResult>\n}\n\n/** Thrown by `upsertUserByEmail` when the app-local user row cannot be\n *  created; the callback handler maps it to `?error=tangle_user_create_failed`.\n *  Any other store error propagates. */\nexport class TangleSsoUserCreateError extends Error {\n  constructor(message = 'Failed to create local user for Tangle SSO') {\n    super(message)\n    this.name = 'TangleSsoUserCreateError'\n  }\n}\n\n/**\n * Account persistence seam. Covers both storage styles in use: link-table\n * apps (a per-user platform-link row) and session-column apps (the key on the\n * session row) — `saveTangleLink` receives both `userId` and `sessionToken`,\n * and each app persists with the key it needs. `createSession` runs first so\n * the token is always available to `saveTangleLink`.\n */\nexport interface TangleSsoAccountStore {\n  /** Find-or-create the app-local user. `tangleUserId` is the platform's\n   *  stable user id — match on it first when the app stores it (emails are\n   *  mutable on the platform; the id is not), falling back to email for\n   *  first-time logins. */\n  upsertUserByEmail(input: { email: string; name: string | null; tangleUserId: string }): Promise<{ userId: string }>\n  /** Create an app session row; returns the session-cookie token value. */\n  createSession(input: {\n    userId: string\n    expiresAt: Date\n    ipAddress: string | null\n    userAgent: string | null\n  }): Promise<{ token: string }>\n  /** Persist the platform link (API key + platform identity). */\n  saveTangleLink(input: {\n    userId: string\n    sessionToken: string\n    tangleUserId: string\n    email: string\n    name: string | null\n    apiKey: string\n    planTier: string | null\n  }): Promise<void>\n}\n\n// ── Session cookie ──────────────────────────────────────────────────────────\n\n/** Successful-login context handed to the `setSessionCookie` seam. */\nexport interface TangleSsoSessionCookieArgs {\n  /** Session token returned by `store.createSession`. */\n  token: string\n  /** Session expiry (now + `sessionTtlSeconds`). */\n  expiresAt: Date\n  /** Mirrors `sessionTtlSeconds` after defaulting. */\n  ttlSeconds: number\n  /** Mirrors `TangleSsoHandlerOptions.secureCookies`. */\n  secure: boolean\n}\n\n/**\n * Sign a session token to better-call's signed-cookie contract — the value\n * better-auth's `getSignedCookie` verifies: `<token>.<signature>` where the\n * signature is the raw HMAC-SHA256 of the token under `secret`, encoded as\n * STANDARD base64 WITH padding (32 bytes → 44 chars ending `=`; better-call\n * rejects any other length or suffix, so url-safe/unpadded variants read back\n * as a null session). The joined value is percent-encoded once at cookie\n * serialization, matching better-call's `serializeSignedCookie` byte-exactly.\n */\nexport async function signSessionCookieValue(token: string, secret: string): Promise<string> {\n  if (!secret) throw new Error('signSessionCookieValue requires a non-empty secret')\n  const sig = await hmacBytes(secret, token)\n  let bin = ''\n  for (const byte of sig) bin += String.fromCharCode(byte)\n  return `${token}.${btoa(bin)}`\n}\n\n/** Structural slice of a `betterAuth()` instance — only what cookie minting\n *  reads. No better-auth import: the signing contract is implemented by\n *  `signSessionCookieValue`, byte-compatible with better-auth's own\n *  `makeSignature`. */\nexport interface BetterAuthSessionCookieSource {\n  $context: PromiseLike<{\n    secret: string\n    authCookies: {\n      sessionToken: {\n        /** Final cookie name — better-auth decides the `__Secure-` prefix\n         *  (and any `advanced.cookiePrefix`) once at `betterAuth()` init. */\n        name: string\n        attributes: {\n          secure?: boolean\n          sameSite?: string\n          path?: string\n          httpOnly?: boolean\n          domain?: string\n        }\n      }\n    }\n  }>\n}\n\n/** Define options to customize warning behavior for shadowed cookie names in authentication sessions */\nexport interface BetterAuthSessionCookieMinterOptions {\n  /** Receives the shadowed-cookie-name warning (see below). Default\n   *  console.warn. */\n  warn?: (message: string) => void\n}\n\n/**\n * Canonical `setSessionCookie` wiring for better-auth apps: mint the session\n * Set-Cookie exactly as better-auth's own login flows do — name + attributes\n * from `auth.$context.authCookies.sessionToken` (better-auth stays\n * authoritative over prefix/name/attributes) and the value signed to\n * better-call's `getSignedCookie` contract. A raw unprefixed\n * `better-auth.session_token` left by an earlier login is explicitly expired\n * so it cannot shadow the real cookie.\n *\n * Warns when the app's session cookie still has better-auth's DEFAULT name:\n * the Tangle platform (id.tangle.tools) sets a `Domain=.tangle.tools` cookie\n * under that exact name, and equal-path cookies are sent oldest-first — the\n * platform's cookie is always older (the user signs in there before the app's\n * callback runs), so the app reads the platform's token, fails its own\n * signature check, and every fresh login lands logged-out. Per-app\n * `advanced.cookiePrefix` is the fix.\n *\n * Throws on a domain-scoped session cookie for the same reason: a\n * `Domain=`-wide session cookie is exactly the shadowing footgun.\n */\nexport function createBetterAuthSessionCookieMinter(\n  auth: BetterAuthSessionCookieSource,\n  options: BetterAuthSessionCookieMinterOptions = {},\n): (args: TangleSsoSessionCookieArgs) => Promise<string[]> {\n  const warn = options.warn ?? ((message: string) => console.warn(message))\n  return async ({ token, ttlSeconds }) => {\n    const ctx = await auth.$context\n    if (!ctx.secret) {\n      throw new Error('createBetterAuthSessionCookieMinter: auth context has no secret')\n    }\n    const { name, attributes } = ctx.authCookies.sessionToken\n    if (attributes.domain) {\n      throw new Error(\n        `createBetterAuthSessionCookieMinter: refusing a domain-scoped session cookie (Domain=${attributes.domain}) — ` +\n          'a domain-wide session cookie shadows sibling apps that share the parent domain',\n      )\n    }\n    if (name === DEFAULT_SESSION_COOKIE || name === `__Secure-${DEFAULT_SESSION_COOKIE}`) {\n      warn(\n        `[tangle-sso] session cookie is named \"${name}\" — better-auth's default. ` +\n          'The Tangle platform (id.tangle.tools) sets a Domain=.tangle.tools cookie under the same name, ' +\n          \"and the platform's (older) cookie wins the Cookie-header order, so this app's sessions read back null. \" +\n          \"Set a per-app prefix: betterAuth({ advanced: { cookiePrefix: '<app>' } }).\",\n      )\n    }\n    const sameSite = typeof attributes.sameSite === 'string' ? attributes.sameSite : 'lax'\n    const cookieOptions = {\n      name,\n      path: typeof attributes.path === 'string' ? attributes.path : '/',\n      httpOnly: attributes.httpOnly !== false,\n      sameSite: (sameSite.charAt(0).toUpperCase() + sameSite.slice(1)) as 'Lax' | 'Strict' | 'None',\n      secure: Boolean(attributes.secure) || name.startsWith('__Secure-'),\n      maxAgeSeconds: ttlSeconds,\n    }\n    const cookies = [serializeCookie(await signSessionCookieValue(token, ctx.secret), cookieOptions)]\n    if (name !== DEFAULT_SESSION_COOKIE) {\n      cookies.push(clearCookieHeader({ ...cookieOptions, name: DEFAULT_SESSION_COOKIE }))\n    }\n    return cookies\n  }\n}\n\n// ── Handlers ────────────────────────────────────────────────────────────────\n\n/** Define configuration options for handling Tangle SSO authentication and session management */\nexport interface TangleSsoHandlerOptions {\n  auth: TangleSsoAuthClient\n  store: TangleSsoAccountStore\n  /** HMAC secret for the state cookie. */\n  stateSecret: string\n  /** Absolute callback URL registered with the platform. */\n  callbackUrl: string\n  stateCookieName: string\n  /** Default 'better-auth.session_token'. Ignored when `setSessionCookie` is\n   *  provided. The default path prepends `__Secure-` iff `secureCookies`. */\n  sessionCookieName?: string\n  /** Mint the host auth framework's own session cookie(s); return complete\n   *  Set-Cookie header values (the handler appends them verbatim and sets no\n   *  session cookie itself). Supply this when the framework should stay\n   *  authoritative over name/prefix/signing/attributes — e.g. better-auth:\n   *  `auth.$context.authCookies.sessionToken` + `makeSignature`. */\n  setSessionCookie?: (\n    args: TangleSsoSessionCookieArgs,\n  ) => readonly string[] | Promise<readonly string[]>\n  /** HMAC-SHA256 secret the host auth framework verifies session cookies with\n   *  (better-auth: its `secret`). Required when `setSessionCookie` is absent —\n   *  the default cookie is minted to better-call's signed contract via\n   *  `signSessionCookieValue`; an unsigned or mis-signed value reads back as a\n   *  null session, so there is deliberately no fallback to `stateSecret`\n   *  (which is not guaranteed to be the auth secret). */\n  sessionCookieSecret?: string\n  /** Adds `Secure` to every cookie this module sets, and (default session\n   *  cookie only) the `__Secure-` name prefix. Must match the auth\n   *  framework's own secure-cookie decision (better-auth: https `baseURL` /\n   *  `advanced.useSecureCookies`), or it will look up a different cookie name\n   *  than the one set here. */\n  secureCookies: boolean\n  /** Default 604 800 (7 days). */\n  sessionTtlSeconds?: number\n  /** Default 600. Applies to both the cookie Max-Age and the signed TTL. */\n  stateTtlSeconds?: number\n  /** Default '/app'. */\n  defaultRedirectPath?: string\n  /** Default '/login'. */\n  loginPath?: string\n  /** Failure log hook (e.g. console.error). Default no-op. */\n  log?: (message: string, error?: unknown) => void\n  now?: () => number\n}\n\n/** Define handlers for SSO start and callback routes managing authentication flow and session cookies */\nexport interface TangleSsoHandlers {\n  /** GET start route: mint + sign state, set the state cookie, 302 to the\n   *  platform authorize URL. `?redirect=` carries the post-login path. */\n  start(request: Request): Promise<Response>\n  /** GET callback route: verify state, exchange the code, upsert the user,\n   *  create the session, save the platform link, set the session cookie\n   *  (via the `setSessionCookie` seam, else signed to better-call's contract\n   *  with `sessionCookieSecret`), 302 to the saved redirect. Every failure\n   *  302s to `loginPath?error=…` with the state cookie cleared. */\n  callback(request: Request): Promise<Response>\n}\n\n/** Accept only same-origin absolute paths (rejects `//host` protocol-relative URLs). */\nfunction sanitizeRedirectPath(value: string | null, fallback: string): string {\n  if (value && value.startsWith('/') && !value.startsWith('//')) return value\n  return fallback\n}\n\nfunction redirectResponse(location: string, headers = new Headers()): Response {\n  headers.set('Location', location)\n  return new Response(null, { status: 302, headers })\n}\n\n/** Real client IP: `CF-Connecting-IP` behind Cloudflare, else the first\n *  `x-forwarded-for` hop (the rest of the list is sender-controlled). */\nfunction clientIp(request: Request): string | null {\n  return (\n    request.headers.get('CF-Connecting-IP') ??\n    request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??\n    null\n  )\n}\n\ninterface StateCookiePayload {\n  s: string\n  r: string\n}\n\nfunction parseStateCookiePayload(raw: string | null): StateCookiePayload | null {\n  if (!raw) return null\n  try {\n    const parsed = JSON.parse(raw) as unknown\n    if (parsed === null || typeof parsed !== 'object') return null\n    const { s, r } = parsed as Record<string, unknown>\n    if (typeof s !== 'string' || typeof r !== 'string') return null\n    return { s, r }\n  } catch {\n    return null\n  }\n}\n\n/** Create Tangle SSO handlers to manage authentication state, callbacks, and session cookies */\nexport function createTangleSsoHandlers(opts: TangleSsoHandlerOptions): TangleSsoHandlers {\n  if (!opts.stateSecret) throw new Error('TangleSsoHandlerOptions.stateSecret is required')\n  if (!opts.callbackUrl) throw new Error('TangleSsoHandlerOptions.callbackUrl is required')\n  if (!opts.stateCookieName) throw new Error('TangleSsoHandlerOptions.stateCookieName is required')\n\n  const sessionCookieName = opts.sessionCookieName ?? DEFAULT_SESSION_COOKIE\n\n  let mintSessionCookies: (args: TangleSsoSessionCookieArgs) => Promise<readonly string[]>\n  if (opts.setSessionCookie) {\n    const seam = opts.setSessionCookie\n    mintSessionCookies = async (args) => await seam(args)\n  } else if (opts.sessionCookieSecret) {\n    const secret = opts.sessionCookieSecret\n    mintSessionCookies = async ({ token, secure, ttlSeconds }) => [\n      serializeCookie(await signSessionCookieValue(token, secret), {\n        name: secure ? `__Secure-${sessionCookieName}` : sessionCookieName,\n        secure,\n        maxAgeSeconds: ttlSeconds,\n      }),\n    ]\n  } else {\n    throw new Error(\n      'TangleSsoHandlerOptions requires setSessionCookie or sessionCookieSecret: ' +\n        'better-auth only accepts HMAC-signed (and, on https, __Secure--prefixed) session cookies, ' +\n        'so an unsigned default would mint sessions that read back null',\n    )\n  }\n  const sessionTtlSeconds = opts.sessionTtlSeconds ?? DEFAULT_SESSION_TTL_SECONDS\n  const stateTtlSeconds = opts.stateTtlSeconds ?? DEFAULT_STATE_TTL_SECONDS\n  const defaultRedirectPath = opts.defaultRedirectPath ?? DEFAULT_REDIRECT_PATH\n  const loginPath = opts.loginPath ?? DEFAULT_LOGIN_PATH\n  const log = opts.log ?? (() => {})\n  const now = opts.now ?? Date.now\n  const stateConfig: SsoStateConfig = { secret: opts.stateSecret, ttlMs: stateTtlSeconds * 1000, now }\n\n  const stateCookieOpts = { name: opts.stateCookieName, secure: opts.secureCookies }\n\n  function loginErrorRedirect(code: string): Response {\n    const headers = new Headers()\n    headers.append('Set-Cookie', clearCookieHeader(stateCookieOpts))\n    return redirectResponse(`${loginPath}?error=${code}`, headers)\n  }\n\n  return {\n    async start(request) {\n      const url = new URL(request.url)\n      const redirectPath = sanitizeRedirectPath(url.searchParams.get('redirect'), defaultRedirectPath)\n      const state = await createSignedSsoState(stateConfig)\n      const cookie = serializeCookie(JSON.stringify({ s: state, r: redirectPath }), {\n        ...stateCookieOpts,\n        maxAgeSeconds: stateTtlSeconds,\n      })\n      const headers = new Headers()\n      headers.append('Set-Cookie', cookie)\n      return redirectResponse(opts.auth.authorizeUrl({ state, redirectUri: opts.callbackUrl }), headers)\n    },\n\n    async callback(request) {\n      const url = new URL(request.url)\n      const code = url.searchParams.get('code')\n      const stateFromPlatform = url.searchParams.get('state')\n      if (!code || !stateFromPlatform) return loginErrorRedirect('tangle_callback_missing')\n\n      const payload = parseStateCookiePayload(readCookieValue(request.headers.get('cookie'), opts.stateCookieName))\n      if (!payload || payload.s !== stateFromPlatform) return loginErrorRedirect('tangle_state_mismatch')\n      if (!(await verifySignedSsoState(payload.s, stateConfig))) return loginErrorRedirect('tangle_state_mismatch')\n\n      let exchanged: TangleSsoExchangeResult\n      try {\n        exchanged = await opts.auth.exchange(code)\n      } catch (err) {\n        log('[tangle-sso] exchange failed', err)\n        return loginErrorRedirect('tangle_exchange_failed')\n      }\n\n      let userId: string\n      try {\n        ;({ userId } = await opts.store.upsertUserByEmail({\n          email: exchanged.user.email,\n          name: exchanged.user.name ?? null,\n          tangleUserId: exchanged.user.id,\n        }))\n      } catch (err) {\n        if (err instanceof TangleSsoUserCreateError) return loginErrorRedirect('tangle_user_create_failed')\n        throw err\n      }\n\n      const expiresAt = new Date(now() + sessionTtlSeconds * 1000)\n      const { token } = await opts.store.createSession({\n        userId,\n        expiresAt,\n        ipAddress: clientIp(request),\n        userAgent: request.headers.get('user-agent'),\n      })\n\n      await opts.store.saveTangleLink({\n        userId,\n        sessionToken: token,\n        tangleUserId: exchanged.user.id,\n        email: exchanged.user.email,\n        name: exchanged.user.name ?? null,\n        apiKey: exchanged.apiKey,\n        planTier: exchanged.plan?.tier ?? null,\n      })\n\n      const headers = new Headers()\n      headers.append('Set-Cookie', clearCookieHeader(stateCookieOpts))\n      const sessionCookies = await mintSessionCookies({\n        token,\n        expiresAt,\n        ttlSeconds: sessionTtlSeconds,\n        secure: opts.secureCookies,\n      })\n      for (const cookie of sessionCookies) headers.append('Set-Cookie', cookie)\n      return redirectResponse(sanitizeRedirectPath(payload.r, defaultRedirectPath), headers)\n    },\n  }\n}\n","/**\n * Request guards for agent-app routes: session auth (302 redirect for pages,\n * JSON 401 for APIs), admin allowlisting (404 — the route stays invisible to\n * non-admins), and the billable-balance gate (402 with a stable code).\n * Session resolution is a seam; thrown Responses follow the router convention\n * of surfacing a thrown Response as the route result.\n */\n\nimport { isTangleBillingEnforcementDisabled } from '../runtime/model'\n\n/** Define options for configuring authentication guard behavior and session retrieval */\nexport interface AuthGuardOptions<Session> {\n  /** e.g. a better-auth `auth.api.getSession` wrapped by the app. */\n  getSession(request: Request): Promise<Session | null | undefined>\n  /** Default '/login'. */\n  loginPath?: string\n}\n\n/** Resolve user authentication and session requirements for page and API requests */\nexport interface AuthGuard<Session> {\n  /** Page guard — throws a 302 redirect Response to `loginPath`. */\n  requireUser(request: Request): Promise<Session>\n  /** API guard — throws JSON 401 `{ error: 'Unauthorized', code: 'auth.unauthenticated' }`. */\n  requireApiUser(request: Request): Promise<Session>\n  /** `apiResponse` selects the 401 JSON path over the redirect. */\n  requireSession(request: Request, opts?: { apiResponse?: boolean }): Promise<Session>\n  getOptionalSession(request: Request): Promise<Session | null>\n}\n\n/** Create an authentication guard that enforces session presence and handles unauthorized access responses */\nexport function createAuthGuard<Session>(opts: AuthGuardOptions<Session>): AuthGuard<Session> {\n  const loginPath = opts.loginPath ?? '/login'\n\n  async function requireSession(request: Request, o: { apiResponse?: boolean } = {}): Promise<Session> {\n    const session = await opts.getSession(request)\n    if (!session) {\n      if (o.apiResponse) {\n        throw Response.json({ error: 'Unauthorized', code: 'auth.unauthenticated' }, { status: 401 })\n      }\n      throw new Response(null, { status: 302, headers: { Location: loginPath } })\n    }\n    return session\n  }\n\n  return {\n    requireSession,\n    requireUser: (request) => requireSession(request),\n    requireApiUser: (request) => requireSession(request, { apiResponse: true }),\n    getOptionalSession: async (request) => (await opts.getSession(request)) ?? null,\n  }\n}\n\n/** Resolve a value or an HTTP response indicating failure in a guarded operation */\nexport type GuardResolution<T> = { ok: true; value: T } | { ok: false; response: Response }\n\n/**\n * Adapt a guard that THROWS a Response (the quartet above — the router\n * convention) to the `{ok: true, value} | {ok: false, response}` resolution\n * shape the route factories take (`/chat-routes` `authorize`,\n * `/interactions` `resolveConnection`, `/chat-routes` upload `authorize`).\n * Every product wrote this try/catch by hand; it lives here once.\n */\nexport async function guardResolution<T>(run: () => Promise<T>): Promise<GuardResolution<T>> {\n  try {\n    return { ok: true, value: await run() }\n  } catch (err) {\n    if (err instanceof Response) return { ok: false, response: err }\n    throw err\n  }\n}\n\n/** Comma/whitespace separated → trimmed, lowercased, empties dropped. */\nexport function parseAdminEmails(raw: string | null | undefined): string[] {\n  return (raw ?? '')\n    .split(/[,\\s]+/)\n    .map((e) => e.trim().toLowerCase())\n    .filter(Boolean)\n}\n\n/** Define options to resolve user session and control access based on allowed admin emails */\nexport interface AdminGuardOptions<Session> {\n  requireUser(request: Request): Promise<Session>\n  emailOf(session: Session): string | null | undefined\n  /** Resolved per request; an EMPTY allowlist refuses everyone. */\n  allowedEmails(): string[]\n}\n\n/** Non-admins (and empty allowlists) get 404, keeping the route invisible —\n *  better than a \"forbidden\" footprint that advertises its existence. */\nexport function createAdminGuard<Session>(opts: AdminGuardOptions<Session>): (request: Request) => Promise<Session> {\n  return async (request) => {\n    const session = await opts.requireUser(request)\n    const allowed = opts.allowedEmails()\n    if (allowed.length === 0) throw new Response('Not found', { status: 404 })\n    const email = (opts.emailOf(session) ?? '').toLowerCase()\n    if (!allowed.includes(email)) throw new Response('Not found', { status: 404 })\n    return session\n  }\n}\n\n/** Describe the billable balance state including overage permission and remaining USD balance */\nexport interface BillableBalanceState {\n  overageAllowed: boolean\n  remainingBalanceUsd: number\n}\n\n/** Define options to assert and customize billable balance enforcement behavior */\nexport interface AssertBillableBalanceOptions {\n  env?: Record<string, string | undefined>\n  /** App-specific enforcement override flag (e.g. 'GTM_BILLING_ENFORCEMENT'),\n   *  fed to `isTangleBillingEnforcementDisabled`. */\n  enforcementEnvVar?: string\n  /** Default 'Add balance or upgrade your plan to invoke this agent.'. */\n  errorMessage?: string\n  /** Merged into the 402 JSON body (e.g. `{ organizationId }`). */\n  errorBody?: Record<string, unknown>\n}\n\n/**\n * Gate a billable turn: passes when enforcement is disabled (dev default),\n * the tier allows overage, or remaining balance is positive. Otherwise throws\n * a 402 Response with the stable `billing.balance_required` code so clients\n * can route to the billing screen.\n */\nexport function assertBillableBalance(state: BillableBalanceState, opts: AssertBillableBalanceOptions = {}): void {\n  if (isTangleBillingEnforcementDisabled({ env: opts.env, enforcementEnvVar: opts.enforcementEnvVar })) return\n  if (state.overageAllowed || state.remainingBalanceUsd > 0) return\n  // errorBody first: the stable error/code contract always wins over caller extras.\n  throw Response.json(\n    {\n      ...opts.errorBody,\n      error: opts.errorMessage ?? 'Add balance or upgrade your plan to invoke this agent.',\n      code: 'billing.balance_required',\n    },\n    { status: 402 },\n  )\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-USYXHDKE.js → chunk-YZ6KQULN.js}

@@ -1,6 +1,6 @@
 import {
   isComplete
-} from "./chunk-ND3XEGBE.js";
+} from "./chunk-JDEGS53O.js";
 
 // src/intakes/completion.ts
 function emptyPayload(graph) {
@@ -27,4 +27,4 @@ export {
   payloadIsStale,
   markComplete
 };
-//# sourceMappingURL=chunk-USYXHDKE.js.map
+//# sourceMappingURL=chunk-YZ6KQULN.js.map

package/dist/{command-stack-B_-WNfZU.d.ts → command-stack-TNPWJCzW.d.ts}

@@ -1,5 +1,5 @@
-import { c as SceneDocument, d as SceneElement, g as ScenePage, B as Bounds } from './model-BBwyOuWG.js';
-import { g as SceneOperation } from './operations-DLIvvD00.js';
+import { c as SceneDocument, a as SceneElement, S as ScenePage, B as Bounds } from './model-DnfO_PdJ.js';
+import { S as SceneOperation } from './operations-ByJ6yXOW.js';
 import { CanvasRenderPalette } from './theme/index.js';
 
 /**
@@ -15,6 +15,7 @@ import { CanvasRenderPalette } from './theme/index.js';
  * never per-pixel.
  */
 
+/** Define the state of the editor scene including document, view settings, and selection details */
 interface EditorSceneState {
     document: SceneDocument;
     activePageId: string;
@@ -30,6 +31,7 @@ interface EditorSceneState {
     showRulers: boolean;
     showBleed: boolean;
 }
+/** Define a command with execution, undo, and operation methods for scene editing and persistence */
 interface SceneCommand {
     label: string;
     execute(state: EditorSceneState): EditorSceneState;
@@ -43,6 +45,7 @@ interface SceneCommand {
      */
     inverseOperations(): SceneOperation[];
 }
+/** Manage and track scene commands with undo, redo, and state subscription capabilities */
 interface SceneCommandStack {
     execute(command: SceneCommand): void;
     /** Apply the top-of-done-stack inverse and return the command (callers use
@@ -77,16 +80,20 @@ interface SceneCommandStack {
      */
     rollback(command: SceneCommand): void;
 }
+/** Define snap target categories for aligning elements within a layout system */
 type SnapTargetKind = 'grid' | 'element-edge' | 'element-center' | 'page-edge' | 'page-center' | 'guide';
+/** Define a target position and kind for snapping elements on a page */
 interface SnapTarget {
     /** Page-coordinate position of the snap line. */
     position: number;
     kind: SnapTargetKind;
 }
+/** Define vertical and horizontal collections of snap targets for alignment purposes */
 interface SnapTargets {
     vertical: SnapTarget[];
     horizontal: SnapTarget[];
 }
+/** Define the result of a snap operation including coordinates and active snap lines */
 interface SnapResult {
     x: number;
     y: number;
@@ -94,6 +101,7 @@ interface SnapResult {
     activeVertical: SnapTarget | null;
     activeHorizontal: SnapTarget | null;
 }
+/** Resolve snapping targets and apply snapping logic to moving elements within the editor scene */
 interface SnapEngine {
     /** Collect targets for a gesture: other elements' edges/centers, page
      *  edges/center, saved guides, and grid lines when enabled. `excludeIds`
@@ -102,6 +110,7 @@ interface SnapEngine {
     /** Snap a moving AABB. Threshold is SCREEN pixels, divided by zoom. */
     apply(bounds: Bounds, targets: SnapTargets, thresholdPx: number, zoom: number): SnapResult;
 }
+/** Define methods and properties to calculate zoom and pan transformations between document and screen coordinates */
 interface ZoomPanMath {
     minZoom: number;
     maxZoom: number;
@@ -145,6 +154,7 @@ interface ZoomPanMath {
         y: number;
     };
 }
+/** Resolve the result of applying a scene update including revision and optional normalized document */
 interface ApplySceneResult {
     rev: number;
     /** Present when the server re-minted ids or normalized the document; the
@@ -175,6 +185,7 @@ interface ExportTriggerOptions {
  *   gallery/thumbnail/export all stay. Additive and backward-compatible.
  */
 type DesignCanvasMode = 'edit' | 'review';
+/** Define properties and callbacks for configuring and controlling the design canvas editor */
 interface DesignCanvasProps {
     document: SceneDocument;
     /** Revision the document was loaded at; threaded through saves. */
@@ -281,6 +292,7 @@ interface SceneCommandStackWithReapply extends SceneCommandStack {
      */
     reundo(command: SceneCommand): void;
 }
+/** Create a command stack for scene editing with reapply capabilities based on the given document and page ID */
 declare function createSceneCommandStack(document: SceneDocument, activePageId: string): SceneCommandStackWithReapply;
 
 export { type ApplySceneResult as A, type DesignCanvasProps as D, type ExportTriggerOptions as E, SCENE_COMMAND_HISTORY_LIMIT as S, type ZoomPanMath as Z, type DesignCanvasMode as a, type EditorSceneState as b, createSceneCommandStack as c, type SceneCommand as d, type SceneCommandStack as e, type SceneCommandStackWithReapply as f, type SnapEngine as g, type SnapResult as h, type SnapTarget as i, type SnapTargetKind as j, type SnapTargets as k };

package/dist/{completion-Kaqp_tWk.d.ts → completion-CvcNUz07.d.ts}

@@ -1,4 +1,4 @@
-import { e as IntakeAnswers, b as IntakeGraph, I as IntakeAnswerValue } from './model-Bzi5i63l.js';
+import { e as IntakeAnswers, b as IntakeGraph, I as IntakeAnswerValue } from './model-C8U0HZxL.js';
 
 /**
  * Pure completion-state helpers for an intake payload — the small algebra over

package/dist/config/index.d.ts

@@ -1,6 +1,6 @@
 import { KnowledgeRequirementSpec } from '../knowledge/index.js';
 export { SatisfiedByRule } from '../knowledge/index.js';
-import { k as TangleModelConfig } from '../model-dF2h4xT9.js';
+import { k as TangleModelConfig } from '../model-DmdkIteM.js';
 import '@tangle-network/agent-eval';
 
 /**

package/dist/{contract-KfqJh_au.d.ts → contract-TjB68uqA.d.ts}

@@ -7,15 +7,18 @@ declare const INTERACTION_CANCEL_EVENT: "interaction.cancel";
 /** An ask was answered; data = `{ id, status }`. In the wire contract so a
  *  server broadcast and a client-local mark share one event name. */
 declare const INTERACTION_RESOLVED_EVENT: "interaction.resolved";
+/** Resolve if the given interaction kind is renderable within the application context */
 declare function isRenderableInteractionKind(kind: string): boolean;
 /** Answer/field keys the sidecar will accept: identifier-safe and never a
  *  prototype-pollution vector. */
 declare function isSafeInteractionFieldKey(key: string): boolean;
+/** Extract select-type interaction fields and optionally allow custom values */
 type ChatSelectField = Extract<InteractionField, {
     type: 'select';
 }> & {
     allowCustom?: boolean;
 };
+/** Resolve a chat interaction field excluding select types or including chat select fields */
 type ChatInteractionField = Exclude<InteractionField, {
     type: 'select';
 }> | ChatSelectField;
@@ -25,13 +28,16 @@ type InteractionRequestWire = Omit<InteractionRequest, 'answerSpec'> & {
         fields: ChatInteractionField[];
     };
 };
+/** Define possible statuses representing the state of a chat interaction */
 type ChatInteractionStatus = 'pending' | 'answered' | 'declined' | 'cancelled' | 'expired';
 /** Accepted field selections keyed by answer-spec field name. */
 /** Accepted answer values. Select fields historically used `string[]`; the
  * wider scalar union is additive and lets durable stores preserve text,
  * numeric, and boolean answer fields without coercion. */
 type InteractionAnswerValue = string | number | boolean | string[];
+/** Map interaction identifiers to their corresponding answer values */
 type InteractionAnswers = Record<string, InteractionAnswerValue>;
+/** Resolve the result of parsing interaction answers with success status and corresponding data or error message */
 type ParseInteractionAnswersResult = {
     succeeded: true;
     value: InteractionAnswers;
@@ -54,6 +60,7 @@ interface ChatInteraction {
     /** Set when status came from an `interaction.cancel` (e.g. "timeout"). */
     cancelReason?: string;
 }
+/** Resolve if the interaction status is a terminal state excluding pending */
 declare function isTerminalInteractionStatus(status: ChatInteractionStatus): boolean;
 /** Statuses only move forward (pending → terminal); a replayed/stale `pending`
  *  must never resurrect a resolved card. */
@@ -62,7 +69,9 @@ declare function canTransitionInteractionStatus(from: ChatInteractionStatus, to:
 declare function cancelStatusFor(reason: string | undefined): ChatInteractionStatus;
 /** Content identity for duplicate safety nets. Excludes volatile ids/statuses. */
 declare function questionInteractionContentSignature(interaction: ChatInteraction): string | null;
+/** Remove duplicate question interactions based on their content signature to ensure uniqueness */
 declare function dedupeQuestionInteractionsByContent(interactions: ChatInteraction[]): ChatInteraction[];
+/** Resolve interaction parsing outcome as success with value or failure with error message */
 type ParseInteractionResult = {
     succeeded: true;
     value: InteractionRequestWire;
@@ -74,10 +83,12 @@ type ParseInteractionResult = {
  *  with the agent-interface schema but returns the raw request so a field a
  *  pinned schema predates (`allowCustom`) survives. */
 declare function parseInteractionRequest(data: Record<string, unknown> | undefined): ParseInteractionResult;
+/** Describe data required to cancel an interaction including its identifier and optional reason */
 interface InteractionCancelData {
     id: string;
     reason?: string;
 }
+/** Parse interaction cancel data and return success status with parsed value or error message */
 declare function parseInteractionCancel(data: Record<string, unknown> | undefined): {
     succeeded: true;
     value: InteractionCancelData;
@@ -85,7 +96,9 @@ declare function parseInteractionCancel(data: Record<string, unknown> | undefine
     succeeded: false;
     error: string;
 };
+/** Determine if a chat interaction field allows free text input */
 declare function fieldAcceptsFreeText(field: ChatInteractionField): boolean;
+/** Define the structure for delivering answers linked to a specific chat interaction and field */
 interface ComposerAnswerDelivery {
     interactionId: string;
     field: ChatInteractionField;
@@ -96,8 +109,11 @@ declare function composerAnswerDeliveries(pending: ChatInteraction[]): ComposerA
 /** Shapes composer text into the respond payload for the routed field
  *  (select answers are string arrays on the wire; text answers are strings). */
 declare function composerAnswerData(field: ChatInteractionField, text: string): InteractionData;
+/** Generate a unique key string for an interaction using the given identifier */
 declare function interactionPartKey(id: string): string;
+/** Generate a unique key string for a notice using the given identifier */
 declare function noticePartKey(id: string): string;
+/** Define specific string literals representing different kinds of notices */
 type NoticeKind = 'warning' | 'auto-declined';
 /**
  * Persisted-part shapes the codecs below produce — the SAME rows
@@ -120,6 +136,7 @@ type InteractionPersistedPart = {
     answers?: InteractionAnswers;
     cancelReason?: string;
 };
+/** Define a persisted notice part with type, id, kind, and text properties */
 type NoticePersistedPart = {
     type: 'notice';
     id: string;