From 03b98fc74e1cf3b838072df2bb12f1c5198e12f2 Mon Sep 17 00:00:00 2001 From: 0thernet <894119+0thernet@users.noreply.github.com> Date: Mon, 28 Sep 2026 16:07:59 -0400 Subject: [PATCH 1/3] Release 0.7.23: position Direct against Storybook, MSW, and Playwright Rewrite the README's second lead paragraph to name the nearest alternatives, give the article a dek that says what kind of library Direct is, name the Todo example's empty and write-failure states, and add a comparison section with Storybook, Mock Service Worker, and Playwright that says where each is the better choice. The article's closing install section no longer repeats a versioned command, so hraness.com never shows a trailing version there. Fold the duplicate "Agent skills" section into "Install the Agent Skill" to keep the packed archive inside the reviewed 1,250,000-byte unpacked bound. Bump the package to 0.7.23 and add its CHANGELOG section. Install examples stay on v0.7.22 until the new release assets are live. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 10 +++++ README.md | 58 ++++++++++++---------------- package.json | 2 +- scripts/npm-publish-workflow.test.ts | 2 +- 4 files changed, 37 insertions(+), 35 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 21ed18e..0cb2de1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,16 @@ Each section below is the release page text for one Direct version: a summary, then the changes. The release workflow copies the section whose heading matches the tagged version and adds the install and verification steps itself. +## 0.7.23 - 2026-09-28 + +This release updates Direct's package description, README, and Agent Skill guidance. The library's exports and browser tooling are unchanged. + +- The npm package description now reads "Direct gives browser agents repeatable app states that open by URL, with your real interface running on fixture data." +- The README opens with what Direct does, then shows how it differs from Storybook and Mock Service Worker. A new section compares Direct with Storybook, Mock Service Worker, and Playwright's saved sign-in and network stubs, and says where each of them is the better choice. +- The README overview leads with a Playwright check against the Todo example, names the example's empty and write-failure states, and no longer repeats install commands in its closing section. +- The `$direct` skill describes Direct as a development-only TypeScript library, closes each task with a short plain-language report of what changed, what was checked, and what remains unverified, and presents any support offer as one plain sentence. +- The skill's adoption guide gives an example of when to use `parseDirectDefinition`. + ## 0.7.22 - 2026-09-16 The Direct Agent Skill can offer optional support for Direct at the end of useful work for a person. The library's exports and browser tooling are unchanged. diff --git a/README.md b/README.md index c5728eb..4522fdd 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,12 @@ real interface running on fixture data. This development-only TypeScript library serves signed-in, empty, and edge-case states for frontend testing, each at its own URL. -Direct runs your real interface and feature code against named, validated -fixture data, so a browser agent can reach a hard-to-set-up state without -clicking through setup or depending on live systems. +Storybook renders components in isolation, and Mock Service Worker mocks HTTP +responses. Direct runs your whole app against fixture data behind a port your +app owns, so it also covers setup that isn't HTTP, such as device permissions +and native modules. Your browser tool, such as agent-browser or Playwright, +still does the clicking. See +[how Direct compares](#direct-compared-with-storybook-msw-and-playwright). [GitHub releases](https://github.com/hraness/direct/releases) · [Install @hraness/direct from npm](https://www.npmjs.com/package/@hraness/direct) · @@ -170,10 +173,11 @@ dependency graph excludes Direct. Do not add a fixture composition until I ask. ``` -The repository and tagged package carry the same skill. Installing the skill -does not add Direct to a consumer project. The skills CLI is the preferred way -to let runners discover it; the packaged copy supports runners and tools -that read skills from installed development dependencies. +Installing the skill doesn't add Direct to a project. The package carries a +byte-identical copy under `node_modules/@hraness/direct/skills/direct/` for +runners that read skills from development dependencies. Installing the package +doesn't activate that copy; it runs no `postinstall` hook and changes no +configuration. Pin the release archive in your project's manifest: @@ -193,21 +197,6 @@ bun install npm install ``` -## Agent skills - -Packages built from this source include one Agent Skill under -`node_modules/@hraness/direct/skills/direct/`. `$direct` guides an agent -through adding your app's port and a Direct build, then audits scenario -behavior, readiness, coverage claims, cleanup, and production build output. The -package smoke test keeps the packaged copy byte-identical to the tagged -repository skill. - -Prefer `npx skills add hraness/direct#v0.7.22` or -`bunx skills add hraness/direct#v0.7.22` for runner discovery. You can also copy -or link that one skill directory into a runner's configured location, then -invoke `$direct`. Installing the package doesn't activate the skill. It runs no -`postinstall` hook and changes no repository or user configuration. - ## A complete browser composition Extract a strict world parser and product harness into product-owned files, then compose the lifecycle in one entry: @@ -544,7 +533,7 @@ This repository contains the core library, the browser bridge, a scanner that ch ## [Give each app state you test its own URL.]() -> Repeatable states for browser agents: your real interface on fixture data, at a URL you can open, test, and share. +> A development-only TypeScript library for frontend testing: your real interface on fixture data, in a named state that a browser agent or Playwright check opens by URL. A browser agent can open a page, click a control, and inspect the result. What slows it down is setting up the state behind that page. A signed-in account, a particular database record, a device permission, a model response, or a failure at the right moment can take longer to arrange than the screen takes to review. @@ -574,6 +563,8 @@ await expect(page.getByRole("checkbox", { `waitForQuiescence` is a helper in your own check that waits for Direct's readiness snapshot, described below. Direct doesn't ship it. +The example declares two more states the same way. `?__direct_scenario=todos.empty` opens the empty list, and `?__direct_scenario=todos.write-failure` opens the list with a save that fails, so a check can confirm the error message without breaking a real store. + ### Put a port under your feature code The interface, reducers, parsing, navigation, and feature logic above the port run the same code in both builds. Only the implementation behind the port changes. @@ -669,21 +660,22 @@ Other tools already cover many fast-setup cases (checked 2026-09-28): - Use unit or component tests when the subject is isolated logic or rendering that doesn't need the full app. - Keep live integration and end-to-end tests when the backend, native host, browser assembly, filesystem, operating system, or device is the subject. Direct never exercises the systems behind the ports it replaces. -### Add Direct to a project +### Direct compared with Storybook, MSW, and Playwright -Direct is a development dependency. Install the `$direct` Agent Skill so your coding agent can add a port, scenarios, and a check that production builds exclude Direct: +Choose Storybook to review components in isolation, Mock Service Worker when every dependency you need to control is an HTTP call, and Playwright's saved sign-in when signing in is the only slow step. Choose Direct when a whole app route needs a named starting state that any browser tool, person, or agent can open by URL. -```sh -npx skills add hraness/direct#v0.7.22 -``` +| Tool | What runs | Where test data comes in | Opens by URL | +| --- | --- | --- | --- | +| [Storybook]() | A component or composed page, one story at a time | Story args, decorators, and loaders | Yes, one URL per story | +| [Mock Service Worker]() | Your whole app, unchanged | Request handlers at the network layer | No | +| Playwright [`storageState`]() and [`page.route`]() | Your whole app, inside one test run | A saved sign-in and per-test network stubs | No | +| Direct | Your whole app entry, with routing, reducers, and feature logic | A validated JSON world behind a port your app owns | Yes, `?__direct_scenario=` | -Or add the package yourself from the GitHub release: +Direct asks more of you up front: you add a port and a separate Direct entry. Storybook and MSW are older, more widely used, and support more frameworks; Direct's core is plain TypeScript with React and React Native bindings. Checked against each project's documentation on 2026-09-28. -```sh -bun add --dev https://github.com/hraness/direct/releases/download/v0.7.22/hraness-direct-0.7.22.tgz -``` +### Add Direct to a project -The [Direct README]() covers npm, archive verification, and running the Todo example locally. +Direct is a development dependency. Install the `$direct` Agent Skill so your coding agent can add a port, scenarios, and a check that production builds exclude Direct. The [Direct README]() has the current release commands for the skill, Bun, and npm, plus archive verification and the Todo example. ## Develop diff --git a/package.json b/package.json index 9e3f6cf..7b83ffe 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@hraness/direct", - "version": "0.7.22", + "version": "0.7.23", "description": "Direct gives browser agents repeatable app states that open by URL, with your real interface running on fixture data.", "license": "MIT", "type": "module", diff --git a/scripts/npm-publish-workflow.test.ts b/scripts/npm-publish-workflow.test.ts index 85b0a5f..54595e2 100644 --- a/scripts/npm-publish-workflow.test.ts +++ b/scripts/npm-publish-workflow.test.ts @@ -356,7 +356,7 @@ import { isUtf8ByteLengthAtMost } from "./utf8-byte-boundary.js"; readonly version?: unknown; }; expect(manifest).toEqual(expect.objectContaining({ - version: "0.7.22", + version: "0.7.23", description: "Direct gives browser agents repeatable app states that open by URL, with your real interface running on fixture data.", keywords: [ "frontend-development", From f3113f3f686e6f28d66c82baa44fe72db229cb99 Mon Sep 17 00:00:00 2001 From: 0thernet <894119+0thernet@users.noreply.github.com> Date: Mon, 28 Sep 2026 16:51:05 -0400 Subject: [PATCH 2/3] Pin the packaged skill install guide to 0.7.23 The package smoke test requires the packaged install guide to name the package's own immutable pin, as the 0.7.22 bump did in #53. Co-Authored-By: Claude Opus 5.5 (1M context) --- skills/direct/references/install.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/skills/direct/references/install.md b/skills/direct/references/install.md index 584bc1e..fef2e54 100644 --- a/skills/direct/references/install.md +++ b/skills/direct/references/install.md @@ -18,19 +18,19 @@ global `direct` CLI. ## Add the library -For a new installation, verify that the immutable v0.7.22 GitHub release and +For a new installation, verify that the immutable v0.7.23 GitHub release and its archive are published before using this version. Source candidates do not establish public availability. Check the release manifest, checksums, and provenance using the tagged publishing guide, then install the exact archive: ```sh -bun add --dev https://github.com/hraness/direct/releases/download/v0.7.22/hraness-direct-0.7.22.tgz +bun add --dev https://github.com/hraness/direct/releases/download/v0.7.23/hraness-direct-0.7.23.tgz # or, in an npm project -npm install --save-dev https://github.com/hraness/direct/releases/download/v0.7.22/hraness-direct-0.7.22.tgz +npm install --save-dev https://github.com/hraness/direct/releases/download/v0.7.23/hraness-direct-0.7.23.tgz ``` The package keeps the name `@hraness/direct`. An independently verified npm -mirror may instead use the immutable pin `@hraness/direct@0.7.22`. Use the +mirror may instead use the immutable pin `@hraness/direct@0.7.23`. Use the consumer's existing package manager and lockfile. To upgrade, replace the exact archive version and run the consumer's type, installation, and emitted production-boundary checks; do not use a moving Latest URL. @@ -39,8 +39,8 @@ 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#v0.7.22 -bunx skills add hraness/direct#v0.7.22 +npx skills add hraness/direct#v0.7.23 +bunx skills add hraness/direct#v0.7.23 ``` Restart or reload the agent runner if it does not discover newly installed From 9966115862f21e72b78be624c8dd8e2c6ca48cbe Mon Sep 17 00:00:00 2001 From: 0thernet <894119+0thernet@users.noreply.github.com> Date: Mon, 28 Sep 2026 17:09:06 -0400 Subject: [PATCH 3/3] Fold the 0.7.23 comparison into the existing When to use Direct table main already compares Direct with Playwright built-ins, MSW, and Storybook in one dated table. Drop the second table this release added, keep its tradeoff sentence under the existing one, and point the lead link and CHANGELOG entry at that section. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 2 +- README.md | 17 +++-------------- 2 files changed, 4 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0cb2de1..de64575 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,7 @@ Each section below is the release page text for one Direct version: a summary, t This release updates Direct's package description, README, and Agent Skill guidance. The library's exports and browser tooling are unchanged. - The npm package description now reads "Direct gives browser agents repeatable app states that open by URL, with your real interface running on fixture data." -- The README opens with what Direct does, then shows how it differs from Storybook and Mock Service Worker. A new section compares Direct with Storybook, Mock Service Worker, and Playwright's saved sign-in and network stubs, and says where each of them is the better choice. +- The README opens with what Direct does, then shows how it differs from Storybook and Mock Service Worker. Its "When to use Direct" section has a table comparing Direct with Playwright's route mocking, saved sign-in, and clock, Mock Service Worker, and Storybook, and says when each of them is the better choice. - The README overview leads with a Playwright check against the Todo example, names the example's empty and write-failure states, and no longer repeats install commands in its closing section. - The `$direct` skill describes Direct as a development-only TypeScript library, closes each task with a short plain-language report of what changed, what was checked, and what remains unverified, and presents any support offer as one plain sentence. - The skill's adoption guide gives an example of when to use `parseDirectDefinition`. diff --git a/README.md b/README.md index 4522fdd..591c594 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ responses. Direct runs your whole app against fixture data behind a port your app owns, so it also covers setup that isn't HTTP, such as device permissions and native modules. Your browser tool, such as agent-browser or Playwright, still does the clicking. See -[how Direct compares](#direct-compared-with-storybook-msw-and-playwright). +[how Direct compares](#when-to-use-direct). [GitHub releases](https://github.com/hraness/direct/releases) · [Install @hraness/direct from npm](https://www.npmjs.com/package/@hraness/direct) · @@ -655,24 +655,13 @@ Other tools already cover many fast-setup cases (checked 2026-09-28): | [Storybook](https://storybook.js.org) | A component's props and context | One story per state | The subject is one component, not the whole app | | Direct | Product-owned ports such as sign-in, records, device permissions, native modules, and model calls | A small port for each replaced system | Setup sits below the network or in native code, and the agent needs a named app state with a readiness signal | +Direct asks more of you up front: a port and a separate Direct entry. Storybook and MSW are older, more widely used, and support more frameworks; Direct's core is plain TypeScript with React and React Native bindings. + - Use browser automation alone when the state you need is already quick to reach, or when the live backend and browser assembly are part of the check. - Pair Direct with agent-browser or Playwright when setup and reset dominate the loop: repeated sign-in, slow seed requests, empty or error states that are hard to create, native modules that aren't available, paid model calls, or device permissions that automation can't reset cleanly. - Use unit or component tests when the subject is isolated logic or rendering that doesn't need the full app. - Keep live integration and end-to-end tests when the backend, native host, browser assembly, filesystem, operating system, or device is the subject. Direct never exercises the systems behind the ports it replaces. -### Direct compared with Storybook, MSW, and Playwright - -Choose Storybook to review components in isolation, Mock Service Worker when every dependency you need to control is an HTTP call, and Playwright's saved sign-in when signing in is the only slow step. Choose Direct when a whole app route needs a named starting state that any browser tool, person, or agent can open by URL. - -| Tool | What runs | Where test data comes in | Opens by URL | -| --- | --- | --- | --- | -| [Storybook]() | A component or composed page, one story at a time | Story args, decorators, and loaders | Yes, one URL per story | -| [Mock Service Worker]() | Your whole app, unchanged | Request handlers at the network layer | No | -| Playwright [`storageState`]() and [`page.route`]() | Your whole app, inside one test run | A saved sign-in and per-test network stubs | No | -| Direct | Your whole app entry, with routing, reducers, and feature logic | A validated JSON world behind a port your app owns | Yes, `?__direct_scenario=` | - -Direct asks more of you up front: you add a port and a separate Direct entry. Storybook and MSW are older, more widely used, and support more frameworks; Direct's core is plain TypeScript with React and React Native bindings. Checked against each project's documentation on 2026-09-28. - ### Add Direct to a project Direct is a development dependency. Install the `$direct` Agent Skill so your coding agent can add a port, scenarios, and a check that production builds exclude Direct. The [Direct README]() has the current release commands for the skill, Bun, and npm, plus archive verification and the Todo example.