@hraness/direct 0.7.5

package/package.json

@@ -0,0 +1,179 @@
+{
+  "name": "@hraness/direct",
+  "version": "0.7.5",
+  "description": "A general harness for repeatable app states.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "./src/core/index.ts",
+    "./src/index.ts",
+    "./src/react.ts",
+    "./src/testing/index.ts",
+    "./src/web.ts"
+  ],
+  "packageManager": "bun@1.3.14",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hraness/direct.git"
+  },
+  "homepage": "https://hraness.com/direct",
+  "bugs": {
+    "url": "https://github.com/hraness/direct/issues"
+  },
+  "keywords": [
+    "typescript",
+    "frontend-testing",
+    "deterministic-testing",
+    "fixtures",
+    "scenario-testing",
+    "property-testing"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./src/core/index.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./react": {
+      "types": "./src/react.ts",
+      "import": "./dist/react.js"
+    },
+    "./testing": {
+      "types": "./src/testing/index.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./web": {
+      "types": "./src/web.ts",
+      "import": "./dist/web.js"
+    },
+    "./tooling/browser-verification": {
+      "types": "./src/tooling/browser-verification-entry.ts",
+      "import": "./dist/tooling/browser-verification-entry.js"
+    },
+    "./tooling/bombadil": {
+      "types": "./src/tooling/bombadil.ts",
+      "import": "./dist/tooling/bombadil.js"
+    },
+    "./tooling/bombadil-campaign": "./src/tooling/bombadil-campaign.ts",
+    "./tooling/bundle-boundary": {
+      "types": "./src/tooling/bundle-boundary.ts",
+      "import": "./dist/tooling/bundle-boundary.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "files": [
+    "dist",
+    "src/core/coverage.ts",
+    "src/core/definition.ts",
+    "src/core/effects.ts",
+    "src/core/fixture.ts",
+    "src/core/ids.ts",
+    "src/core/index.ts",
+    "src/core/json-value.ts",
+    "src/core/json.ts",
+    "src/core/query.ts",
+    "src/core/reason.ts",
+    "src/core/resource.ts",
+    "src/core/result.ts",
+    "src/core/runtime.ts",
+    "src/core/scenario.ts",
+    "src/core/store.ts",
+    "src/index.ts",
+    "src/react.ts",
+    "src/testing/activity.ts",
+    "src/testing/coverage-binding.ts",
+    "src/testing/evidence.ts",
+    "src/testing/index.ts",
+    "src/testing/manifest.ts",
+    "src/testing/probe.ts",
+    "src/testing/scripted-transport.ts",
+    "src/testing/session.ts",
+    "src/tooling/browser-verification-entry.ts",
+    "src/tooling/browser-verification.ts",
+    "src/tooling/bombadil-internal.d.ts",
+    "src/tooling/bombadil-campaign.ts",
+    "src/tooling/bombadil-runner.ts",
+    "src/tooling/bombadil.ts",
+    "src/tooling/bundle-boundary.ts",
+    "src/web.ts",
+    "src/web/browser.ts",
+    "src/web/browser-bridge.ts",
+    "src/web/fetch-firewall.ts",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run build:clean && bun run build:runtime && bun run build:tooling",
+    "build:clean": "bun -e 'await (await import(\"node:fs/promises\")).rm(\"./dist\", { recursive: true, force: true })'",
+    "build:runtime": "bun build ./src/index.ts ./src/core/index.ts ./src/react.ts ./src/testing/index.ts ./src/web.ts --outdir ./dist --root ./src --target browser --format esm --splitting --packages external",
+    "build:tooling": "bun build ./src/tooling/browser-verification-entry.ts ./src/tooling/bundle-boundary.ts --outdir ./dist/tooling --root ./src/tooling --target bun --format esm --splitting --packages external && bun build ./src/tooling/bombadil.ts --outdir ./dist/tooling --root ./src/tooling --target bun --format esm --splitting --packages external",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test ./src",
+    "example:build": "vite build --config examples/todos/vite.config.ts",
+    "example:build:direct": "vite build --config examples/todos/direct/vite.config.ts",
+    "example:check-boundary": "bun run examples/todos/direct/check-production-boundary.ts examples/todos/dist",
+    "example:dev": "vite --config examples/todos/vite.config.ts",
+    "example:direct": "vite --config examples/todos/direct/vite.config.ts",
+    "example:react-native": "bun run --cwd examples/react-native start",
+    "example:react-native:test": "bun run --cwd examples/react-native test",
+    "example:react-native:typecheck": "tsc -p examples/react-native/tsconfig.json --noEmit",
+    "example:react-native:verify": "bun run examples/react-native/verify.ts",
+    "example:test": "bun test ./examples/todos",
+    "example:typecheck": "tsc -p examples/todos/tsconfig.json --noEmit",
+    "example:verify": "bun run examples/todos/verify.ts",
+    "lint": "eslint src examples scripts",
+    "test:npm-release": "bun test ./scripts/npm-stage-workflow.test.ts",
+    "test:package": "bun run ./scripts/package-smoke.ts",
+    "kb:refresh": "bunx --bun github:hraness/kb#v0.15.2 refresh --root kb",
+    "kb:check:lane": "bunx --bun github:hraness/kb#v0.15.2 check --root kb --no-catalog",
+    "kb:check": "bunx --bun github:hraness/kb#v0.15.2 check --root kb && bunx --bun github:hraness/kb#v0.15.2 agents check --root kb --repo .",
+    "kb:catalog": "bunx --bun github:hraness/kb#v0.15.2 catalog --root kb",
+    "check": "bun run typecheck && bun run test:npm-release && bun run build && bun run test:package && bun run test && bun run lint && bun run example:test && bun run example:typecheck && bun run example:verify && bun run example:react-native:test && bun run example:react-native:typecheck && bun run example:react-native:verify",
+    "prepack": "bun run check"
+  },
+  "peerDependencies": {
+    "@antithesishq/bombadil": "0.7.2",
+    "agent-browser": "0.32.3",
+    "react": ">=18 <20"
+  },
+  "peerDependenciesMeta": {
+    "@antithesishq/bombadil": {
+      "optional": true
+    },
+    "agent-browser": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@antithesishq/bombadil": "0.7.2",
+    "@eslint/js": "^9.39.2",
+    "@expo/metro-runtime": "~57.0.6",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^24.10.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "eslint": "^9.39.2",
+    "expo": "~57.0.9",
+    "fast-check": "^4.8.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-native": "0.86.2",
+    "react-native-web": "~0.21.2",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.53.0",
+    "vite": "^8.1.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/skills/direct/AGENTS.md

@@ -0,0 +1,13 @@
+# Contents
+
+- `SKILL.md` – concise routing, shared invariants, and production-exclusion rules.
+- `references/install.md` – exact package installation, readiness, and optional browser-driver guidance.
+- `references/adoption.md` – product-boundary and deterministic-composition workflow.
+- `references/verification.md` – evidence, browser-session, cleanup, and production-boundary audit workflow.
+- `agents/openai.yaml` – concise UI metadata and default `$direct` invocation.
+
+# Guidelines
+
+- Preserve the product-owned semantic-port boundary and keep provider protocols out of deterministic adapters.
+- Require strict versioned worlds, explicit proof modes, structurally separate composition graphs, and non-vacuous emitted-output scans with paired source maps where platform resolution matters.
+- Keep metadata aligned with the skill's actual trigger and workflow.

package/skills/direct/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: direct
+description: Use Hraness Direct to install, adopt, test, audit, or troubleshoot deterministic frontend and UI testing workbenches for web, React, React Native, and Expo. Trigger for repeatable signed-in, empty, loading, and error states; frontend fixtures and scenario URLs; strict JSON worlds; product-owned ports and adapters; logical time; fail-closed network boundaries; agent-browser, Playwright, or Bombadil verification; quiescence probes; coverage claims; property tests; and proving @hraness/direct stays out of production bundles.
+---
+
+# Direct
+
+Direct is a development-only harness for repeatable application states. It
+runs the real interface and feature code against product-owned deterministic
+ports. It does not drive the browser or prove the live systems, hosts,
+platforms, or devices that those ports replace.
+
+## Choose the workflow
+
+- If Direct is absent, the requested work includes installation, or package
+  readiness is uncertain, read [references/install.md](references/install.md).
+- To add, extend, repair, or troubleshoot a Direct composition, read
+  [references/adoption.md](references/adoption.md).
+- To test, audit, review, or report evidence from an existing composition,
+  read [references/verification.md](references/verification.md).
+- For end-to-end adoption, read the installation and adoption references,
+  implement the smallest product seam, then apply the verification reference.
+
+## Preserve the boundary
+
+Keep Direct in `devDependencies`. Put provider, storage, native-module, host,
+or service code behind the smallest product-owned semantic port. Production
+and Direct compositions must have structurally separate entry graphs.
+
+Never import Direct, fixture worlds, scenario catalogs, workbench code, or the
+browser bridge from a production entry. Build production independently and
+scan its emitted executable output. A scan that inspected no executable files
+is not evidence.
+
+Parse foreign worlds and browser contracts from `unknown`. Reject malformed
+explicit activation instead of falling back to another scenario. Use logical
+time and activity scopes for deterministic work, and join a stable quiet probe
+before making semantic assertions.
+
+State proof limits precisely. Fixture evidence can prove the real interface
+and product logic through deterministic ports; it cannot prove a substituted
+adapter, service, operating system, browser host, or device.
+
+## Finish the task
+
+Run narrow checks while editing, then the consumer repository's complete
+in-scope gate. Report the selected product port, scenarios, proof modes,
+commands, production surfaces scanned, passed evidence, and direct evidence
+that remains open.

package/skills/direct/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Direct"
+  short_description: "Build and verify deterministic UI states"
+  default_prompt: "Use $direct to add or verify a deterministic UI composition while keeping Direct out of production."

package/skills/direct/references/adoption.md

@@ -0,0 +1,131 @@
+# Adopt Direct
+
+## Inspect the product boundary
+
+1. Read every applicable `AGENTS.md`, the package manifest, build configuration, production entry, feature state, and existing tests.
+2. Trace the external dependency that makes the target state slow or nondeterministic.
+3. Choose the lowest product-owned semantic port above that dependency and below the behavior under review.
+4. State which adapter, service, host, platform, or device behavior the deterministic composition will replace and therefore cannot prove.
+
+Do not simulate a provider SDK or wire protocol when the product can own a smaller domain port. Do not fork product UI or reducers into fixture-only copies.
+
+## Separate production first
+
+1. Define the port in production-safe product code.
+2. Move provider, native-module, storage, or service imports into a production adapter.
+3. Compose production from a production-only graph.
+4. Add Direct as a development dependency and create a distinct Direct graph and output directory. Use a separate entry when both compositions target the same platform; a non-shipping Expo web fixture may instead sit behind an extensionless import with `.native` and `.web` implementations below a shared route tree.
+
+Reject a design that conditionally imports fixtures from a query string, build flag, or runtime environment variable inside the production graph. Keep platform-specific navigation providers below shared routes and screens so route discovery sees one stable module while the bundler selects one composition.
+
+## Define the deterministic surface
+
+1. Define one bounded JSON world with a literal version.
+2. Parse it from `unknown`; reject unknown keys, unsupported versions, duplicate identifiers, inconsistent states, and exceeded bounds.
+3. Call `defineDirect` with a validated default, stable scenario IDs, and exact `fixture`, `mixed`, or `direct` coverage entries. Authored invalid configuration should fail during startup. Use `tryDefineDirect` for typed configuration assembled dynamically and `parseDirectDefinition` for genuinely unknown configuration.
+   Keep each definition within the public discovery bounds of 256 scenarios
+   and 256 coverage entries.
+4. Implement deterministic adapters for the same product ports. Use logical time for product delays and activity scopes for asynchronous work.
+5. Use exact scripts only when request or event order is part of the claim. Keep arbitrary valid interactive behavior stateful in the product adapter.
+6. Call `createDirectSession` to own activation, store, clock, activity,
+   harness construction, the world-free session manifest, probe observation,
+   cancellation, and reverse-order cleanup.
+
+Treat the shared world store as a scenario seed and activity ledger. Let product adapters own mutable repositories or event streams after construction.
+
+A scenario contains initial world, route, and optional logical-runtime state. Product-verifier actions, semantic assertions, and evidence policy do not belong in the scenario catalog.
+
+## Add the development entry
+
+Render the real product interface with deterministic adapters from
+`session.harness`. Call `installDirectBrowser({ session })` only in a browser
+Direct entry. It atomically publishes the exact session manifest, live probe,
+and reset action, installs the fail-closed application-fetch firewall by
+default, tracks fetch work in the session activity scope, and registers
+cleanup with the session. Configure blocked-request and activity-error
+observers as named violations. Pass `firewall: false` only when another
+checked boundary owns the same application-`fetch` policy. The verifier still
+needs pre-navigation egress containment.
+
+Do not create a product-specific scenario-discovery global. The manifest
+already publishes the query keys, default scenario, ordered scenario metadata,
+active identity, and coverage contract without exposing worlds, scripts, or
+product assertions. Its catalog drift fingerprint covers the query keys,
+default scenario, ordered metadata, and exact coverage snapshot. The scenario
+route is the expected product route; the product still owns whether its Direct
+entry lives at that route or inside one wrapper URL.
+
+Display activation failures. Never fall back from malformed explicit activation to a nearby valid scenario.
+
+Keep browser process and session policy in the product verifier, outside the
+product composition. Direct's browser runtime remains driver-neutral. Prefer
+the optional `@hraness/direct/tooling/browser-verification` Bun/Node helpers
+for atomic bridge reads, bounded agent-browser commands, server leases, and
+artifacts when they fit the repository. The helpers invoke the consumer's
+local agent-browser installation; they do not bundle a driver, coordinate
+parallel work, supervise cleanup, or own product commands and evidence.
+
+Use one task-owned local Chromium session and process for a sequential batch of
+at most eight scenarios. Call `window new` before every scenario to create a
+fresh BrowserContext. Inventory its tabs and attempt to close scenario-owned
+tabs, retaining each command result and the post-attempt inventory.
+agent-browser 0.32.3 can ignore `Target.closeTarget` errors, so do not claim
+proven per-tab closure. Keep the inert no-URL bootstrap tab until the final
+whole-browser close, which is the stronger disposal boundary. Do not reuse a
+context, substitute `tab new`, or launch one process per scenario. Capture
+semantic and visual evidence in the same exact Chromium context.
+
+Pass an exact `--allowed-domains` list for the target and required asset hosts
+before the first navigation. Start Chromium with `open` and no URL so
+agent-browser installs the allowlist while creating its inert internal
+`about:blank` tab. Do not pass `about:blank` as an explicit URL; 0.32.3 rejects
+that hostname-free navigation under the allowlist. Keep the Direct
+application-`fetch` firewall as instrumentation; it does not contain
+navigation, subresources, WebSockets, workers, service workers, beacons,
+WebRTC, native traffic, or another realm.
+Forbid ordinary browser-wide `--cdp` attachment because named sessions do not
+isolate contexts and agent-browser 0.32.3 cannot combine that attachment with
+`--allowed-domains`.
+
+Run locally serial unless a real external coordinator enforces shared
+admission. Direct does not integrate or enforce a process cap. Use one explicit
+session, empty task-owned config, fresh socket directory, sanitized
+environment, exact allowlist, and bounded idle timeout for every batch command.
+Record the exact agent-browser version.
+
+Require a successful final browser close. A close failure invalidates the
+batch; preserve task metadata and do not claim disposal or performance.
+The idle timeout is only an orphan backstop. Parallel-admission or crash-safe
+cleanup claims require a real external supervisor that owns both the
+agent-browser daemon and Chromium roots, or one containing job. The roots can
+occupy different process groups, so daemon exit alone is not cleanup proof.
+
+## Prove behavior and exclusion
+
+Add focused tests for:
+
+- accepted and rejected worlds;
+- scenario and coverage drift;
+- session-manifest round trips, active identity, and catalog drift;
+- deterministic adapter success, declared failure, cancellation, and cleanup;
+- exact-script consumption and remaining work when scripts are used; and
+- emitted production output containing a forbidden marker.
+
+Build production and Direct separately. Scan emitted production assets for package names, wire schemas, reserved query keys, fixture and workbench markers, and browser globals. Prefer `@hraness/direct/tooling/bundle-boundary` for the shared scan mechanics while keeping included paths, product markers, and positive production identity evidence product-owned. Fail a scan that inspects no executable files.
+
+For native bundles, emit a paired source map for each production platform. Positively require stable path suffixes for the shared screen and state, native composition, and production adapters in every map; reject the Direct package, `.web` composition, fixtures, and workbench sources. Apply the inverse positive selection to a web fixture map. An absence-only scan of an unrelated clean bundle is not proof.
+
+Update the nearest `AGENTS.md`, package README, and command documentation. Run the narrow tests while iterating, then the repository's complete in-scope gate.
+
+## Report the result
+
+Name the selected port, deterministic scenarios, proof modes, commands run, production surfaces scanned, and direct evidence that still remains. Do not describe fixture evidence as proof of a replaced external system.
+When browser verification is in scope, also name the process and session
+policy. Require each evidence record to carry the exact browser-driver version,
+configured backend, allowed hosts, observed browser identity, batch index and
+size, verifier-assigned scenario/context label, fresh `window new` command and
+result, tab inventories and close-attempt results, execution mode, and final
+close result. Only when a performance comparison is explicitly requested, report wall time
+separately from local host CPU and peak resident memory; lower host load is not
+itself a faster result. Direct provides no browser-run or performance evidence;
+require external product evidence for either claim.

package/skills/direct/references/install.md

@@ -0,0 +1,91 @@
+# Install and verify Direct
+
+Installing this Agent Skill does not install the Direct library into a
+consumer project. Direct is a development dependency and does not provide a
+global `direct` CLI.
+
+## Check readiness
+
+1. Read the consumer's repository instructions and package manifest.
+2. Confirm Bun is available with `command -v bun`. If it is absent, follow the
+   reviewed environment setup or the official [Bun installation
+   guide](https://bun.sh/docs/installation); do not run an unreviewed remote
+   install script.
+3. Inspect `devDependencies` for `@hraness/direct`. Do not move it into
+   `dependencies`.
+4. Reuse the repository's existing immutable Direct pin when it is compatible.
+   Do not upgrade an existing pin unless the user asked for an upgrade.
+
+## Add the library
+
+For a new installation, pin the reviewed public release:
+
+```sh
+bun add --dev @hraness/direct@0.7.5
+# or, in an npm project
+npm install --save-dev @hraness/direct@0.7.5
+```
+
+The equivalent manifest entry is:
+
+```json
+{
+  "devDependencies": {
+    "@hraness/direct": "0.7.5"
+  }
+}
+```
+
+Then run `bun install`. Do not add another package manager or lockfile to a
+repository that already defines its package manager.
+
+If the task starts with skill installation rather than a loaded skill, install
+the single repository skill with either command:
+
+```sh
+npx skills add hraness/direct
+bunx skills add hraness/direct
+```
+
+Restart or reload the agent runner if it does not discover newly installed
+skills during the current session, then invoke `$direct`.
+
+## Optional browser verification dependency
+
+Direct's runtime is driver-neutral. Install `agent-browser@0.32.3` only when
+the requested verification workflow uses Direct's optional agent-browser host
+tooling and the consumer does not already supply the compatible peer:
+
+```sh
+bun add --dev agent-browser@0.32.3
+```
+
+Playwright MCP or another browser driver can instead read the same exact
+`window.__direct` contract when it independently establishes the required
+containment, fresh-context, and cleanup evidence. Do not install a browser
+driver for an adoption-only task.
+
+Install Bombadil only when the product requests bounded diagnostic fuzzing
+through Direct's optional campaign and host-runner subpaths. The integration
+supports one exact release:
+
+```sh
+bun add --dev @antithesishq/bombadil@0.7.2
+```
+
+Bombadil is an optional Direct peer. Keep the direct development dependency in
+the consumer root because the host runner resolves and validates that root
+package and its native platform binary.
+
+## Verify the boundary
+
+After installation:
+
+- ensure the lockfile resolves the intended immutable release;
+- typecheck the consumer's intended Direct imports;
+- build Direct and production entries separately; and
+- run the product-owned emitted-bundle boundary gate against every production
+  surface.
+
+Package installation alone does not activate fixtures and does not prove
+production exclusion.