@hraness/direct 0.7.6 → 0.7.7

package/dist/tooling/browser-verification-entry.js

@@ -1393,23 +1393,54 @@ async function stopVerificationServerWithOutput(server, stopTimeoutMs = DEFAULT_
 async function stopVerificationServer(server, stopTimeoutMs = DEFAULT_STOP_TIMEOUT_MS) {
   await stopVerificationServerWithOutput(server, stopTimeoutMs);
 }
+function verificationServerAcquisitionAbortError() {
+  return new Error("Verification server acquisition was aborted");
+}
+function throwIfVerificationServerAcquisitionAborted(signal) {
+  if (signal?.aborted === true)
+    throw verificationServerAcquisitionAbortError();
+}
+async function waitForVerificationServerAcquisitionStep(promise, signal) {
+  if (signal === undefined)
+    return await promise;
+  throwIfVerificationServerAcquisitionAborted(signal);
+  let abortListener;
+  const aborted = new Promise((_resolve, reject) => {
+    abortListener = () => reject(verificationServerAcquisitionAbortError());
+    signal.addEventListener("abort", abortListener, { once: true });
+    if (signal.aborted)
+      abortListener();
+  });
+  let value;
+  try {
+    value = await Promise.race([promise, aborted]);
+  } finally {
+    if (abortListener !== undefined)
+      signal.removeEventListener("abort", abortListener);
+  }
+  throwIfVerificationServerAcquisitionAborted(signal);
+  return value;
+}
 async function acquireVerificationServer(options) {
   const probeTimeoutMs = options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
   const readinessPath = options.readinessPath ?? "/";
   const isReachable = options.isReachable ?? serverIsReachable;
   const canStartLocally = canAutomaticallyStartLocalServer(options.baseUrl, options.localHosts);
-  if (await isReachable(options.baseUrl, probeTimeoutMs, readinessPath)) {
+  throwIfVerificationServerAcquisitionAborted(options.abortSignal);
+  if (await waitForVerificationServerAcquisitionStep(Promise.resolve(isReachable(options.baseUrl, probeTimeoutMs, readinessPath)), options.abortSignal)) {
     if (canStartLocally && options.reuseExistingLocalServer === false) {
       throw new Error(`A local server is already reachable at ${options.baseUrl}; ` + "verification will not reuse a server whose worktree ownership is unknown");
     }
-    await Bun.sleep(options.reuseProbeIntervalMs ?? DEFAULT_REUSE_PROBE_INTERVAL_MS);
-    if (await isReachable(options.baseUrl, probeTimeoutMs, readinessPath)) {
+    await waitForVerificationServerAcquisitionStep(Bun.sleep(options.reuseProbeIntervalMs ?? DEFAULT_REUSE_PROBE_INTERVAL_MS), options.abortSignal);
+    if (await waitForVerificationServerAcquisitionStep(Promise.resolve(isReachable(options.baseUrl, probeTimeoutMs, readinessPath)), options.abortSignal)) {
+      throwIfVerificationServerAcquisitionAborted(options.abortSignal);
       return { source: "reused" };
     }
   }
   if (!canStartLocally) {
     throw new Error(`No server is reachable at ${options.baseUrl}; automatic startup is limited to local HTTP URLs`);
   }
+  throwIfVerificationServerAcquisitionAborted(options.abortSignal);
   const server = options.startServer();
   let exitedWithCode = null;
   try {
@@ -1420,10 +1451,11 @@ async function acquireVerificationServer(options) {
         exitedWithCode = exitCode;
         break;
       }
-      if (await isReachable(options.baseUrl, probeTimeoutMs, readinessPath)) {
+      if (await waitForVerificationServerAcquisitionStep(Promise.resolve(isReachable(options.baseUrl, probeTimeoutMs, readinessPath)), options.abortSignal)) {
+        throwIfVerificationServerAcquisitionAborted(options.abortSignal);
         return { source: "started", server };
       }
-      await Bun.sleep(options.pollIntervalMs ?? 200);
+      await waitForVerificationServerAcquisitionStep(Bun.sleep(options.pollIntervalMs ?? 200), options.abortSignal);
     }
   } catch (error) {
     await stopVerificationServer(server);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/direct",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "A TypeScript harness for deterministic frontend development with repeatable scenarios, local fixtures, and browser verification for coding agents.",
   "license": "MIT",
   "type": "module",

package/skills/direct/references/install.md

@@ -21,9 +21,9 @@ global `direct` CLI.
 For a new installation, pin the reviewed public release:
 
 ```sh
-bun add --dev @hraness/direct@0.7.6
+bun add --dev @hraness/direct@0.7.7
 # or, in an npm project
-npm install --save-dev @hraness/direct@0.7.6
+npm install --save-dev @hraness/direct@0.7.7
 ```
 
 The equivalent manifest entry is:
@@ -31,7 +31,7 @@ The equivalent manifest entry is:
 ```json
 {
   "devDependencies": {
-    "@hraness/direct": "0.7.6"
+    "@hraness/direct": "0.7.7"
   }
 }
 ```

package/src/tooling/bombadil-campaign.ts

@@ -9,6 +9,7 @@ import {
   extract,
   weighted,
   type ActionGenerator,
+  type Cell,
   type Formula,
   type JSON as BombadilJson,
   type Tree,
@@ -27,8 +28,38 @@ const DIRECT_BROWSER_BRIDGE_SCHEMA = "direct.browser-bridge/v2";
 const DIRECT_SESSION_MANIFEST_SCHEMA = "direct.session-manifest/v1";
 const DIRECT_PROBE_SCHEMA = "direct.probe/v1";
 const MAX_RAW_CONTRACT_CHARACTERS = 2_000_000;
+const MAX_NAMED_SNAPSHOT_CANONICAL_BYTES = 2 * 1024 * 1024;
+const MAX_NAMED_SNAPSHOT_JSON_DEPTH = 64;
 const BRIDGE_KEYS = new Set(["manifest", "reset", "schema", "snapshot"]);
 const UNSAFE_CLICK_INPUT_TYPES = new Set(["image", "reset", "submit"]);
+const UNSAFE_CLICK_LABEL_PHRASES = [
+  "clear",
+  "close",
+  "delete",
+  "discard",
+  "erase",
+  "log out",
+  "remove",
+  "reset",
+  "sign out",
+  "unlink",
+] as const;
+const SNAPSHOT_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_.:/-]*$/u;
+const RESERVED_SNAPSHOT_NAMES = new Set([
+  "direct",
+  "__proto__",
+  "constructor",
+  "prototype",
+]);
+const RESOURCE_LEAK_OPTION_KEYS = new Set(["growthLimit", "metric", "windowMillis"]);
+const RESOURCE_METRICS = [
+  "dom_nodes",
+  "js_event_listeners",
+  "js_heap_total",
+  "js_heap_used",
+  "layout_objects",
+] as const;
+const RESOURCE_METRIC_SET = new Set<string>(RESOURCE_METRICS);
 
 export interface DirectBombadilObservation {
   readonly [key: string | number | symbol]: BombadilJson;
@@ -48,12 +79,32 @@ export interface DirectBombadilObservation {
 }
 
 export interface DirectBombadilProperties {
+  readonly startupContract: Formula;
   readonly exactContract: Formula;
   readonly stableCatalog: Formula;
   readonly noDeclaredViolations: Formula;
   readonly eventualQuiescence: Formula;
 }
 
+function observationHasExactContract(
+  observation: DirectBombadilObservation,
+): boolean {
+  return observation.contractValid
+    && observation.activeSource === "scenario"
+    && observation.activeScenario.length > 0
+    && observation.activeRoute.length > 0
+    && observation.activationHash.length > 0
+    && observation.catalogHash.length > 0;
+}
+
+export type DirectBombadilResourceMetric = (typeof RESOURCE_METRICS)[number];
+
+export interface DirectBombadilResourceLeakOptions {
+  readonly growthLimit: number;
+  readonly metric: DirectBombadilResourceMetric;
+  readonly windowMillis: number;
+}
+
 function safeClickAction(action: ActionTemplate): boolean {
   if (typeof action !== "object" || action === null) return false;
   const candidate = "Click" in action
@@ -67,11 +118,19 @@ function safeClickAction(action: ActionTemplate): boolean {
   const inputType = fingerprint.inputType?.toLowerCase() ?? "";
   const labels = [fingerprint.accessibleName, fingerprint.textContent]
     .filter((label): label is string => label !== null)
-    .map((label) => label.trim().toLowerCase());
+    .map((label) => label
+      .trim()
+      .toLowerCase()
+      .replace(/[^\p{L}\p{N}]+/gu, " "));
+  const hasUnsafeLabel = labels.some((label) => {
+    const padded = ` ${label} `;
+    return UNSAFE_CLICK_LABEL_PHRASES.some((phrase) => padded.includes(` ${phrase} `));
+  });
   return fingerprint.href === null
     && tag !== "a"
+    && tag !== "label"
     && fingerprint.role?.toLowerCase() !== "link"
-    && !labels.includes("reset")
+    && !hasUnsafeLabel
     && !UNSAFE_CLICK_INPUT_TYPES.has(inputType)
     && (tag !== "button" || inputType === "button");
 }
@@ -100,7 +159,8 @@ function pruneActionTree<Action>(
 
 /**
  * Builds a browser action generator without reload/history actions or visible
- * navigation and submission click targets, keeping Direct continuously bound.
+ * navigation, submission, reset, or destructive click targets, keeping Direct
+ * continuously bound.
  */
 export function createDirectBombadilActions(): ActionGenerator<ActionTemplate> {
   const safeClicks = actions(() => pruneActionTree(clicks.generate(), safeClickAction) ?? []);
@@ -126,6 +186,72 @@ function hasExactKeys(
   return keys.length === expected.size && keys.every((key) => expected.has(key));
 }
 
+/**
+ * Builds Bombadil's documented sliding-window resource growth invariant from
+ * the public browser state because 0.7.2 omits its extras module from exports.
+ */
+export function createDirectBombadilResourceLeakProperty(
+  options: DirectBombadilResourceLeakOptions,
+): Formula {
+  if (!isRecord(options) || !hasExactKeys(options, RESOURCE_LEAK_OPTION_KEYS)) {
+    throw new Error("Bombadil resource leak options must contain metric, growthLimit, and windowMillis");
+  }
+  if (typeof options.metric !== "string" || !RESOURCE_METRIC_SET.has(options.metric)) {
+    throw new Error("Bombadil resource leak metric is unsupported");
+  }
+  if (
+    typeof options.growthLimit !== "number"
+    || !Number.isFinite(options.growthLimit)
+    || options.growthLimit <= 0
+    || options.growthLimit > Number.MAX_SAFE_INTEGER
+  ) {
+    throw new Error("Bombadil resource leak growthLimit must be a positive finite safe number");
+  }
+  if (
+    typeof options.windowMillis !== "number"
+    || !Number.isSafeInteger(options.windowMillis)
+    || options.windowMillis < 1
+    || options.windowMillis > 300_000
+  ) {
+    throw new Error("Bombadil resource leak windowMillis must be an integer between 1 and 300000");
+  }
+  const metric = options.metric;
+  const samples: Array<{ readonly timestamp: number; readonly value: number }> = [];
+  let previousTimestamp = -1;
+  const window = extract<BombadilBrowserState, {
+    readonly baseline: number;
+    readonly valid: boolean;
+    readonly value: number;
+  }>((state) => {
+    const timestamp = state.resources.timestamp * 1_000;
+    const value = state.resources[metric];
+    if (
+      !Number.isFinite(timestamp)
+      || timestamp < 0
+      || timestamp < previousTimestamp
+      || !Number.isFinite(value)
+      || value < 0
+    ) {
+      return { baseline: 0, valid: false, value: 0 };
+    }
+    previousTimestamp = timestamp;
+    samples.push({ timestamp, value });
+    const cutoff = timestamp - options.windowMillis;
+    while (samples.length > 2 && (samples[1]?.timestamp ?? Number.POSITIVE_INFINITY) <= cutoff) {
+      samples.shift();
+    }
+    return {
+      baseline: samples[0]?.value ?? value,
+      valid: true,
+      value,
+    };
+  });
+  return always(() =>
+    window.current.valid
+    && window.current.value - window.current.baseline <= options.growthLimit
+  );
+}
+
 function invalidObservation(bridgePresent = false): DirectBombadilObservation {
   return {
     activationHash: "",
@@ -150,6 +276,99 @@ function boundedJsonClone(value: unknown): BombadilJson | null {
   return JSON.parse(source) as BombadilJson;
 }
 
+function cloneNamedSnapshotJson(
+  value: unknown,
+  depth = 0,
+  ancestors: WeakSet<object> = new WeakSet<object>(),
+): BombadilJson | undefined {
+  if (depth > MAX_NAMED_SNAPSHOT_JSON_DEPTH) return undefined;
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (typeof value !== "object") return undefined;
+  if (ancestors.has(value)) return undefined;
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const cloned: BombadilJson[] = [];
+      for (const entry of value) {
+        const child = cloneNamedSnapshotJson(entry, depth + 1, ancestors);
+        if (child === undefined) return undefined;
+        cloned.push(child);
+      }
+      return cloned;
+    }
+    const clonedEntries: [string, BombadilJson][] = [];
+    for (const key of Object.keys(value)) {
+      const child = cloneNamedSnapshotJson(
+        Reflect.get(value, key),
+        depth + 1,
+        ancestors,
+      );
+      if (child === undefined) return undefined;
+      clonedEntries.push([key, child]);
+    }
+    return Object.fromEntries(clonedEntries) as BombadilJson;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function boundedNamedSnapshotJson(value: unknown): BombadilJson | undefined {
+  const cloned = cloneNamedSnapshotJson(value);
+  if (cloned === undefined) return undefined;
+  const source = JSON.stringify(cloned);
+  return new TextEncoder().encode(source).byteLength
+      <= MAX_NAMED_SNAPSHOT_CANONICAL_BYTES
+    ? cloned
+    : undefined;
+}
+
+/**
+ * Creates a named, bounded JSON extractor that fails closed to an explicit
+ * fallback when a page getter throws or returns non-JSON or oversized data.
+ */
+export function createDirectBombadilNamedSnapshot<T extends BombadilJson>(options: {
+  readonly fallback: T;
+  readonly name: string;
+  readonly read: (state: BombadilBrowserState) => unknown;
+  readonly validate: (value: BombadilJson) => value is T;
+}): Cell<T> {
+  if (
+    options.name.length === 0
+    || options.name.length > 128
+    || !SNAPSHOT_NAME_PATTERN.test(options.name)
+    || RESERVED_SNAPSHOT_NAMES.has(options.name)
+  ) {
+    throw new Error(
+      "Bombadil snapshot name must be a safe, unreserved 1-128 character identifier",
+    );
+  }
+  const validate = (value: unknown): T | undefined => {
+    const owned = boundedNamedSnapshotJson(value);
+    return owned !== undefined && options.validate(owned) ? owned : undefined;
+  };
+  let fallback: T | undefined;
+  try {
+    fallback = validate(options.fallback);
+  } catch {
+    fallback = undefined;
+  }
+  if (fallback === undefined) {
+    throw new Error(
+      "Bombadil snapshot fallback must be bounded JSON accepted by validate",
+    );
+  }
+  return extract<BombadilBrowserState, T>((state) => {
+    try {
+      return validate(options.read(state)) ?? fallback;
+    } catch {
+      return fallback;
+    }
+  }).named(options.name);
+}
+
 function readNonNegativeCounters(value: unknown): {
   readonly valid: boolean;
   readonly values: number[];
@@ -247,39 +466,50 @@ export function readDirectBombadilObservation(
   }
 }
 
-/** Builds the four Direct invariants used by Bombadil browser campaigns. */
+/** Builds bounded startup plus strict recurring Direct browser invariants. */
 export function createDirectBombadilProperties(): DirectBombadilProperties {
-  const direct = extract<BombadilBrowserState, DirectBombadilObservation>((state) =>
-    readDirectBombadilObservation(state.window)
-  ).named("direct");
+  let initial: Readonly<{
+    activationHash: string;
+    activeRoute: string;
+    activeScenario: string;
+    catalogHash: string;
+  }> | null = null;
+  const direct = extract<BombadilBrowserState, DirectBombadilObservation>((state) => {
+    const observation = readDirectBombadilObservation(state.window);
+    if (initial === null && observationHasExactContract(observation)) {
+      initial = Object.freeze({
+        activationHash: observation.activationHash,
+        activeRoute: observation.activeRoute,
+        activeScenario: observation.activeScenario,
+        catalogHash: observation.catalogHash,
+      });
+    }
+    return observation;
+  }).named("direct");
 
-  const exactContract = always(
-    eventually(() =>
-      direct.current.contractValid
-      && direct.current.activeSource === "scenario"
-      && direct.current.activeScenario.length > 0
-      && direct.current.activeRoute.length > 0
-      && direct.current.activationHash.length > 0
-    ).within(10, "seconds"),
-  );
-  const stableCatalog = always(
-    eventually(() =>
-      direct.current.contractValid
-      && direct.current.catalogHash.length > 0
-    ).within(10, "seconds"),
-  );
-  const noDeclaredViolations = always(
-    eventually(() =>
-      direct.current.contractValid
-      && direct.current.violationsValid
-      && direct.current.violations.every((value: number) => value === 0)
-    ).within(10, "seconds"),
-  );
+  const startupContract = eventually(() => initial !== null).within(10, "seconds");
+  const exactContract = always(() => initial === null || (
+    observationHasExactContract(direct.current)
+    && direct.current.activationHash === initial.activationHash
+    && direct.current.activeRoute === initial.activeRoute
+    && direct.current.activeScenario === initial.activeScenario
+  ));
+  const stableCatalog = always(() => initial === null || (
+    observationHasExactContract(direct.current)
+    && direct.current.catalogHash === initial.catalogHash
+  ));
+  const noDeclaredViolations = always(() => initial === null || (
+    observationHasExactContract(direct.current)
+    && direct.current.violationsValid
+    && direct.current.violations.every((value: number) => value === 0)
+  ));
   const eventualQuiescence = always(
-    eventually(() => direct.current.isQuiescent).within(10, "seconds"),
+    eventually(() => initial !== null && direct.current.isQuiescent)
+      .within(10, "seconds"),
   );
 
   return Object.freeze({
+    startupContract,
     exactContract,
     stableCatalog,
     noDeclaredViolations,