@devaccel-labs/app-comments-toolbar 1.0.0 → 1.3.0

package/src/compiler/annotate.ts

@@ -0,0 +1,202 @@
+import generateModule from "@babel/generator";
+import { parse } from "@babel/parser";
+import * as t from "@babel/types";
+
+/** A parsed Babel node, walked by its `VISITOR_KEYS` without `@babel/traverse`. */
+type WalkNode = { type: string; [key: string]: any };
+
+interface BabelGenerateOptions {
+  retainLines?: boolean;
+  comments?: boolean;
+}
+
+function generate() {
+  const mod = generateModule as unknown as {
+    default?: (ast: unknown, options?: BabelGenerateOptions, code?: string) => { code: string };
+    (ast: unknown, options?: BabelGenerateOptions, code?: string): { code: string };
+  };
+  return mod.default ?? mod;
+}
+
+function isWalkNode(value: unknown): value is WalkNode {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof (value as { type?: unknown }).type === "string"
+  );
+}
+
+export function toProjectPath(filename: string, root: string) {
+  const clean = filename.split("?")[0].replaceAll("\\", "/");
+  const rootClean = root.replaceAll("\\", "/").replace(/\/$/, "");
+  let relative = clean.startsWith(`${rootClean}/`) ? clean.slice(rootClean.length + 1) : clean;
+  if (relative.startsWith("/")) relative = relative.slice(1);
+  return relative;
+}
+
+/**
+ * `ancestors` is the chain from `File` down to the element's parent. Same checks as walking
+ * `path.parentPath` up from the element: the nearest named function or class declaration, or a
+ * function expression assigned to a variable, object property, or class property.
+ */
+function componentName(ancestors: readonly WalkNode[], fallback: string) {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const current = ancestors[i];
+    if (
+      (current.type === "FunctionDeclaration" || current.type === "ClassDeclaration") &&
+      current.id
+    ) {
+      return current.id.name;
+    }
+    if (current.type === "FunctionExpression" || current.type === "ArrowFunctionExpression") {
+      const parent = i > 0 ? ancestors[i - 1] : null;
+      if (parent?.type === "VariableDeclarator" && parent.id.type === "Identifier")
+        return parent.id.name;
+      if (
+        (parent?.type === "ObjectProperty" || parent?.type === "ClassProperty") &&
+        parent.key.type === "Identifier"
+      ) {
+        return parent.key.name;
+      }
+    }
+  }
+  return fallback;
+}
+
+/** No JSX element sits between this one and its enclosing function (`path.getFunctionParent()`). */
+function isRootJsx(ancestors: readonly WalkNode[]) {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const current = ancestors[i];
+    if (t.isFunction(current as t.Node)) return true;
+    if (current.type === "JSXElement") return false;
+  }
+  return false;
+}
+
+function hasAttr(node: WalkNode, name: string) {
+  return node.openingElement.attributes.some(
+    (attr: { type?: string; name?: { type?: string; name?: string } }) =>
+      attr.type === "JSXAttribute" &&
+      attr.name?.type === "JSXIdentifier" &&
+      attr.name.name === name,
+  );
+}
+
+function setAttr(node: WalkNode, name: string, value: string) {
+  if (hasAttr(node, name)) return;
+  node.openingElement.attributes.push(
+    t.jsxAttribute(t.jsxIdentifier(name), t.stringLiteral(value)),
+  );
+}
+
+/** React built-ins that reject or ignore extra props. */
+const REACT_BUILTINS = new Set([
+  "Fragment",
+  "Suspense",
+  "StrictMode",
+  "Profiler",
+  "Activity",
+  "ViewTransition",
+]);
+const contextComponent = /\.(?:Provider|Consumer)$/;
+
+/**
+ * The names this file uses for React's built-ins: `Fragment`, `React.Fragment`, and whatever the
+ * file imports them as (`import { Fragment as Frag }`, `import * as R from "react"` → `R.Fragment`).
+ */
+function reactBuiltinTags(program: WalkNode): ReadonlySet<string> {
+  const tags = new Set<string>();
+  const namespaces = new Set(["React"]);
+  for (const statement of (program.body ?? []) as WalkNode[]) {
+    if (statement.type !== "ImportDeclaration" || statement.source?.value !== "react") continue;
+    for (const specifier of (statement.specifiers ?? []) as WalkNode[]) {
+      const local = specifier.local?.name;
+      if (typeof local !== "string") continue;
+      if (
+        specifier.type === "ImportNamespaceSpecifier" ||
+        specifier.type === "ImportDefaultSpecifier"
+      ) {
+        namespaces.add(local);
+      } else if (specifier.type === "ImportSpecifier") {
+        const imported = specifier.imported?.name ?? specifier.imported?.value;
+        if (REACT_BUILTINS.has(imported)) tags.add(local);
+      }
+    }
+  }
+  for (const builtin of REACT_BUILTINS) {
+    tags.add(builtin);
+    for (const namespace of namespaces) tags.add(`${namespace}.${builtin}`);
+  }
+  return tags;
+}
+
+function jsxName(name: any): string | null {
+  if (t.isJSXIdentifier(name)) return name.name;
+  if (t.isJSXMemberExpression(name)) {
+    const object = jsxName(name.object);
+    return object ? `${object}.${name.property.name}` : null;
+  }
+  return null;
+}
+
+/**
+ * Stamp the root node of each component of each component with a stable file + component name.
+ * Line numbers are intentionally not included: moving the component in the file
+ * or on the page must not change the stamp. A root that is itself a component
+ * (`<DropdownMenu>`, `<Menu.Root>`) gets the stamp as a prop: it reaches the DOM when
+ * the component spreads its props, and the toolbar reads it from React's tree when
+ * the component renders into a portal.
+ */
+export function annotateSource(code: string, filename: string, root: string) {
+  if (!filename.match(/\.[jt]sx$/)) return code;
+  if (filename.includes("node_modules")) return code;
+  let ast: ReturnType<typeof parse>;
+  try {
+    ast = parse(code, {
+      sourceType: "module",
+      plugins: ["jsx", "typescript"],
+    });
+  } catch {
+    return code;
+  }
+  const file = toProjectPath(filename, root);
+  const fallback =
+    file
+      .split("/")
+      .pop()
+      ?.replace(/\.[jt]sx$/, "") || "component";
+  let changed = false;
+  const ancestors: WalkNode[] = [];
+  const builtins = reactBuiltinTags((ast as unknown as WalkNode).program as WalkNode);
+  const stamp = (node: WalkNode) => {
+    const tag = jsxName(node.openingElement.name);
+    if (!tag || builtins.has(tag) || contextComponent.test(tag)) return;
+    if (!isRootJsx(ancestors)) return;
+    const name = componentName(ancestors, fallback);
+    const before = node.openingElement.attributes.length;
+    setAttr(node, "data-cs-cmp", name);
+    setAttr(node, "data-cs-file", file);
+    if (node.openingElement.attributes.length !== before) changed = true;
+  };
+  // Walks the AST directly instead of through `@babel/traverse`: its NodePath and scope
+  // bookkeeping was most of the plugin's build cost (2026-10-24: 2.67 s → 0.86 s over
+  // apps/workspace). Same visit order (`VISITOR_KEYS`, pre-order, an element is stamped before
+  // its children are walked), so the output is byte-identical to the traverse version.
+  const visit = (node: WalkNode) => {
+    if (node.type === "JSXElement") stamp(node);
+    ancestors.push(node);
+    for (const key of t.VISITOR_KEYS[node.type] ?? []) {
+      const child = node[key];
+      if (Array.isArray(child)) {
+        for (const item of child) if (isWalkNode(item)) visit(item);
+      } else if (isWalkNode(child)) {
+        visit(child);
+      }
+    }
+    ancestors.pop();
+  };
+  visit(ast as unknown as WalkNode);
+  if (!changed) return code;
+  const printed = generate()(ast, { retainLines: true, comments: true }, code);
+  return printed.code;
+}

package/src/compiler/babel.d.ts

@@ -0,0 +1,11 @@
+declare module "@babel/generator" {
+  interface GenerateResult {
+    code: string
+  }
+  const generate: (
+    ast: unknown,
+    options?: Record<string, unknown>,
+    code?: string,
+  ) => GenerateResult
+  export default generate
+}

package/src/compiler/enabled.ts

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/** A host app that serves the toolbar sets this, in its env files, its Wrangler `vars`, or the build's environment. */
+export const CONFIG_KEY = "COMMENT_SERVICE_URL";
+
+/**
+ * Whether to stamp components. An explicit option or COMMENT_SERVICE_ENABLED wins; otherwise the dev server always
+ * stamps, and a build stamps only when it can see comment-service configuration.
+ */
+export function stampingEnabled({
+  option,
+  flag,
+  command,
+  configured,
+}: {
+  option: boolean | undefined;
+  flag: string | undefined;
+  command: "build" | "serve";
+  configured: () => boolean;
+}) {
+  if (option !== undefined) return option;
+  if (flag === "0" || flag === "false") return false;
+  if (flag === "1" || flag === "true") return true;
+  return command === "serve" || configured();
+}
+
+/** Comment-service configuration a build can see: its environment, Vite env files for the mode, or Wrangler config. */
+export function buildConfigured(
+  root: string,
+  mode: string,
+  env: Record<string, string | undefined> = process.env,
+) {
+  if (env[CONFIG_KEY]) return true;
+  const read = (file: string) => {
+    try {
+      return fs.readFileSync(path.join(root, file), "utf8");
+    } catch {
+      return "";
+    }
+  };
+  const assignment = new RegExp(`^\\s*(?:export\\s+)?${CONFIG_KEY}\\s*=\\s*\\S`, "m");
+  if (
+    [".env", ".env.local", `.env.${mode}`, `.env.${mode}.local`].some((file) =>
+      assignment.test(read(file)),
+    )
+  )
+    return true;
+  const jsonKey = new RegExp(`^\\s*"${CONFIG_KEY}"\\s*:`, "m");
+  const tomlKey = new RegExp(`^\\s*${CONFIG_KEY}\\s*=`, "m");
+  return (
+    jsonKey.test(read("wrangler.jsonc") + read("wrangler.json")) ||
+    tomlKey.test(read("wrangler.toml"))
+  );
+}

package/src/compiler/index.ts

@@ -0,0 +1,2 @@
+export { annotateSource, toProjectPath } from "./annotate.js";
+export { CONFIG_KEY, buildConfigured, stampingEnabled } from "./enabled.js";

package/src/core/index.ts

@@ -0,0 +1,8 @@
+export {
+  describeAnchor,
+  dropAncestors,
+  resolveAnchor,
+  validateAnchor,
+  validateSketch,
+} from "./resolve.js";
+export type { Anchor, Candidate, Resolution, ResolutionStatus, Sketch } from "./types.js";

package/src/core/resolve.ts

@@ -0,0 +1,307 @@
+import type { Anchor, Candidate, Resolution, ResolutionStatus, Sketch } from "./types.js";
+
+const norm = (value: string | null | undefined) =>
+  (value ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+
+const labelOf = (value: { accName: string | null; text: string | null }) =>
+  norm(value.accName) || norm(value.text);
+
+/**
+ * A path is an ancestor of another when it is a strict prefix ("0/1" contains "0/1/4").
+ * Equal paths are the same element, not a nesting relationship.
+ */
+function isAncestorPath(ancestor: string, descendant: string) {
+  if (!ancestor || ancestor === descendant) return false;
+  return descendant.startsWith(`${ancestor}/`);
+}
+
+/**
+ * Drop elements that contain another match, so a wrapping div doesn't steal the button.
+ *
+ * Sorted by path, an element's descendants ("0/1/…") come directly after it: "/" sorts before every digit, so
+ * nothing else can sit between "0/1" and "0/1/4". One pass over the sorted list finds every ancestor, instead of
+ * comparing every pair; a page section with thousands of elements used to take seconds here.
+ */
+export function dropAncestors(candidates: Candidate[]) {
+  if (candidates.length < 2) return candidates;
+  const order = candidates.map((candidate, index) => ({ index, path: candidate.path }));
+  order.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const dropped = new Set<number>();
+  for (const [i, { index, path }] of order.entries()) {
+    let next = i + 1;
+    while (order[next]?.path === path) next++;
+    const after = order[next];
+    if (after && isAncestorPath(path, after.path)) dropped.add(index);
+  }
+  return dropped.size ? candidates.filter((_, index) => !dropped.has(index)) : candidates;
+}
+
+/** The one candidate in `list`, or null when there are none or several. */
+function single(list: readonly Candidate[]): Candidate | null {
+  return list.length === 1 ? (list[0] ?? null) : null;
+}
+
+function finish(
+  status: ResolutionStatus,
+  candidate: Candidate | null,
+  score: number,
+  reason: string,
+): Resolution {
+  if (candidate && !candidate.visible && (status === "pinned" || status === "drifted")) {
+    return { status: "hidden", key: candidate.key, score, reason: `hidden: ${reason}` };
+  }
+  return { status, key: candidate?.key ?? null, score, reason };
+}
+
+function sameExplicit(anchor: Anchor, candidate: Candidate) {
+  return anchor.explicit.some((expected) =>
+    candidate.explicit.some(
+      (actual) => actual.attr === expected.attr && actual.value === expected.value,
+    ),
+  );
+}
+
+function sameComponent(anchor: Anchor, candidate: Candidate, requireFile: boolean) {
+  if (!anchor.component || !candidate.component) return false;
+  if (anchor.component.name !== candidate.component.name) return false;
+  if (requireFile) {
+    return Boolean(anchor.component.file) && anchor.component.file === candidate.component.file;
+  }
+  return true;
+}
+
+function sameRole(anchor: Anchor, candidate: Candidate) {
+  if (!anchor.role || !candidate.role) return !anchor.role;
+  return anchor.role === candidate.role;
+}
+
+function sameLabel(anchor: Anchor, candidate: Candidate) {
+  const expected = labelOf(anchor);
+  if (!expected) return false;
+  return expected === labelOf(candidate);
+}
+
+function unavailable(reason: string): Resolution {
+  return { status: "unavailable", key: null, score: 0, reason };
+}
+
+/**
+ * Resolve a stored anchor against the elements currently on the route.
+ *
+ * Order is deliberate:
+ * 1. An explicit id (`data-cs-anchor`, `data-testid`, stable `id`) wins.
+ * 2. Otherwise the match is component file + component name + role + label.
+ * 3. Sibling index and pixel position are ignored, so inserting, reordering,
+ *    or moving the element (including out of a sheet) does not retarget the comment.
+ * 4. A tie is ambiguous. We do not fall back to "the first one" or the old index.
+ * 5. A unique component whose label changed is "drifted": still shown, marked uncertain.
+ * 6. A match that exists but is inside a closed dialog is "hidden", not deleted.
+ * 7. No match is "unavailable". The thread stays in the inbox.
+ *
+ * `candidates` may be a targeted subset of the page, as long as it holds every element with one of the anchor's
+ * explicit ids and every element owned by a component of the anchor's name. The drift check looks at everything
+ * inside the component's root, so such callers pass `inside` to supply those candidates on demand.
+ */
+export function resolveAnchor(
+  anchor: Anchor,
+  candidates: Candidate[],
+  inside: (root: Candidate) => Candidate[] = () => candidates,
+): Resolution {
+  const pool = candidates.filter((candidate) => candidate.route === anchor.route);
+  if (anchor.explicit.length > 0) {
+    const hits = dropAncestors(pool.filter((candidate) => sameExplicit(anchor, candidate)));
+    const hit = single(hits);
+    if (hit) return finish("pinned", hit, 100, "explicit id");
+    if (hits.length > 1) {
+      return {
+        status: "ambiguous",
+        key: null,
+        score: 40,
+        reason: "explicit id matches more than one element",
+      };
+    }
+  }
+
+  const componentScoped = pool.filter(
+    (candidate) => sameComponent(anchor, candidate, true) && sameRole(anchor, candidate),
+  );
+  const labeled = dropAncestors(
+    componentScoped.filter((candidate) => sameLabel(anchor, candidate)),
+  );
+  const label = single(labeled);
+  if (label) return finish("pinned", label, 100, "component file, role, and label");
+  if (labeled.length > 1) {
+    return {
+      status: "ambiguous",
+      key: null,
+      score: 50,
+      reason: "several elements in this component share the same label",
+    };
+  }
+
+  if (anchor.component?.file && anchor.component.name) {
+    const roots = pool.filter(
+      (candidate) => candidate.componentRoot && sameComponent(anchor, candidate, true),
+    );
+    const root = single(roots);
+    if (root) {
+      const within = dropAncestors(
+        inside(root).filter(
+          (candidate) =>
+            candidate.route === anchor.route &&
+            (candidate.path === root.path || isAncestorPath(root.path, candidate.path)) &&
+            sameRole(anchor, candidate),
+        ),
+      );
+      const moved = single(within);
+      if (moved) return finish("drifted", moved, 70, "same component and role, label changed");
+      const where = anchor.overlay
+        ? ` Last seen in ${anchor.overlay.role} “${anchor.overlay.name}”.`
+        : "";
+      return unavailable(`label no longer matches inside ${anchor.component.name}.${where}`.trim());
+    }
+    if (roots.length === 0) {
+      const where = anchor.overlay
+        ? ` Last seen in ${anchor.overlay.role} “${anchor.overlay.name}”.`
+        : "";
+      return unavailable(
+        `component ${anchor.component.name} is not on ${anchor.route}.${where}`.trim(),
+      );
+    }
+    return {
+      status: "ambiguous",
+      key: null,
+      score: 45,
+      reason: "component is on the page more than once and the label no longer matches",
+    };
+  }
+
+  // Dev fallback when the compiler didn't stamp a file: component name + label.
+  if (anchor.component?.name) {
+    const named = dropAncestors(
+      pool.filter(
+        (candidate) =>
+          sameComponent(anchor, candidate, false) &&
+          sameRole(anchor, candidate) &&
+          sameLabel(anchor, candidate),
+      ),
+    );
+    const name = single(named);
+    if (name) return finish("pinned", name, 80, "component name and label");
+    if (named.length > 1) {
+      return {
+        status: "ambiguous",
+        key: null,
+        score: 40,
+        reason: "component name and label match more than one element",
+      };
+    }
+  }
+
+  const where = anchor.overlay
+    ? ` It was inside ${anchor.overlay.role} “${anchor.overlay.name}”.`
+    : "";
+  return unavailable(`no element on ${anchor.route} matches this comment.${where}`.trim());
+}
+
+export function describeAnchor(anchor: Anchor) {
+  const component = anchor.component
+    ? `${anchor.component.name}${anchor.component.file ? ` · ${anchor.component.file}` : ""}`
+    : anchor.tag;
+  const label = anchor.accName || anchor.text;
+  return label ? `${component} — ${label}` : component;
+}
+
+export function validateAnchor(input: unknown): Anchor | null {
+  if (!input || typeof input !== "object") return null;
+  const value = input as Partial<Anchor>;
+  if (value.v !== 1) return null;
+  if (typeof value.route !== "string" || !value.route.startsWith("/") || value.route.length > 500)
+    return null;
+  if (typeof value.tag !== "string" || value.tag.length > 40) return null;
+  const explicit = Array.isArray(value.explicit) ? value.explicit : [];
+  if (explicit.length > 8) return null;
+  if (
+    explicit.some(
+      (item) =>
+        !item ||
+        typeof item !== "object" ||
+        typeof item.attr !== "string" ||
+        typeof item.value !== "string" ||
+        item.attr.length > 40 ||
+        item.value.length > 200,
+    )
+  ) {
+    return null;
+  }
+  const component = value.component;
+  if (
+    component !== null &&
+    component !== undefined &&
+    (typeof component !== "object" ||
+      typeof component.name !== "string" ||
+      (component.file !== null &&
+        component.file !== undefined &&
+        typeof component.file !== "string"))
+  ) {
+    return null;
+  }
+  const clip = (text: unknown, max: number) =>
+    typeof text === "string" ? text.slice(0, max) : null;
+  const sketch = value.sketch === undefined ? null : validateSketch(value.sketch);
+  if (value.sketch !== undefined && !sketch) return null;
+  return {
+    v: 1,
+    route: value.route,
+    overlay:
+      value.overlay &&
+      typeof value.overlay === "object" &&
+      typeof value.overlay.role === "string" &&
+      typeof value.overlay.name === "string"
+        ? { role: value.overlay.role.slice(0, 40), name: value.overlay.name.slice(0, 120) }
+        : null,
+    explicit: explicit.map((item) => ({ attr: item.attr, value: item.value })),
+    component: component
+      ? {
+          name: component.name.slice(0, 120),
+          file: component.file ? component.file.slice(0, 300) : null,
+        }
+      : null,
+    stack: Array.isArray(value.stack)
+      ? value.stack.filter((item): item is string => typeof item === "string").slice(0, 16)
+      : [],
+    role: clip(value.role, 40),
+    accName: clip(value.accName, 160),
+    text: clip(value.text, 160),
+    tag: value.tag,
+    intra: clip(value.intra, 300),
+    ...(sketch ? { sketch } : {}),
+  };
+}
+
+/** Most strokes, and numbers per stroke, a drawing keeps. */
+const SKETCH_PATHS = 8;
+const SKETCH_NUMBERS = 600;
+/** Coordinates and sizes outside this many pixels either way are not a drawing on a page. */
+const SKETCH_RANGE = 20_000;
+
+export function validateSketch(input: unknown): Sketch | null {
+  if (!input || typeof input !== "object") return null;
+  const value = input as Partial<Sketch>;
+  const size = (n: unknown) =>
+    typeof n === "number" && Number.isFinite(n) && n >= 0 && n <= SKETCH_RANGE;
+  if (!size(value.w) || !size(value.h)) return null;
+  if (!Array.isArray(value.paths) || !value.paths.length || value.paths.length > SKETCH_PATHS)
+    return null;
+  const paths: number[][] = [];
+  for (const path of value.paths) {
+    if (!Array.isArray(path) || path.length < 4 || path.length > SKETCH_NUMBERS || path.length % 2)
+      return null;
+    if (
+      path.some((n) => typeof n !== "number" || !Number.isFinite(n) || Math.abs(n) > SKETCH_RANGE)
+    )
+      return null;
+    paths.push(path.map((n: number) => Math.round(n)));
+  }
+  return { w: Math.round(value.w as number), h: Math.round(value.h as number), paths };
+}

package/src/core/types.ts

@@ -0,0 +1,58 @@
+/** Stable identity for a commented element. Pixel and DOM-index position are not part of the match. */
+export type Anchor = {
+  v: 1;
+  /** Pathname only, no query or hash. */
+  route: string;
+  /**
+   * Dialog or sheet the element lived in when the comment was written.
+   * Used to explain a hidden thread. Not required to match after the element moves out of the overlay.
+   */
+  overlay: { role: string; name: string } | null;
+  /** Opt-in stable ids: data-cs-anchor, data-testid, or a human id. Highest priority. */
+  explicit: Array<{ attr: string; value: string }>;
+  /** React component that owns the element. File path is relative and has no line number. */
+  component: { name: string; file: string | null } | null;
+  /** Component names from the tree, outer to inner. Diagnostic. */
+  stack: string[];
+  role: string | null;
+  accName: string | null;
+  text: string | null;
+  tag: string;
+  /** Sibling path inside the component. Stored for agents, never used to choose a match. */
+  intra: string | null;
+  /** A freehand drawing the comment was left with. Never used to choose a match. */
+  sketch?: Sketch;
+};
+
+/**
+ * Strokes drawn on the page, in CSS pixels from the top-left corner of the anchored element.
+ * Each path is a flat list of x, y pairs. `w` and `h` are the element's size when it was drawn.
+ */
+export type Sketch = { w: number; h: number; paths: number[][] };
+
+export type Candidate = {
+  key: string;
+  route: string;
+  visible: boolean;
+  /** Index path from the document body. Used only to tell ancestors from descendants. */
+  path: string;
+  componentRoot: boolean;
+  overlay: { role: string; name: string } | null;
+  explicit: Array<{ attr: string; value: string }>;
+  component: { name: string; file: string | null } | null;
+  stack: string[];
+  role: string | null;
+  accName: string | null;
+  text: string | null;
+  tag: string;
+  intra: string | null;
+};
+
+export type ResolutionStatus = "pinned" | "drifted" | "hidden" | "ambiguous" | "unavailable";
+
+export type Resolution = {
+  status: ResolutionStatus;
+  key: string | null;
+  score: number;
+  reason: string;
+};

package/src/debug-context.ts

@@ -0,0 +1,47 @@
+/**
+ * The debug context file a comment carries (`context-<stamp>.json`), for an inbox, a destination and the
+ * service: read it back safely, redact it again, and turn it into the brief a coding agent reads. DOM-free, so
+ * a Worker can import it. Source only, like `./replay`: not built into `dist`.
+ */
+export {
+  DEBUG_CONTEXT_MAX_BYTES,
+  DEBUG_CONTEXT_PREFIX,
+  DEBUG_SIGNALS,
+  DEFAULT_SIGNALS,
+  OPT_IN_SIGNALS,
+  debugContextBrief,
+  debugContextBytes,
+  debugContextKey,
+  debugContextName,
+  fitDebugContext,
+  isDebugContextName,
+  liveDebugOptions,
+  newReportId,
+  resolveDebugContext,
+  sanitizeDebugContext,
+  type BriefMeta,
+  type DebugAudience,
+  type DebugContextConfig,
+  type DebugContextFile,
+  type DebugContextOptions,
+  type DebugError,
+  type DebugRequest,
+  type DebugSignal,
+  type DebugStep,
+  type HostBuild,
+  type HostContext,
+  type QuerySummary,
+  type RealtimeState,
+  type ResolvedDebugContext,
+} from "./runtime/debug-context-model.js";
+export {
+  ID_HEADERS,
+  idHeaderNames,
+  newTally,
+  scrubId,
+  scrubText,
+  scrubUrl,
+  scrubValue,
+  type JsonBag,
+  type RedactionTally,
+} from "./runtime/debug-context-redact.js";