@agent-surface/testing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wiseair S.r.l.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @agent-surface/testing
+
+Deterministic testing toolkit for [agent-surface](https://github.com/Wiseair-srl/agent-surface). The surface is a typed contract; contracts are tested deterministically — **no test in this ecosystem requires an LLM**.
+
+Docs: https://agent-surface-docs.vercel.app
+
+## Install
+
+```bash
+pnpm add -D @agent-surface/testing
+```
+
+## Use
+
+```tsx
+import { renderAgentSurface } from "@agent-surface/testing/react";
+import { matchers } from "@agent-surface/testing/matchers";
+expect.extend(matchers);
+
+it("exposes the documented surface", async () => {
+  const s = await renderAgentSurface(<DevicesPage />);
+  expect(s).toExpose("view:devices.table.selectRows");
+  expect(s).toExposeUnavailable("domain:devices.disable", {
+    reason: "Select at least one device first",
+  });
+  expect(s).toMatchSurfaceSnapshot(); // reviewable "what agents can see" artifact
+});
+
+it("runs the full disable flow", async () => {
+  const s = await renderAgentSurface(<DevicesPage />);
+  await s.invoke("view:devices.table.selectRows", { ids: ["d1"] });
+  let r = await s.invoke("domain:devices.disable", {});
+  expect(r).toFailWith("CONFIRMATION_REQUIRED");
+  s.confirmations.approve();
+  r = await s.invoke("domain:devices.disable", {}, {
+    confirmationId: r.error.details!.confirmationId as string,
+  });
+  expect(r).toBeOk();
+});
+```
+
+`createTestSurface` (framework-free) drives a bare registry the same way. Semantic snapshots normalize volatility (`registrationId` → `<reg#N>`), so they survive Strict Mode and remounts. Matchers distinguish *hidden* from *visible-disabled* — that distinction is the security model.
+
+Full specification: [docs/08](https://github.com/Wiseair-srl/agent-surface/blob/main/docs/08-testing.md).
+
+MIT © Wiseair S.r.l.

package/dist/chunk-2E5UCTGQ.js

@@ -0,0 +1,173 @@
+// src/matchers.ts
+import { jsonDeepEqual } from "@agent-surface/core";
+
+// src/serialize.ts
+function serializeSurfaceSnapshot(snapshot, options) {
+  const regIdMap = /* @__PURE__ */ new Map();
+  const normalizeRegId = (id) => {
+    let placeholder = regIdMap.get(id);
+    if (!placeholder) {
+      placeholder = `<reg#${regIdMap.size + 1}>`;
+      regIdMap.set(id, placeholder);
+    }
+    return placeholder;
+  };
+  return {
+    ...options?.includeVersion ? { surfaceVersion: snapshot.surfaceVersion } : {},
+    ...snapshot.route ? { route: snapshot.route } : {},
+    components: snapshot.components.map((component) => ({
+      ...component,
+      registrationId: normalizeRegId(component.registrationId)
+    })),
+    procedures: snapshot.procedures.map((procedure) => ({
+      ...procedure,
+      registrationId: normalizeRegId(procedure.registrationId)
+    })),
+    ...snapshot.truncated ? { truncated: snapshot.truncated } : {}
+  };
+}
+
+// src/matchers.ts
+function isTestSurface(value) {
+  return typeof value === "object" && value !== null && typeof value.snapshot === "function" && typeof value.invoke === "function";
+}
+function collectCapabilities(snapshot) {
+  const entries = [];
+  for (const component of snapshot.components) {
+    for (const cap of [...component.observations, ...component.actions]) {
+      entries.push({
+        capabilityId: cap.capabilityId,
+        available: cap.available,
+        unavailableReason: cap.unavailableReason,
+        instanceId: component.instanceId
+      });
+    }
+  }
+  for (const proc of snapshot.procedures) {
+    entries.push({
+      capabilityId: proc.procedureId,
+      available: proc.available,
+      unavailableReason: proc.unavailableReason,
+      ...proc.context ? { instanceId: proc.context.instanceId } : {}
+    });
+  }
+  return entries;
+}
+function findEntries(surface, capabilityId, opts) {
+  const snapshot = surface.snapshot();
+  return collectCapabilities(snapshot).filter(
+    (e) => e.capabilityId === capabilityId && (opts?.instanceId === void 0 || e.instanceId === opts.instanceId)
+  );
+}
+function toExpose(received, capabilityId, opts) {
+  if (!isTestSurface(received)) {
+    return { pass: false, message: () => "toExpose expects a TestSurface" };
+  }
+  const entries = findEntries(received, capabilityId, opts);
+  const pass = entries.some((e) => e.available);
+  return {
+    pass,
+    message: () => pass ? `expected surface not to expose ${capabilityId}, but it is exposed and available` : entries.length > 0 ? `expected ${capabilityId} to be available, but it is visible-disabled (${entries[0]?.unavailableReason ?? "no reason"})` : `expected surface to expose ${capabilityId}, but it is absent (hidden or unregistered)`
+  };
+}
+function toExposeUnavailable(received, capabilityId, opts) {
+  if (!isTestSurface(received)) {
+    return { pass: false, message: () => "toExposeUnavailable expects a TestSurface" };
+  }
+  const entries = findEntries(received, capabilityId, opts);
+  const disabled = entries.filter((e) => !e.available);
+  const pass = disabled.length > 0 && (opts?.reason === void 0 || disabled.some((e) => e.unavailableReason === opts.reason));
+  return {
+    pass,
+    message: () => {
+      if (entries.length === 0) {
+        return `expected ${capabilityId} to be visible-disabled, but it is absent from the snapshot (hidden)`;
+      }
+      if (disabled.length === 0) {
+        return `expected ${capabilityId} to be visible-disabled, but it is available`;
+      }
+      return `expected ${capabilityId} unavailableReason ${JSON.stringify(opts?.reason)}, got ${JSON.stringify(disabled[0]?.unavailableReason)}`;
+    }
+  };
+}
+function toBeOk(received) {
+  const result = received;
+  const pass = typeof result === "object" && result !== null && result.status === "ok";
+  return {
+    pass,
+    message: () => pass ? "expected invocation result not to be ok" : `expected ok result, got ${JSON.stringify(
+      result?.error ?? result
+    )}`
+  };
+}
+function toFailWith(received, code, detailsSubset) {
+  const result = received;
+  if (typeof result !== "object" || result === null || result.status !== "error") {
+    return {
+      pass: false,
+      message: () => `expected an error result with code ${code}, got ${JSON.stringify(result)}`
+    };
+  }
+  if (result.error.code !== code) {
+    return {
+      pass: false,
+      message: () => `expected error code ${code}, got ${result.error.code} (${result.error.message})`
+    };
+  }
+  if (detailsSubset) {
+    for (const [key, expected] of Object.entries(detailsSubset)) {
+      const actual = result.error.details?.[key];
+      if (!jsonDeepEqual(actual, expected)) {
+        return {
+          pass: false,
+          message: () => `expected details.${key} = ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`
+        };
+      }
+    }
+  }
+  return { pass: true, message: () => `expected result not to fail with ${code}` };
+}
+function toMatchSurfaceSnapshot(received) {
+  if (!isTestSurface(received)) {
+    return { pass: false, message: () => "toMatchSurfaceSnapshot expects a TestSurface" };
+  }
+  const normalized = serializeSurfaceSnapshot(received.snapshot());
+  const expectFn = globalThis.expect;
+  if (!expectFn) {
+    return {
+      pass: false,
+      message: () => "toMatchSurfaceSnapshot requires a global expect with snapshot support (vitest globals or jest)"
+    };
+  }
+  try {
+    expectFn(normalized).toMatchSnapshot();
+    return { pass: true, message: () => "surface snapshot matched" };
+  } catch (err) {
+    return {
+      pass: false,
+      message: () => err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+var matchers = {
+  toExpose,
+  toExposeUnavailable,
+  toBeOk,
+  toFailWith,
+  toMatchSurfaceSnapshot
+};
+var globalExpect = globalThis.expect;
+if (globalExpect?.extend) {
+  globalExpect.extend(matchers);
+}
+
+export {
+  serializeSurfaceSnapshot,
+  toExpose,
+  toExposeUnavailable,
+  toBeOk,
+  toFailWith,
+  toMatchSurfaceSnapshot,
+  matchers
+};
+//# sourceMappingURL=chunk-2E5UCTGQ.js.map

package/dist/chunk-2E5UCTGQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/matchers.ts","../src/serialize.ts"],"sourcesContent":["import type {\n  AgentCapabilityErrorCode,\n  AgentInvocationResult,\n  AgentSurfaceSnapshot,\n  JsonValue,\n} from \"@agent-surface/core\";\nimport { jsonDeepEqual } from \"@agent-surface/core\";\nimport type { TestSurface } from \"./harness.js\";\nimport { serializeSurfaceSnapshot } from \"./serialize.js\";\n\ninterface MatcherResult {\n  pass: boolean;\n  message: () => string;\n}\n\ninterface CapabilityEntry {\n  capabilityId: string;\n  available: boolean;\n  unavailableReason?: string;\n  instanceId?: string;\n}\n\nfunction isTestSurface(value: unknown): value is TestSurface {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as TestSurface).snapshot === \"function\" &&\n    typeof (value as TestSurface).invoke === \"function\"\n  );\n}\n\nfunction collectCapabilities(snapshot: AgentSurfaceSnapshot): CapabilityEntry[] {\n  const entries: CapabilityEntry[] = [];\n  for (const component of snapshot.components) {\n    for (const cap of [...component.observations, ...component.actions]) {\n      entries.push({\n        capabilityId: cap.capabilityId,\n        available: cap.available,\n        unavailableReason: cap.unavailableReason,\n        instanceId: component.instanceId,\n      });\n    }\n  }\n  for (const proc of snapshot.procedures) {\n    entries.push({\n      capabilityId: proc.procedureId,\n      available: proc.available,\n      unavailableReason: proc.unavailableReason,\n      ...(proc.context ? { instanceId: proc.context.instanceId } : {}),\n    });\n  }\n  return entries;\n}\n\nfunction findEntries(\n  surface: TestSurface,\n  capabilityId: string,\n  opts?: { instanceId?: string },\n): CapabilityEntry[] {\n  const snapshot = surface.snapshot();\n  return collectCapabilities(snapshot).filter(\n    (e) =>\n      e.capabilityId === capabilityId &&\n      (opts?.instanceId === undefined || e.instanceId === opts.instanceId),\n  );\n}\n\n/**\n * `toExpose` = present AND available for the harness consumer.\n * Hidden ≠ disabled: that distinction is the security model (docs/06).\n */\nexport function toExpose(\n  received: unknown,\n  capabilityId: string,\n  opts?: { instanceId?: string },\n): MatcherResult {\n  if (!isTestSurface(received)) {\n    return { pass: false, message: () => \"toExpose expects a TestSurface\" };\n  }\n  const entries = findEntries(received, capabilityId, opts);\n  const pass = entries.some((e) => e.available);\n  return {\n    pass,\n    message: () =>\n      pass\n        ? `expected surface not to expose ${capabilityId}, but it is exposed and available`\n        : entries.length > 0\n          ? `expected ${capabilityId} to be available, but it is visible-disabled (${entries[0]?.unavailableReason ?? \"no reason\"})`\n          : `expected surface to expose ${capabilityId}, but it is absent (hidden or unregistered)`,\n  };\n}\n\n/** `toExposeUnavailable` = present with available: false (+ optional reason). */\nexport function toExposeUnavailable(\n  received: unknown,\n  capabilityId: string,\n  opts?: { instanceId?: string; reason?: string },\n): MatcherResult {\n  if (!isTestSurface(received)) {\n    return { pass: false, message: () => \"toExposeUnavailable expects a TestSurface\" };\n  }\n  const entries = findEntries(received, capabilityId, opts);\n  const disabled = entries.filter((e) => !e.available);\n  const pass =\n    disabled.length > 0 &&\n    (opts?.reason === undefined || disabled.some((e) => e.unavailableReason === opts.reason));\n  return {\n    pass,\n    message: () => {\n      if (entries.length === 0) {\n        return `expected ${capabilityId} to be visible-disabled, but it is absent from the snapshot (hidden)`;\n      }\n      if (disabled.length === 0) {\n        return `expected ${capabilityId} to be visible-disabled, but it is available`;\n      }\n      return `expected ${capabilityId} unavailableReason ${JSON.stringify(opts?.reason)}, got ${JSON.stringify(disabled[0]?.unavailableReason)}`;\n    },\n  };\n}\n\nexport function toBeOk(received: unknown): MatcherResult {\n  const result = received as AgentInvocationResult;\n  const pass =\n    typeof result === \"object\" && result !== null && (result as { status?: string }).status === \"ok\";\n  return {\n    pass,\n    message: () =>\n      pass\n        ? \"expected invocation result not to be ok\"\n        : `expected ok result, got ${JSON.stringify(\n            (result as { error?: unknown })?.error ?? result,\n          )}`,\n  };\n}\n\nexport function toFailWith(\n  received: unknown,\n  code: AgentCapabilityErrorCode,\n  detailsSubset?: Record<string, JsonValue>,\n): MatcherResult {\n  const result = received as AgentInvocationResult;\n  if (typeof result !== \"object\" || result === null || result.status !== \"error\") {\n    return {\n      pass: false,\n      message: () => `expected an error result with code ${code}, got ${JSON.stringify(result)}`,\n    };\n  }\n  if (result.error.code !== code) {\n    return {\n      pass: false,\n      message: () =>\n        `expected error code ${code}, got ${result.error.code} (${result.error.message})`,\n    };\n  }\n  if (detailsSubset) {\n    for (const [key, expected] of Object.entries(detailsSubset)) {\n      const actual = result.error.details?.[key];\n      if (!jsonDeepEqual(actual, expected)) {\n        return {\n          pass: false,\n          message: () =>\n            `expected details.${key} = ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,\n        };\n      }\n    }\n  }\n  return { pass: true, message: () => `expected result not to fail with ${code}` };\n}\n\n/**\n * Semantic surface snapshot matcher. Delegates to the runner's own\n * toMatchSnapshot on the normalized form; `serializeSurfaceSnapshot` is the\n * underlying primitive if you prefer explicit snapshots.\n */\nexport function toMatchSurfaceSnapshot(received: unknown): MatcherResult {\n  if (!isTestSurface(received)) {\n    return { pass: false, message: () => \"toMatchSurfaceSnapshot expects a TestSurface\" };\n  }\n  const normalized = serializeSurfaceSnapshot(received.snapshot());\n  const expectFn = (globalThis as { expect?: (v: unknown) => { toMatchSnapshot(): void } }).expect;\n  if (!expectFn) {\n    return {\n      pass: false,\n      message: () =>\n        \"toMatchSurfaceSnapshot requires a global expect with snapshot support (vitest globals or jest)\",\n    };\n  }\n  try {\n    expectFn(normalized).toMatchSnapshot();\n    return { pass: true, message: () => \"surface snapshot matched\" };\n  } catch (err) {\n    return {\n      pass: false,\n      message: () => (err instanceof Error ? err.message : String(err)),\n    };\n  }\n}\n\nexport const matchers = {\n  toExpose,\n  toExposeUnavailable,\n  toBeOk,\n  toFailWith,\n  toMatchSurfaceSnapshot,\n};\n\n/**\n * Matcher surface for `expect.extend(matchers)`. Augment your test runner's\n * Assertion interface with this shape, e.g. for vitest:\n *\n *   declare module \"vitest\" {\n *     interface Assertion<T = any> extends AgentSurfaceMatchers<T> {}\n *   }\n */\nexport interface AgentSurfaceMatchers<R = unknown> {\n  toExpose(capabilityId: string, opts?: { instanceId?: string }): R;\n  toExposeUnavailable(\n    capabilityId: string,\n    opts?: { instanceId?: string; reason?: string },\n  ): R;\n  toBeOk(): R;\n  toFailWith(code: AgentCapabilityErrorCode, detailsSubset?: Record<string, JsonValue>): R;\n  toMatchSurfaceSnapshot(): R;\n}\n\n// Auto-extend when a global expect (vitest globals / jest) is present.\nconst globalExpect = (globalThis as { expect?: { extend?: (m: object) => void } }).expect;\nif (globalExpect?.extend) {\n  globalExpect.extend(matchers);\n}\n","import type { AgentSurfaceSnapshot } from \"@agent-surface/core\";\n\nexport interface SerializeSurfaceOptions {\n  /** Include surfaceVersion in the output. Default false (volatile). */\n  includeVersion?: boolean;\n}\n\n/**\n * Semantic snapshot serialization (docs/08): registrationIds become stable\n * placeholders in first-appearance order (`<reg#1>`, `<reg#2>` …);\n * surfaceId/capturedAt are dropped; surfaceVersion dropped by default;\n * components/capabilities keep the canonical registry ordering; schemas are\n * included verbatim — schema drift is exactly what these snapshots catch.\n */\nexport function serializeSurfaceSnapshot(\n  snapshot: AgentSurfaceSnapshot,\n  options?: SerializeSurfaceOptions,\n): Record<string, unknown> {\n  const regIdMap = new Map<string, string>();\n  const normalizeRegId = (id: string): string => {\n    let placeholder = regIdMap.get(id);\n    if (!placeholder) {\n      placeholder = `<reg#${regIdMap.size + 1}>`;\n      regIdMap.set(id, placeholder);\n    }\n    return placeholder;\n  };\n\n  return {\n    ...(options?.includeVersion ? { surfaceVersion: snapshot.surfaceVersion } : {}),\n    ...(snapshot.route ? { route: snapshot.route } : {}),\n    components: snapshot.components.map((component) => ({\n      ...component,\n      registrationId: normalizeRegId(component.registrationId),\n    })),\n    procedures: snapshot.procedures.map((procedure) => ({\n      ...procedure,\n      registrationId: normalizeRegId(procedure.registrationId),\n    })),\n    ...(snapshot.truncated ? { truncated: snapshot.truncated } : {}),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-QV7I5CCY.js

@@ -0,0 +1,127 @@
+// src/harness.ts
+import {
+  createAgentSurfaceRegistry,
+  memoryAuditSink
+} from "@agent-surface/core";
+function createTestSurface(options) {
+  const hostRef = { current: options?.host ?? {} };
+  const consumer = options?.consumer ?? { id: "test", kind: "test" };
+  const auditSink = memoryAuditSink({ capacity: 5e3 });
+  const ownsRegistry = options?.registry === void 0;
+  const registry = options?.registry ?? createAgentSurfaceRegistry({
+    environment: "test",
+    context: () => hostRef.current,
+    audit: auditSink
+  });
+  const events = [];
+  const unsubscribe = registry.subscribe((event) => {
+    events.push(event);
+  });
+  function resolveRegistrationId(capabilityId, instanceId) {
+    const snapshot = registry.snapshot({ consumer });
+    const matches = [];
+    for (const component of snapshot.components) {
+      if (instanceId !== void 0 && component.instanceId !== instanceId) continue;
+      const caps = [...component.observations, ...component.actions];
+      if (caps.some((c) => c.capabilityId === capabilityId)) {
+        matches.push(component.registrationId);
+      }
+    }
+    for (const proc of snapshot.procedures) {
+      if (proc.procedureId === capabilityId) matches.push(proc.registrationId);
+    }
+    return matches.length === 1 ? matches[0] : void 0;
+  }
+  function pickPending(confirmationId) {
+    if (confirmationId !== void 0) return confirmationId;
+    const pending = registry.confirmations.pending();
+    if (pending.length === 1) return pending[0].confirmationId;
+    throw new Error(
+      pending.length === 0 ? "no pending confirmation to resolve" : "multiple pending confirmations \u2014 pass an explicit confirmationId"
+    );
+  }
+  const surface = {
+    registry,
+    snapshot(ctx) {
+      return registry.snapshot({ consumer, ...ctx });
+    },
+    invoke(capabilityId, input, opts) {
+      const registrationId = opts?.registrationId !== void 0 ? opts.registrationId : resolveRegistrationId(capabilityId, opts?.instanceId);
+      return registry.invoke(
+        {
+          capabilityId,
+          ...input !== void 0 ? { input } : {},
+          ...opts?.instanceId !== void 0 ? { instanceId: opts.instanceId } : {},
+          ...registrationId !== void 0 ? { registrationId } : {},
+          ...opts?.surfaceVersion !== void 0 ? { surfaceVersion: opts.surfaceVersion } : {},
+          ...opts?.confirmationId !== void 0 ? { confirmationId: opts.confirmationId } : {}
+        },
+        { consumer: opts?.consumer ?? consumer }
+      );
+    },
+    async observe(capabilityId, opts) {
+      const versionBefore = registry.getVersion();
+      const result = await surface.invoke(capabilityId, void 0, opts);
+      if (result.status === "error") {
+        throw new Error(
+          `observe(${capabilityId}) failed: ${result.error.code} \u2014 ${result.error.message}`
+        );
+      }
+      const versionAfter = registry.getVersion();
+      if (versionAfter !== versionBefore) {
+        throw new Error(
+          `observe(${capabilityId}) mutated the surface (version ${versionBefore} \u2192 ${versionAfter}); observations MUST be side-effect free (docs/01)`
+        );
+      }
+      return result.output;
+    },
+    captureRef(capabilityId, instanceId) {
+      const registrationId = resolveRegistrationId(capabilityId, instanceId);
+      if (registrationId === void 0) {
+        throw new Error(`captureRef: no unique live registration exposes ${capabilityId}`);
+      }
+      return { registrationId, surfaceVersion: registry.getVersion() };
+    },
+    as(host) {
+      if (!ownsRegistry) {
+        throw new Error(
+          "as() requires a harness-created registry \u2014 pass `host` through your own RegistryOptions.context instead"
+        );
+      }
+      hostRef.current = host;
+    },
+    confirmations: {
+      pending() {
+        return registry.confirmations.pending();
+      },
+      approve(confirmationId) {
+        registry.confirmations.resolve(pickPending(confirmationId), { approved: true });
+      },
+      deny(confirmationId, reason) {
+        registry.confirmations.resolve(pickPending(confirmationId), {
+          approved: false,
+          ...reason !== void 0 ? { reason } : {}
+        });
+      },
+      expire(confirmationId) {
+        registry.confirmations.forceExpire(pickPending(confirmationId));
+      }
+    },
+    events() {
+      return [...events];
+    },
+    auditLog() {
+      return auditSink.events();
+    },
+    dispose() {
+      unsubscribe();
+      if (ownsRegistry) registry.dispose();
+    }
+  };
+  return surface;
+}
+
+export {
+  createTestSurface
+};
+//# sourceMappingURL=chunk-QV7I5CCY.js.map

package/dist/chunk-QV7I5CCY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/harness.ts"],"sourcesContent":["import {\n  createAgentSurfaceRegistry,\n  memoryAuditSink,\n  type AgentConsumer,\n  type AgentInvocationResult,\n  type AgentSurfaceEvent,\n  type AgentSurfaceRegistry,\n  type AgentSurfaceSnapshot,\n  type AuditEvent,\n  type JsonValue,\n  type PendingConfirmation,\n  type SnapshotContext,\n} from \"@agent-surface/core\";\n\nexport interface TestSurfaceOptions {\n  registry?: AgentSurfaceRegistry; // default: fresh registry, environment \"test\"\n  consumer?: AgentConsumer; // default {id:\"test\", kind:\"test\"}\n  host?: Record<string, unknown>; // overrides RegistryOptions.context()\n}\n\nexport interface TestSurface {\n  registry: AgentSurfaceRegistry;\n  snapshot(ctx?: Partial<SnapshotContext>): AgentSurfaceSnapshot;\n\n  /** Invoke with test conveniences: auto invocationId, auto registrationId\n      resolution from the latest snapshot, typed input. */\n  invoke(\n    capabilityId: string,\n    input?: JsonValue,\n    opts?: {\n      instanceId?: string;\n      registrationId?: string; // pass a captured one to simulate staleness\n      surfaceVersion?: string;\n      confirmationId?: string;\n      consumer?: AgentConsumer;\n    },\n  ): Promise<AgentInvocationResult>;\n\n  /** Sugar: invoke an observation and return its parsed output (throws on error). */\n  observe<T = JsonValue>(capabilityId: string, opts?: { instanceId?: string }): Promise<T>;\n\n  /** Capture current resolution tokens for later stale-invocation tests. */\n  captureRef(\n    capabilityId: string,\n    instanceId?: string,\n  ): { registrationId: string; surfaceVersion: string };\n\n  /** Swap host context mid-test (auth changes): as({user: admin}). */\n  as(host: Record<string, unknown>): void;\n\n  confirmations: {\n    pending(): PendingConfirmation[];\n    approve(confirmationId?: string): void; // default: the only pending one\n    deny(confirmationId?: string, reason?: string): void;\n    expire(confirmationId?: string): void; // force-expires that record\n  };\n\n  /** All registry events recorded since creation, in order. */\n  events(): AgentSurfaceEvent[];\n  auditLog(): AuditEvent[];\n\n  dispose(): void;\n}\n\nexport function createTestSurface(options?: TestSurfaceOptions): TestSurface {\n  const hostRef: { current: Record<string, unknown> } = { current: options?.host ?? {} };\n  const consumer: AgentConsumer = options?.consumer ?? { id: \"test\", kind: \"test\" };\n  const auditSink = memoryAuditSink({ capacity: 5000 });\n  const ownsRegistry = options?.registry === undefined;\n\n  const registry =\n    options?.registry ??\n    createAgentSurfaceRegistry({\n      environment: \"test\",\n      context: () => hostRef.current,\n      audit: auditSink,\n    });\n\n  const events: AgentSurfaceEvent[] = [];\n  const unsubscribe = registry.subscribe((event) => {\n    events.push(event);\n  });\n\n  function resolveRegistrationId(\n    capabilityId: string,\n    instanceId: string | undefined,\n  ): string | undefined {\n    const snapshot = registry.snapshot({ consumer });\n    const matches: string[] = [];\n    for (const component of snapshot.components) {\n      if (instanceId !== undefined && component.instanceId !== instanceId) continue;\n      const caps = [...component.observations, ...component.actions];\n      if (caps.some((c) => c.capabilityId === capabilityId)) {\n        matches.push(component.registrationId);\n      }\n    }\n    for (const proc of snapshot.procedures) {\n      if (proc.procedureId === capabilityId) matches.push(proc.registrationId);\n    }\n    // Auto-attach only when unambiguous; otherwise let the registry produce\n    // AMBIGUOUS_INSTANCE / CAPABILITY_NOT_FOUND / COMPONENT_UNMOUNTED.\n    return matches.length === 1 ? matches[0] : undefined;\n  }\n\n  function pickPending(confirmationId: string | undefined): string {\n    if (confirmationId !== undefined) return confirmationId;\n    const pending = registry.confirmations.pending();\n    if (pending.length === 1) return pending[0]!.confirmationId;\n    throw new Error(\n      pending.length === 0\n        ? \"no pending confirmation to resolve\"\n        : \"multiple pending confirmations — pass an explicit confirmationId\",\n    );\n  }\n\n  const surface: TestSurface = {\n    registry,\n\n    snapshot(ctx) {\n      return registry.snapshot({ consumer, ...ctx });\n    },\n\n    invoke(capabilityId, input, opts) {\n      const registrationId =\n        opts?.registrationId !== undefined\n          ? opts.registrationId\n          : resolveRegistrationId(capabilityId, opts?.instanceId);\n      return registry.invoke(\n        {\n          capabilityId,\n          ...(input !== undefined ? { input } : {}),\n          ...(opts?.instanceId !== undefined ? { instanceId: opts.instanceId } : {}),\n          ...(registrationId !== undefined ? { registrationId } : {}),\n          ...(opts?.surfaceVersion !== undefined ? { surfaceVersion: opts.surfaceVersion } : {}),\n          ...(opts?.confirmationId !== undefined ? { confirmationId: opts.confirmationId } : {}),\n        },\n        { consumer: opts?.consumer ?? consumer },\n      );\n    },\n\n    async observe<T = JsonValue>(capabilityId: string, opts?: { instanceId?: string }): Promise<T> {\n      const versionBefore = registry.getVersion();\n      const result = await surface.invoke(capabilityId, undefined, opts);\n      if (result.status === \"error\") {\n        throw new Error(\n          `observe(${capabilityId}) failed: ${result.error.code} — ${result.error.message}`,\n        );\n      }\n      const versionAfter = registry.getVersion();\n      if (versionAfter !== versionBefore) {\n        throw new Error(\n          `observe(${capabilityId}) mutated the surface (version ${versionBefore} → ${versionAfter}); observations MUST be side-effect free (docs/01)`,\n        );\n      }\n      return result.output as T;\n    },\n\n    captureRef(capabilityId, instanceId) {\n      const registrationId = resolveRegistrationId(capabilityId, instanceId);\n      if (registrationId === undefined) {\n        throw new Error(`captureRef: no unique live registration exposes ${capabilityId}`);\n      }\n      return { registrationId, surfaceVersion: registry.getVersion() };\n    },\n\n    as(host) {\n      if (!ownsRegistry) {\n        throw new Error(\n          \"as() requires a harness-created registry — pass `host` through your own RegistryOptions.context instead\",\n        );\n      }\n      hostRef.current = host;\n    },\n\n    confirmations: {\n      pending() {\n        return registry.confirmations.pending();\n      },\n      approve(confirmationId) {\n        registry.confirmations.resolve(pickPending(confirmationId), { approved: true });\n      },\n      deny(confirmationId, reason) {\n        registry.confirmations.resolve(pickPending(confirmationId), {\n          approved: false,\n          ...(reason !== undefined ? { reason } : {}),\n        });\n      },\n      expire(confirmationId) {\n        registry.confirmations.forceExpire(pickPending(confirmationId));\n      },\n    },\n\n    events() {\n      return [...events];\n    },\n\n    auditLog() {\n      return auditSink.events();\n    },\n\n    dispose() {\n      unsubscribe();\n      if (ownsRegistry) registry.dispose();\n    },\n  };\n\n  return surface;\n}\n"],"mappings":"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","names":[]}

package/dist/harness-B_t1q70R.d.ts

@@ -0,0 +1,44 @@
+import { AgentSurfaceRegistry, SnapshotContext, AgentSurfaceSnapshot, JsonValue, AgentConsumer, AgentInvocationResult, PendingConfirmation, AgentSurfaceEvent, AuditEvent } from '@agent-surface/core';
+
+interface TestSurfaceOptions {
+    registry?: AgentSurfaceRegistry;
+    consumer?: AgentConsumer;
+    host?: Record<string, unknown>;
+}
+interface TestSurface {
+    registry: AgentSurfaceRegistry;
+    snapshot(ctx?: Partial<SnapshotContext>): AgentSurfaceSnapshot;
+    /** Invoke with test conveniences: auto invocationId, auto registrationId
+        resolution from the latest snapshot, typed input. */
+    invoke(capabilityId: string, input?: JsonValue, opts?: {
+        instanceId?: string;
+        registrationId?: string;
+        surfaceVersion?: string;
+        confirmationId?: string;
+        consumer?: AgentConsumer;
+    }): Promise<AgentInvocationResult>;
+    /** Sugar: invoke an observation and return its parsed output (throws on error). */
+    observe<T = JsonValue>(capabilityId: string, opts?: {
+        instanceId?: string;
+    }): Promise<T>;
+    /** Capture current resolution tokens for later stale-invocation tests. */
+    captureRef(capabilityId: string, instanceId?: string): {
+        registrationId: string;
+        surfaceVersion: string;
+    };
+    /** Swap host context mid-test (auth changes): as({user: admin}). */
+    as(host: Record<string, unknown>): void;
+    confirmations: {
+        pending(): PendingConfirmation[];
+        approve(confirmationId?: string): void;
+        deny(confirmationId?: string, reason?: string): void;
+        expire(confirmationId?: string): void;
+    };
+    /** All registry events recorded since creation, in order. */
+    events(): AgentSurfaceEvent[];
+    auditLog(): AuditEvent[];
+    dispose(): void;
+}
+declare function createTestSurface(options?: TestSurfaceOptions): TestSurface;
+
+export { type TestSurface as T, type TestSurfaceOptions as a, createTestSurface as c };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { T as TestSurface, a as TestSurfaceOptions, c as createTestSurface } from './harness-B_t1q70R.js';
+import { AgentSurfaceSnapshot } from '@agent-surface/core';
+export { AgentSurfaceMatchers, matchers, toBeOk, toExpose, toExposeUnavailable, toFailWith, toMatchSurfaceSnapshot } from './matchers.js';
+
+interface SerializeSurfaceOptions {
+    /** Include surfaceVersion in the output. Default false (volatile). */
+    includeVersion?: boolean;
+}
+/**
+ * Semantic snapshot serialization (docs/08): registrationIds become stable
+ * placeholders in first-appearance order (`<reg#1>`, `<reg#2>` …);
+ * surfaceId/capturedAt are dropped; surfaceVersion dropped by default;
+ * components/capabilities keep the canonical registry ordering; schemas are
+ * included verbatim — schema drift is exactly what these snapshots catch.
+ */
+declare function serializeSurfaceSnapshot(snapshot: AgentSurfaceSnapshot, options?: SerializeSurfaceOptions): Record<string, unknown>;
+
+export { type SerializeSurfaceOptions, serializeSurfaceSnapshot };

package/dist/index.js

@@ -0,0 +1,23 @@
+import {
+  matchers,
+  serializeSurfaceSnapshot,
+  toBeOk,
+  toExpose,
+  toExposeUnavailable,
+  toFailWith,
+  toMatchSurfaceSnapshot
+} from "./chunk-2E5UCTGQ.js";
+import {
+  createTestSurface
+} from "./chunk-QV7I5CCY.js";
+export {
+  createTestSurface,
+  matchers,
+  serializeSurfaceSnapshot,
+  toBeOk,
+  toExpose,
+  toExposeUnavailable,
+  toFailWith,
+  toMatchSurfaceSnapshot
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/matchers.d.ts

@@ -0,0 +1,55 @@
+import { AgentCapabilityErrorCode, JsonValue } from '@agent-surface/core';
+
+interface MatcherResult {
+    pass: boolean;
+    message: () => string;
+}
+/**
+ * `toExpose` = present AND available for the harness consumer.
+ * Hidden ≠ disabled: that distinction is the security model (docs/06).
+ */
+declare function toExpose(received: unknown, capabilityId: string, opts?: {
+    instanceId?: string;
+}): MatcherResult;
+/** `toExposeUnavailable` = present with available: false (+ optional reason). */
+declare function toExposeUnavailable(received: unknown, capabilityId: string, opts?: {
+    instanceId?: string;
+    reason?: string;
+}): MatcherResult;
+declare function toBeOk(received: unknown): MatcherResult;
+declare function toFailWith(received: unknown, code: AgentCapabilityErrorCode, detailsSubset?: Record<string, JsonValue>): MatcherResult;
+/**
+ * Semantic surface snapshot matcher. Delegates to the runner's own
+ * toMatchSnapshot on the normalized form; `serializeSurfaceSnapshot` is the
+ * underlying primitive if you prefer explicit snapshots.
+ */
+declare function toMatchSurfaceSnapshot(received: unknown): MatcherResult;
+declare const matchers: {
+    toExpose: typeof toExpose;
+    toExposeUnavailable: typeof toExposeUnavailable;
+    toBeOk: typeof toBeOk;
+    toFailWith: typeof toFailWith;
+    toMatchSurfaceSnapshot: typeof toMatchSurfaceSnapshot;
+};
+/**
+ * Matcher surface for `expect.extend(matchers)`. Augment your test runner's
+ * Assertion interface with this shape, e.g. for vitest:
+ *
+ *   declare module "vitest" {
+ *     interface Assertion<T = any> extends AgentSurfaceMatchers<T> {}
+ *   }
+ */
+interface AgentSurfaceMatchers<R = unknown> {
+    toExpose(capabilityId: string, opts?: {
+        instanceId?: string;
+    }): R;
+    toExposeUnavailable(capabilityId: string, opts?: {
+        instanceId?: string;
+        reason?: string;
+    }): R;
+    toBeOk(): R;
+    toFailWith(code: AgentCapabilityErrorCode, detailsSubset?: Record<string, JsonValue>): R;
+    toMatchSurfaceSnapshot(): R;
+}
+
+export { type AgentSurfaceMatchers, matchers, toBeOk, toExpose, toExposeUnavailable, toFailWith, toMatchSurfaceSnapshot };

package/dist/matchers.js

@@ -0,0 +1,17 @@
+import {
+  matchers,
+  toBeOk,
+  toExpose,
+  toExposeUnavailable,
+  toFailWith,
+  toMatchSurfaceSnapshot
+} from "./chunk-2E5UCTGQ.js";
+export {
+  matchers,
+  toBeOk,
+  toExpose,
+  toExposeUnavailable,
+  toFailWith,
+  toMatchSurfaceSnapshot
+};
+//# sourceMappingURL=matchers.js.map

package/dist/matchers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/react.d.ts

@@ -0,0 +1,24 @@
+import { ComponentType, ReactNode, ReactElement } from 'react';
+import { RenderResult } from '@testing-library/react';
+import { a as TestSurfaceOptions, T as TestSurface } from './harness-B_t1q70R.js';
+import '@agent-surface/core';
+
+interface RenderAgentSurfaceOptions extends TestSurfaceOptions {
+    wrapper?: ComponentType<{
+        children: ReactNode;
+    }>;
+}
+interface RenderedAgentSurface extends TestSurface {
+    /** RTL render result (rerender/unmount/container…). */
+    view: RenderResult;
+    rerender(ui: ReactElement): void;
+    unmount(): void;
+}
+/**
+ * Renders `ui` inside an AgentSurfaceProvider bound to a harness registry and
+ * resolves after mount effects flush, so registrations are live (docs/08).
+ * Runs fine under React Strict Mode — keep it on to prove cleanup symmetry.
+ */
+declare function renderAgentSurface(ui: ReactElement, options?: RenderAgentSurfaceOptions): Promise<RenderedAgentSurface>;
+
+export { type RenderAgentSurfaceOptions, type RenderedAgentSurface, renderAgentSurface };

package/dist/react.js

@@ -0,0 +1,91 @@
+import {
+  createTestSurface
+} from "./chunk-QV7I5CCY.js";
+
+// src/react.ts
+import { createElement } from "react";
+import { act, render } from "@testing-library/react";
+import { AgentSurfaceProvider } from "@agent-surface/react";
+async function renderAgentSurface(ui, options) {
+  const surface = createTestSurface(options);
+  const Wrapper = options?.wrapper;
+  const wrap = (element) => {
+    const provided = createElement(AgentSurfaceProvider, {
+      registry: surface.registry,
+      children: element
+    });
+    return Wrapper ? createElement(Wrapper, null, provided) : provided;
+  };
+  let view;
+  await act(async () => {
+    view = render(wrap(ui));
+  });
+  const actInvoke = async (...args) => {
+    let result;
+    await act(async () => {
+      result = await surface.invoke(...args);
+    });
+    return result;
+  };
+  return {
+    ...surface,
+    invoke: actInvoke,
+    async observe(capabilityId, opts) {
+      const versionBefore = surface.registry.getVersion();
+      const result = await actInvoke(capabilityId, void 0, opts);
+      if (result.status === "error") {
+        throw new Error(
+          `observe(${capabilityId}) failed: ${result.error.code} \u2014 ${result.error.message}`
+        );
+      }
+      if (surface.registry.getVersion() !== versionBefore) {
+        throw new Error(
+          `observe(${capabilityId}) mutated the surface; observations MUST be side-effect free (docs/01)`
+        );
+      }
+      return result.output;
+    },
+    confirmations: {
+      pending: () => surface.confirmations.pending(),
+      approve(confirmationId) {
+        act(() => {
+          surface.confirmations.approve(confirmationId);
+        });
+      },
+      deny(confirmationId, reason) {
+        act(() => {
+          surface.confirmations.deny(confirmationId, reason);
+        });
+      },
+      expire(confirmationId) {
+        act(() => {
+          surface.confirmations.expire(confirmationId);
+        });
+      }
+    },
+    view,
+    rerender(next) {
+      act(() => {
+        view.rerender(wrap(next));
+      });
+    },
+    unmount() {
+      act(() => {
+        view.unmount();
+      });
+    },
+    dispose() {
+      try {
+        act(() => {
+          view.unmount();
+        });
+      } catch {
+      }
+      surface.dispose();
+    }
+  };
+}
+export {
+  renderAgentSurface
+};
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react.ts"],"sourcesContent":["import { createElement, type ComponentType, type ReactElement, type ReactNode } from \"react\";\nimport { act, render, type RenderResult } from \"@testing-library/react\";\nimport { AgentSurfaceProvider } from \"@agent-surface/react\";\nimport { createTestSurface, type TestSurface, type TestSurfaceOptions } from \"./harness.js\";\n\nexport interface RenderAgentSurfaceOptions extends TestSurfaceOptions {\n  wrapper?: ComponentType<{ children: ReactNode }>; // routers, query clients…\n}\n\nexport interface RenderedAgentSurface extends TestSurface {\n  /** RTL render result (rerender/unmount/container…). */\n  view: RenderResult;\n  rerender(ui: ReactElement): void;\n  unmount(): void;\n}\n\n/**\n * Renders `ui` inside an AgentSurfaceProvider bound to a harness registry and\n * resolves after mount effects flush, so registrations are live (docs/08).\n * Runs fine under React Strict Mode — keep it on to prove cleanup symmetry.\n */\nexport async function renderAgentSurface(\n  ui: ReactElement,\n  options?: RenderAgentSurfaceOptions,\n): Promise<RenderedAgentSurface> {\n  const surface = createTestSurface(options);\n  const Wrapper = options?.wrapper;\n\n  const wrap = (element: ReactElement): ReactElement => {\n    const provided = createElement(AgentSurfaceProvider, {\n      registry: surface.registry,\n      children: element,\n    });\n    return Wrapper ? createElement(Wrapper, null, provided) : provided;\n  };\n\n  let view!: RenderResult;\n  await act(async () => {\n    view = render(wrap(ui));\n  });\n\n  // Invocations run app handlers that call setState: wrap them in act() so\n  // React commits deterministically and tests stay warning-free.\n  const actInvoke: TestSurface[\"invoke\"] = async (...args) => {\n    let result!: Awaited<ReturnType<TestSurface[\"invoke\"]>>;\n    await act(async () => {\n      result = await surface.invoke(...args);\n    });\n    return result;\n  };\n\n  return {\n    ...surface,\n    invoke: actInvoke,\n    async observe(capabilityId, opts) {\n      const versionBefore = surface.registry.getVersion();\n      const result = await actInvoke(capabilityId, undefined, opts);\n      if (result.status === \"error\") {\n        throw new Error(\n          `observe(${capabilityId}) failed: ${result.error.code} — ${result.error.message}`,\n        );\n      }\n      if (surface.registry.getVersion() !== versionBefore) {\n        throw new Error(\n          `observe(${capabilityId}) mutated the surface; observations MUST be side-effect free (docs/01)`,\n        );\n      }\n      return result.output as never;\n    },\n    confirmations: {\n      pending: () => surface.confirmations.pending(),\n      approve(confirmationId) {\n        act(() => {\n          surface.confirmations.approve(confirmationId);\n        });\n      },\n      deny(confirmationId, reason) {\n        act(() => {\n          surface.confirmations.deny(confirmationId, reason);\n        });\n      },\n      expire(confirmationId) {\n        act(() => {\n          surface.confirmations.expire(confirmationId);\n        });\n      },\n    },\n    view,\n    rerender(next: ReactElement) {\n      act(() => {\n        view.rerender(wrap(next));\n      });\n    },\n    unmount() {\n      act(() => {\n        view.unmount();\n      });\n    },\n    dispose() {\n      try {\n        act(() => {\n          view.unmount();\n        });\n      } catch {\n        /* already unmounted */\n      }\n      surface.dispose();\n    },\n  };\n}\n"],"mappings":";;;;;AAAA,SAAS,qBAA4E;AACrF,SAAS,KAAK,cAAiC;AAC/C,SAAS,4BAA4B;AAmBrC,eAAsB,mBACpB,IACA,SAC+B;AAC/B,QAAM,UAAU,kBAAkB,OAAO;AACzC,QAAM,UAAU,SAAS;AAEzB,QAAM,OAAO,CAAC,YAAwC;AACpD,UAAM,WAAW,cAAc,sBAAsB;AAAA,MACnD,UAAU,QAAQ;AAAA,MAClB,UAAU;AAAA,IACZ,CAAC;AACD,WAAO,UAAU,cAAc,SAAS,MAAM,QAAQ,IAAI;AAAA,EAC5D;AAEA,MAAI;AACJ,QAAM,IAAI,YAAY;AACpB,WAAO,OAAO,KAAK,EAAE,CAAC;AAAA,EACxB,CAAC;AAID,QAAM,YAAmC,UAAU,SAAS;AAC1D,QAAI;AACJ,UAAM,IAAI,YAAY;AACpB,eAAS,MAAM,QAAQ,OAAO,GAAG,IAAI;AAAA,IACvC,CAAC;AACD,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,QAAQ;AAAA,IACR,MAAM,QAAQ,cAAc,MAAM;AAChC,YAAM,gBAAgB,QAAQ,SAAS,WAAW;AAClD,YAAM,SAAS,MAAM,UAAU,cAAc,QAAW,IAAI;AAC5D,UAAI,OAAO,WAAW,SAAS;AAC7B,cAAM,IAAI;AAAA,UACR,WAAW,YAAY,aAAa,OAAO,MAAM,IAAI,WAAM,OAAO,MAAM,OAAO;AAAA,QACjF;AAAA,MACF;AACA,UAAI,QAAQ,SAAS,WAAW,MAAM,eAAe;AACnD,cAAM,IAAI;AAAA,UACR,WAAW,YAAY;AAAA,QACzB;AAAA,MACF;AACA,aAAO,OAAO;AAAA,IAChB;AAAA,IACA,eAAe;AAAA,MACb,SAAS,MAAM,QAAQ,cAAc,QAAQ;AAAA,MAC7C,QAAQ,gBAAgB;AACtB,YAAI,MAAM;AACR,kBAAQ,cAAc,QAAQ,cAAc;AAAA,QAC9C,CAAC;AAAA,MACH;AAAA,MACA,KAAK,gBAAgB,QAAQ;AAC3B,YAAI,MAAM;AACR,kBAAQ,cAAc,KAAK,gBAAgB,MAAM;AAAA,QACnD,CAAC;AAAA,MACH;AAAA,MACA,OAAO,gBAAgB;AACrB,YAAI,MAAM;AACR,kBAAQ,cAAc,OAAO,cAAc;AAAA,QAC7C,CAAC;AAAA,MACH;AAAA,IACF;AAAA,IACA;AAAA,IACA,SAAS,MAAoB;AAC3B,UAAI,MAAM;AACR,aAAK,SAAS,KAAK,IAAI,CAAC;AAAA,MAC1B,CAAC;AAAA,IACH;AAAA,IACA,UAAU;AACR,UAAI,MAAM;AACR,aAAK,QAAQ;AAAA,MACf,CAAC;AAAA,IACH;AAAA,IACA,UAAU;AACR,UAAI;AACF,YAAI,MAAM;AACR,eAAK,QAAQ;AAAA,QACf,CAAC;AAAA,MACH,QAAQ;AAAA,MAER;AACA,cAAQ,QAAQ;AAAA,IAClB;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@agent-surface/testing",
+  "version": "0.1.0",
+  "description": "Deterministic test harness, matchers and semantic snapshots for agent surfaces — no LLM required",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./matchers": {
+      "types": "./dist/matchers.d.ts",
+      "import": "./dist/matchers.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@agent-surface/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@testing-library/react": ">=14",
+    "react": ">=18.2",
+    "@agent-surface/react": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@agent-surface/react": {
+      "optional": true
+    },
+    "@testing-library/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "@types/react": "^19.1.9",
+    "vitest": "^3.2.4",
+    "zod": "^4.1.5",
+    "@agent-surface/react": "0.1.0"
+  },
+  "author": "Paolo Barbato",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wiseair-srl/agent-surface.git",
+    "directory": "packages/testing"
+  },
+  "homepage": "https://agent-surface-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/Wiseair-srl/agent-surface/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agent-surface",
+    "agent",
+    "ai",
+    "llm",
+    "frontend",
+    "capabilities",
+    "typescript",
+    "testing",
+    "vitest",
+    "jest"
+  ],
+  "size-limit": [
+    {
+      "path": "dist/index.js",
+      "limit": "8 kB",
+      "ignore": [
+        "@agent-surface/core",
+        "@agent-surface/react",
+        "react",
+        "@testing-library/react"
+      ]
+    }
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "size": "size-limit"
+  }
+}