@harnessed-ts/storybook 0.0.0-stage → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# @harnessed-ts/storybook
+
+## 0.6.0
+
+### Minor Changes
+
+- e324e94: ember-test-selectors style test ids: `configure({ testIdAttribute: 'data-test-*' })` makes `testId('x')` match any element that has the attribute `data-test-x`, whatever its value, with the same scoping, strictness, `{ global: true }`, frame and absence rules as before under every driver. A plain attribute name keeps matching by value. A presence id is held to letters, digits, `-`, `_`, `.` and `:`, and anything else (or a `RegExp`) is refused rather than spliced into a selector.
+
+  `Query.boundingBox()` resolves to `{ x, y, width, height }`: the target's border box in CSS pixels, relative to the top-level viewport, offset by every frame crossed. Strict, and on an absent target it rejects after the timeout, as `text()` does. A node that draws no box reads as all zeros, and so does every node under the dom driver: jsdom computes no layout.
+
+  `Query.upload(files)` sets the files of an `<input type="file">`, or of the input a `<label>` is for, and fires `input` and `change`, replacing any earlier selection. It refuses any other element, and several files for an input that is not `multiple`. Puppeteer, WebdriverIO and TestCafe take only paths, so there each `File` is written to a temporary directory first: its name and bytes arrive, and the browser infers its type from the extension.
+
+  `Query` gains two abstract members, so a driver outside this repo implements both to keep compiling; the conformance catalog pins all three changes.
+
+  `@harnessed-ts/eslint-plugin` supports ESLint 8.57 and legacy `.eslintrc`: the peer range is now `>=8.57`, `legacy-recommended` and `legacy-strict` name the rules under `@harnessed-ts/`, and the CJS build exposes `rules` and `configs` at the top level, where eslintrc reads them.
+
+  `npx @harnessed-ts/claude install` detects ember-test-selectors attributes (in `.gts`, `.gjs` and `.hbs` files too) and writes `testIdAttribute: 'data-test-*'`.
+
+  `@harnessed-ts/storybook` writes and finds its story-ready marker under a `data-test-*` config, where `StoryPage` waits for it.
+
+### Patch Changes
+
+- Updated dependencies [e324e94]
+  - @harnessed-ts/core@0.6.0
+  - @harnessed-ts/dom@0.6.0
+  - @harnessed-ts/page@0.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- ad20e8c: Add `@harnessed-ts/storybook`. Spread `harnessed()` into `.storybook/preview.ts`, and a story that names its harness in `parameters.harness` gets it in `play` as `context.harness`. The harness drives the canvas through Storybook's instrumented `userEvent`, each public method is a step in the Interactions panel (secret-looking arguments are masked by parameter name in development, and by object key in a minified build too), and the harness matchers are registered on `storybook/test`'s `expect`. `StoryPage` from `@harnessed-ts/storybook/page` opens a story by URL from any runner that can navigate, with typed `args` and `globals`, `play: false` to skip the play function, and a play function's own error when it throws. React only: `@storybook/ember` builds with webpack, and Storybook's Vitest addon needs Vite.
+
+  `no-raw-locator-in-test` now treats `*.stories.*` files as tests, flagging `canvas.getBy*`, `within` from `storybook/test`, and `canvasElement.querySelector`. `npx @harnessed-ts/claude install` detects Storybook and documents the preview setup, `play` with a harness, and `StoryPage`.
+
+### Patch Changes
+
+- @harnessed-ts/core@0.5.0
+  - @harnessed-ts/dom@0.5.0
+  - @harnessed-ts/page@0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Gaudet, Jay Seo
+
+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

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @harnessed-ts/storybook
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Harnesses in Storybook. A harness in every play function, with each of its
+methods a step in the Interactions panel, and stories opened as fixtures from
+any runner that can navigate.
+
+```ts
+// .storybook/preview.ts
+import { harnessed } from '@harnessed-ts/storybook'
+export default { ...harnessed() } satisfies Preview
+```
+
+```tsx
+const meta = {
+  title: 'Forms/Login Form',
+  component: LoginForm,
+  parameters: { harness: LoginFormHarness },
+} satisfies Meta<typeof LoginForm>
+export default meta
+
+type Story = WithHarness<StoryObj<typeof meta>, LoginFormHarness>
+
+export const WrongPassword: Story = {
+  play: async ({ harness }) => {
+    await harness.signInAs('ada@example.com', 'guess')
+    await expect(await harness.error()).toBe('Wrong password')
+  },
+}
+```
+
+```ts
+// Playwright, or any runner whose driver can navigate
+import { StoryPage } from '@harnessed-ts/storybook/page'
+import * as LoginStories from './LoginForm.stories'
+
+const story = await StoryPage.goto(pw(page), LoginStories, 'WrongPassword', { play: false })
+await story.harness(LoginFormHarness).signInAs('ada@example.com', 'hunter2')
+```
+
+Storybook 9 or later. See [Using with Storybook](https://github.com/joegaudet/harnessed#using-with-storybook).

package/dist/chunk-J6DS34J4.js

@@ -0,0 +1,55 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length; i < n; i++) flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : { get [name]() {
+    return __privateGet(this, extra);
+  }, set [name](x) {
+    return __privateSet(this, extra, x);
+  } }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1; i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => name in x };
+      if (k ^ 3) access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2) access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? void 0 : { get: desc.get, set: desc.set } : target, ctx), done._ = 1;
+    if (k ^ 4 || it === void 0) __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null) __typeError("Object expected");
+    else __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/ready.ts
+var STORY_READY_TEST_ID = "harnessed-story-ready";
+var PLAY_ERROR_ATTRIBUTE = "data-harnessed-play-error";
+
+export { PLAY_ERROR_ATTRIBUTE, STORY_READY_TEST_ID, __decorateElement, __decoratorStart, __runInitializers };
+//# sourceMappingURL=chunk-J6DS34J4.js.map
+//# sourceMappingURL=chunk-J6DS34J4.js.map

package/dist/chunk-J6DS34J4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ready.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMO,IAAM,mBAAA,GAAsB;AAG5B,IAAM,oBAAA,GAAuB","file":"chunk-J6DS34J4.js","sourcesContent":["/**\n * The test id of the node `harnessed()` adds once a story has rendered and its\n * play function has finished. `StoryPage` waits for it: Storybook's own\n * \"rendered\" signal is a channel event, which a runner outside the iframe's\n * realm cannot listen for, while a node is something every driver can count.\n */\nexport const STORY_READY_TEST_ID = 'harnessed-story-ready'\n\n/** Set on that node when the play function threw, holding the error's message. */\nexport const PLAY_ERROR_ATTRIBUTE = 'data-harnessed-play-error'\n"]}

package/dist/index.cjs

@@ -0,0 +1,143 @@
+'use strict';
+
+var core = require('@harnessed-ts/core');
+var dom = require('@harnessed-ts/dom');
+var coreEvents = require('storybook/internal/core-events');
+var previewApi = require('storybook/preview-api');
+var test = require('storybook/test');
+
+// src/index.ts
+
+// src/ready.ts
+var STORY_READY_TEST_ID = "harnessed-story-ready";
+var PLAY_ERROR_ATTRIBUTE = "data-harnessed-play-error";
+var SECRET = /pass|secret|token|credential/i;
+var SECRET_WORD = /^(key|pin|otp|auth)$/i;
+var WORD_BREAK = /[^a-zA-Z0-9]+|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/;
+var REDACTED = "\u2022\u2022\u2022";
+var MAX_ARG = 40;
+var AsyncFunction = (async () => {
+}).constructor;
+var proxies = /* @__PURE__ */ new WeakMap();
+function withSteps(harness, step) {
+  const cached = proxies.get(harness);
+  if (cached !== void 0) return cached;
+  const className = harness.constructor.name;
+  const wrap = (value) => {
+    if (value instanceof core.ScopedHarness) return withSteps(value, step);
+    if (Array.isArray(value) && value.some((item) => item instanceof core.ScopedHarness)) {
+      return value.map(wrap);
+    }
+    return value;
+  };
+  const proxy = new Proxy(harness, {
+    get(target, prop) {
+      const value = Reflect.get(target, prop, target);
+      if (typeof value !== "function") return wrap(value);
+      if (typeof prop !== "string" || prop === "constructor" || prop.startsWith("_")) {
+        return value.bind(target);
+      }
+      const method = value;
+      if (method instanceof AsyncFunction) {
+        return async (...args) => {
+          let result;
+          await step(stepLabel(className, method, args, prop), async () => {
+            result = await method.apply(target, args);
+          });
+          return wrap(result);
+        };
+      }
+      return (...args) => wrap(method.apply(target, args));
+    },
+    // An accessor's setter writes a private slot only the real instance has.
+    set: (target, prop, value) => Reflect.set(target, prop, value, target)
+  });
+  proxies.set(harness, proxy);
+  return proxy;
+}
+function stepLabel(className, method, args, name = method.name) {
+  const params = parameterNames(method);
+  const shown = args.map(
+    (arg, index) => isSecret(params[index] ?? "") ? JSON.stringify(REDACTED) : formatArg(arg)
+  );
+  return `${className}.${name}(${shown.join(", ")})`;
+}
+function isSecret(name) {
+  return SECRET.test(name) || name.split(WORD_BREAK).some((word) => SECRET_WORD.test(word));
+}
+function formatArg(arg) {
+  if (typeof arg === "function") return "\u0192";
+  if (arg instanceof core.ScopedHarness) return arg.constructor.name;
+  if (typeof arg === "string") {
+    return JSON.stringify(arg.length > MAX_ARG ? `${arg.slice(0, MAX_ARG)}\u2026` : arg);
+  }
+  const json = JSON.stringify(arg, (key, value) => isSecret(key) ? REDACTED : value) ?? String(arg);
+  return json.length > MAX_ARG ? `${json.slice(0, MAX_ARG)}\u2026` : json;
+}
+function parameterNames(method) {
+  const list = /\(([^)]*)\)/.exec(Function.prototype.toString.call(method))?.[1] ?? "";
+  if (/[{[]/.test(list)) return [];
+  return list.split(",").map((param) => param.replace(/[=:].*$/s, "").trim());
+}
+
+// src/index.ts
+var matchersRegistered = false;
+var listening = false;
+var playError;
+function listenForPlayErrors() {
+  if (listening || !previewApi.addons.hasChannel()) return;
+  previewApi.addons.getChannel().on(coreEvents.PLAY_FUNCTION_THREW_EXCEPTION, (error) => {
+    playError = error?.message ?? "the play function threw";
+  });
+  listening = true;
+}
+function harnessed() {
+  if (!matchersRegistered) {
+    test.expect.extend(core.harnessMatchers);
+    matchersRegistered = true;
+  }
+  return {
+    async beforeEach(context) {
+      readyMarker(context.canvasElement.ownerDocument)?.remove();
+      listenForPlayErrors();
+      playError = void 0;
+      const HarnessClass = context.parameters.harness;
+      if (HarnessClass === void 0) return;
+      const env = dom.dom({
+        // Storybook's own instance, so each keystroke shows up in the panel. It
+        // is only set where a clipboard exists; fall back to a plain one.
+        user: hasClick(context.userEvent) ? context.userEvent : test.userEvent.setup(),
+        container: context.canvasElement
+      });
+      context.harness = withSteps(new HarnessClass(env), context.step);
+    },
+    async afterEach(context) {
+      const document = context.canvasElement.ownerDocument;
+      if (readyMarker(document) !== null) return;
+      const marker = document.createElement("div");
+      const attribute = core.getConfig().testIdAttribute;
+      if (attribute.endsWith("*"))
+        marker.setAttribute(attribute.slice(0, -1) + STORY_READY_TEST_ID, "");
+      else marker.setAttribute(attribute, STORY_READY_TEST_ID);
+      marker.hidden = true;
+      if (playError !== void 0) marker.setAttribute(PLAY_ERROR_ATTRIBUTE, playError);
+      document.body.append(marker);
+    }
+  };
+}
+function readyMarker(document) {
+  const attribute = core.getConfig().testIdAttribute;
+  const presence = core.testIdPresenceSelector(attribute, STORY_READY_TEST_ID);
+  return document.querySelector(presence ?? `[${attribute}="${STORY_READY_TEST_ID}"]`);
+}
+function hasClick(value) {
+  return typeof value?.click === "function";
+}
+
+exports.PLAY_ERROR_ATTRIBUTE = PLAY_ERROR_ATTRIBUTE;
+exports.STORY_READY_TEST_ID = STORY_READY_TEST_ID;
+exports.harnessed = harnessed;
+exports.stepLabel = stepLabel;
+exports.withSteps = withSteps;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ready.ts","../src/steps.ts","../src/index.ts"],"names":["ScopedHarness","addons","PLAY_FUNCTION_THREW_EXCEPTION","expect","harnessMatchers","dom","userEvent","getConfig","testIdPresenceSelector"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * The test id of the node `harnessed()` adds once a story has rendered and its\n * play function has finished. `StoryPage` waits for it: Storybook's own\n * \"rendered\" signal is a channel event, which a runner outside the iframe's\n * realm cannot listen for, while a node is something every driver can count.\n */\nexport const STORY_READY_TEST_ID = 'harnessed-story-ready'\n\n/** Set on that node when the play function threw, holding the error's message. */\nexport const PLAY_ERROR_ATTRIBUTE = 'data-harnessed-play-error'\n","import { ScopedHarness } from '@harnessed-ts/core'\n\n/** Storybook's `context.step`, narrowed to what the proxy needs. */\nexport type StepRunner = (label: string, play: () => Promise<void>) => Promise<unknown> | unknown\n\nconst SECRET = /pass|secret|token|credential/i\n// Short names match whole words only, so `author`, `keyboard` and `typing` stay visible.\nconst SECRET_WORD = /^(key|pin|otp|auth)$/i\n// camelCase, PascalCase acronyms (`APIKey`) and snake/kebab-case word breaks.\nconst WORD_BREAK = /[^a-zA-Z0-9]+|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/\nconst REDACTED = '•••'\nconst MAX_ARG = 40\n\nconst AsyncFunction = (async () => {}).constructor\n\nconst proxies = new WeakMap<object, unknown>()\n\n/**\n * The harness, with every public async method run inside `step()` — so the\n * Interactions panel reads `LoginFormHarness.signInAs(\"ada@…\", \"•••\")` with the\n * raw clicks and keystrokes nested under it, rather than a flat list of events.\n *\n * Methods run against the real instance, not the proxy: a harness calling its\n * own methods does not log a step per call, and decorated `accessor` fields\n * (backed by private slots a proxy cannot reach) keep working. Sync methods stay\n * sync; a harness they return — `nth()`, a child — comes back wrapped too.\n *\n * shortcut: async is detected by `AsyncFunction`, so a plain method that returns\n * a promise, or one down-levelled to a generator, logs no step. Upgrade if a\n * harness or a build ever needs that.\n */\nexport function withSteps<T extends ScopedHarness>(harness: T, step: StepRunner): T {\n  const cached = proxies.get(harness)\n  if (cached !== undefined) return cached as T\n  const className = harness.constructor.name\n\n  const wrap = (value: unknown): unknown => {\n    if (value instanceof ScopedHarness) return withSteps(value, step)\n    if (Array.isArray(value) && value.some(item => item instanceof ScopedHarness)) {\n      return value.map(wrap)\n    }\n    return value\n  }\n\n  const proxy = new Proxy(harness, {\n    get(target, prop) {\n      const value: unknown = Reflect.get(target, prop, target)\n      if (typeof value !== 'function') return wrap(value)\n      if (typeof prop !== 'string' || prop === 'constructor' || prop.startsWith('_')) {\n        return (value as (...args: unknown[]) => unknown).bind(target)\n      }\n      const method = value as (...args: unknown[]) => unknown\n      if (method instanceof AsyncFunction) {\n        return async (...args: unknown[]) => {\n          let result: unknown\n          await step(stepLabel(className, method, args, prop), async () => {\n            result = await method.apply(target, args)\n          })\n          return wrap(result)\n        }\n      }\n      return (...args: unknown[]) => wrap(method.apply(target, args))\n    },\n    // An accessor's setter writes a private slot only the real instance has.\n    set: (target, prop, value) => Reflect.set(target, prop, value, target),\n  })\n  proxies.set(harness, proxy)\n  return proxy\n}\n\n/**\n * `Harness.method(args…)`, each argument shortened, and any argument whose\n * parameter name — or object key — looks like a secret replaced with `•••`.\n *\n * Names are read from the source, so a minified `storybook build` shows mangled\n * class names and masks only object keys, not positional arguments.\n */\nexport function stepLabel(\n  className: string,\n  method: (...args: never[]) => unknown,\n  args: readonly unknown[],\n  name: string = method.name,\n): string {\n  const params = parameterNames(method)\n  const shown = args.map((arg, index) =>\n    isSecret(params[index] ?? '') ? JSON.stringify(REDACTED) : formatArg(arg),\n  )\n  return `${className}.${name}(${shown.join(', ')})`\n}\n\nfunction isSecret(name: string): boolean {\n  return SECRET.test(name) || name.split(WORD_BREAK).some(word => SECRET_WORD.test(word))\n}\n\nfunction formatArg(arg: unknown): string {\n  if (typeof arg === 'function') return 'ƒ'\n  if (arg instanceof ScopedHarness) return arg.constructor.name\n  if (typeof arg === 'string') {\n    return JSON.stringify(arg.length > MAX_ARG ? `${arg.slice(0, MAX_ARG)}…` : arg)\n  }\n  const json =\n    JSON.stringify(arg, (key, value: unknown) => (isSecret(key) ? REDACTED : value)) ?? String(arg)\n  return json.length > MAX_ARG ? `${json.slice(0, MAX_ARG)}…` : json\n}\n\n/** Plain parameter names from the source; none when they are destructured. */\nfunction parameterNames(method: (...args: never[]) => unknown): string[] {\n  const list = /\\(([^)]*)\\)/.exec(Function.prototype.toString.call(method))?.[1] ?? ''\n  if (/[{[]/.test(list)) return []\n  return list.split(',').map(param => param.replace(/[=:].*$/s, '').trim())\n}\n","import { getConfig, harnessMatchers, testIdPresenceSelector } from '@harnessed-ts/core'\nimport type { Assertable, ScopedHarness, ScopedHarnessConstructor } from '@harnessed-ts/core'\nimport { dom } from '@harnessed-ts/dom'\nimport type { UserEvent } from '@testing-library/user-event'\nimport { PLAY_FUNCTION_THREW_EXCEPTION } from 'storybook/internal/core-events'\nimport { addons } from 'storybook/preview-api'\nimport { expect, userEvent } from 'storybook/test'\nimport { PLAY_ERROR_ATTRIBUTE, STORY_READY_TEST_ID } from './ready'\nimport { withSteps } from './steps'\nimport type { StepRunner } from './steps'\n\nexport { PLAY_ERROR_ATTRIBUTE, STORY_READY_TEST_ID } from './ready'\nexport { stepLabel, withSteps } from './steps'\nexport type { StepRunner } from './steps'\n\n/** What `harnessed()` reads from, and adds to, Storybook's story context. */\nexport interface HarnessedContext {\n  canvasElement: HTMLElement\n  parameters: { harness?: ScopedHarnessConstructor }\n  userEvent?: unknown\n  step: StepRunner\n  harness?: ScopedHarness\n}\n\nlet matchersRegistered = false\nlet listening = false\n/** The message of the current story's play error, if it threw. */\nlet playError: string | undefined\n\n/**\n * Storybook catches a play function's error, reports it on its channel, and\n * then finishes the render (running `afterEach`) as if it had passed, so the\n * error has to be caught here to reach the ready mark.\n */\nfunction listenForPlayErrors(): void {\n  if (listening || !addons.hasChannel()) return\n  addons.getChannel().on(PLAY_FUNCTION_THREW_EXCEPTION, (error?: { message?: string }) => {\n    playError = error?.message ?? 'the play function threw'\n  })\n  listening = true\n}\n\n/**\n * Preview annotations that put a harness in every play function. Spread them\n * into `.storybook/preview.ts`:\n *\n * ```ts\n * import { harnessed } from '@harnessed-ts/storybook'\n * export default { ...harnessed() } satisfies Preview\n * ```\n *\n * A story (or its meta) names its harness in `parameters.harness`, and `play`\n * receives it as `context.harness`, driving the canvas through Storybook's\n * instrumented `userEvent` with each method logged as a step. The harness\n * matchers are added to `storybook/test`'s `expect`.\n */\nexport function harnessed(): {\n  beforeEach: (context: HarnessedContext) => Promise<void>\n  afterEach: (context: HarnessedContext) => Promise<void>\n} {\n  if (!matchersRegistered) {\n    expect.extend(harnessMatchers)\n    matchersRegistered = true\n  }\n  return {\n    async beforeEach(context: HarnessedContext) {\n      readyMarker(context.canvasElement.ownerDocument)?.remove()\n      listenForPlayErrors()\n      playError = undefined\n      const HarnessClass = context.parameters.harness\n      if (HarnessClass === undefined) return\n      const env = dom({\n        // Storybook's own instance, so each keystroke shows up in the panel. It\n        // is only set where a clipboard exists; fall back to a plain one.\n        user: (hasClick(context.userEvent) ? context.userEvent : userEvent.setup()) as UserEvent,\n        container: context.canvasElement,\n      })\n      context.harness = withSteps(new HarnessClass(env), context.step)\n    },\n    async afterEach(context: HarnessedContext) {\n      const document = context.canvasElement.ownerDocument\n      if (readyMarker(document) !== null) return\n      const marker = document.createElement('div')\n      const attribute = getConfig().testIdAttribute\n      // Under a presence pattern the id is part of the name: `data-test-<id>`.\n      if (attribute.endsWith('*'))\n        marker.setAttribute(attribute.slice(0, -1) + STORY_READY_TEST_ID, '')\n      else marker.setAttribute(attribute, STORY_READY_TEST_ID)\n      marker.hidden = true\n      if (playError !== undefined) marker.setAttribute(PLAY_ERROR_ATTRIBUTE, playError)\n      document.body.append(marker)\n    },\n  }\n}\n\n/** Found the way `testId(STORY_READY_TEST_ID)` finds it, which is what `StoryPage` waits on. */\nfunction readyMarker(document: Document): Element | null {\n  const attribute = getConfig().testIdAttribute\n  const presence = testIdPresenceSelector(attribute, STORY_READY_TEST_ID)\n  return document.querySelector(presence ?? `[${attribute}=\"${STORY_READY_TEST_ID}\"]`)\n}\n\nfunction hasClick(value: unknown): boolean {\n  return typeof (value as { click?: unknown } | undefined)?.click === 'function'\n}\n\n/**\n * A story type whose `play` receives `harness` typed as `H`.\n *\n * ```ts\n * type Story = WithHarness<StoryObj<typeof meta>, LoginFormHarness>\n * ```\n */\nexport type WithHarness<S, H extends ScopedHarness> = Omit<S, 'play'> & {\n  play?: S extends { play?: infer P }\n    ? P extends (context: infer C) => infer R\n      ? (context: C & { harness: H }) => R\n      : never\n    : never\n}\n\ndeclare module 'storybook/test' {\n  // The type parameter must keep Storybook's own name. Gating on `T` makes calling\n  // these on something that is not a target or a harness a type error.\n  interface Assertion<T> {\n    toBeSelected(): T extends Assertable ? Promise<void> : never\n    toBeAbsent(): T extends Assertable ? Promise<void> : never\n    toReadAs(expected: string | RegExp): T extends Assertable ? Promise<void> : never\n  }\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import type { Assertable, ScopedHarness, ScopedHarnessConstructor } from '@harnessed-ts/core';
+import type { StepRunner } from './steps';
+export { PLAY_ERROR_ATTRIBUTE, STORY_READY_TEST_ID } from './ready';
+export { stepLabel, withSteps } from './steps';
+export type { StepRunner } from './steps';
+/** What `harnessed()` reads from, and adds to, Storybook's story context. */
+export interface HarnessedContext {
+    canvasElement: HTMLElement;
+    parameters: {
+        harness?: ScopedHarnessConstructor;
+    };
+    userEvent?: unknown;
+    step: StepRunner;
+    harness?: ScopedHarness;
+}
+/**
+ * Preview annotations that put a harness in every play function. Spread them
+ * into `.storybook/preview.ts`:
+ *
+ * ```ts
+ * import { harnessed } from '@harnessed-ts/storybook'
+ * export default { ...harnessed() } satisfies Preview
+ * ```
+ *
+ * A story (or its meta) names its harness in `parameters.harness`, and `play`
+ * receives it as `context.harness`, driving the canvas through Storybook's
+ * instrumented `userEvent` with each method logged as a step. The harness
+ * matchers are added to `storybook/test`'s `expect`.
+ */
+export declare function harnessed(): {
+    beforeEach: (context: HarnessedContext) => Promise<void>;
+    afterEach: (context: HarnessedContext) => Promise<void>;
+};
+/**
+ * A story type whose `play` receives `harness` typed as `H`.
+ *
+ * ```ts
+ * type Story = WithHarness<StoryObj<typeof meta>, LoginFormHarness>
+ * ```
+ */
+export type WithHarness<S, H extends ScopedHarness> = Omit<S, 'play'> & {
+    play?: S extends {
+        play?: infer P;
+    } ? P extends (context: infer C) => infer R ? (context: C & {
+        harness: H;
+    }) => R : never : never;
+};
+declare module 'storybook/test' {
+    interface Assertion<T> {
+        toBeSelected(): T extends Assertable ? Promise<void> : never;
+        toBeAbsent(): T extends Assertable ? Promise<void> : never;
+        toReadAs(expected: string | RegExp): T extends Assertable ? Promise<void> : never;
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAQ7F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AACnE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAC9C,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,WAAW,CAAA;IAC1B,UAAU,EAAE;QAAE,OAAO,CAAC,EAAE,wBAAwB,CAAA;KAAE,CAAA;IAClD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,IAAI,EAAE,UAAU,CAAA;IAChB,OAAO,CAAC,EAAE,aAAa,CAAA;CACxB;AAoBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,IAAI;IAC3B,UAAU,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,SAAS,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACxD,CAkCA;AAaD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,aAAa,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG;IACtE,IAAI,CAAC,EAAE,CAAC,SAAS;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAA;KAAE,GAC/B,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,GACrC,CAAC,OAAO,EAAE,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC,CAAA;KAAE,KAAK,CAAC,GAClC,KAAK,GACP,KAAK,CAAA;CACV,CAAA;AAED,OAAO,QAAQ,gBAAgB,CAAC;IAG9B,UAAU,SAAS,CAAC,CAAC;QACnB,YAAY,IAAI,CAAC,SAAS,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;QAC5D,UAAU,IAAI,CAAC,SAAS,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;QAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,SAAS,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;KAClF;CACF"}

package/dist/index.js

@@ -0,0 +1,134 @@
+import { STORY_READY_TEST_ID, PLAY_ERROR_ATTRIBUTE } from './chunk-J6DS34J4.js';
+export { PLAY_ERROR_ATTRIBUTE, STORY_READY_TEST_ID } from './chunk-J6DS34J4.js';
+import { ScopedHarness, harnessMatchers, getConfig, testIdPresenceSelector } from '@harnessed-ts/core';
+import { dom } from '@harnessed-ts/dom';
+import { PLAY_FUNCTION_THREW_EXCEPTION } from 'storybook/internal/core-events';
+import { addons } from 'storybook/preview-api';
+import { expect, userEvent } from 'storybook/test';
+
+var SECRET = /pass|secret|token|credential/i;
+var SECRET_WORD = /^(key|pin|otp|auth)$/i;
+var WORD_BREAK = /[^a-zA-Z0-9]+|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/;
+var REDACTED = "\u2022\u2022\u2022";
+var MAX_ARG = 40;
+var AsyncFunction = (async () => {
+}).constructor;
+var proxies = /* @__PURE__ */ new WeakMap();
+function withSteps(harness, step) {
+  const cached = proxies.get(harness);
+  if (cached !== void 0) return cached;
+  const className = harness.constructor.name;
+  const wrap = (value) => {
+    if (value instanceof ScopedHarness) return withSteps(value, step);
+    if (Array.isArray(value) && value.some((item) => item instanceof ScopedHarness)) {
+      return value.map(wrap);
+    }
+    return value;
+  };
+  const proxy = new Proxy(harness, {
+    get(target, prop) {
+      const value = Reflect.get(target, prop, target);
+      if (typeof value !== "function") return wrap(value);
+      if (typeof prop !== "string" || prop === "constructor" || prop.startsWith("_")) {
+        return value.bind(target);
+      }
+      const method = value;
+      if (method instanceof AsyncFunction) {
+        return async (...args) => {
+          let result;
+          await step(stepLabel(className, method, args, prop), async () => {
+            result = await method.apply(target, args);
+          });
+          return wrap(result);
+        };
+      }
+      return (...args) => wrap(method.apply(target, args));
+    },
+    // An accessor's setter writes a private slot only the real instance has.
+    set: (target, prop, value) => Reflect.set(target, prop, value, target)
+  });
+  proxies.set(harness, proxy);
+  return proxy;
+}
+function stepLabel(className, method, args, name = method.name) {
+  const params = parameterNames(method);
+  const shown = args.map(
+    (arg, index) => isSecret(params[index] ?? "") ? JSON.stringify(REDACTED) : formatArg(arg)
+  );
+  return `${className}.${name}(${shown.join(", ")})`;
+}
+function isSecret(name) {
+  return SECRET.test(name) || name.split(WORD_BREAK).some((word) => SECRET_WORD.test(word));
+}
+function formatArg(arg) {
+  if (typeof arg === "function") return "\u0192";
+  if (arg instanceof ScopedHarness) return arg.constructor.name;
+  if (typeof arg === "string") {
+    return JSON.stringify(arg.length > MAX_ARG ? `${arg.slice(0, MAX_ARG)}\u2026` : arg);
+  }
+  const json = JSON.stringify(arg, (key, value) => isSecret(key) ? REDACTED : value) ?? String(arg);
+  return json.length > MAX_ARG ? `${json.slice(0, MAX_ARG)}\u2026` : json;
+}
+function parameterNames(method) {
+  const list = /\(([^)]*)\)/.exec(Function.prototype.toString.call(method))?.[1] ?? "";
+  if (/[{[]/.test(list)) return [];
+  return list.split(",").map((param) => param.replace(/[=:].*$/s, "").trim());
+}
+
+// src/index.ts
+var matchersRegistered = false;
+var listening = false;
+var playError;
+function listenForPlayErrors() {
+  if (listening || !addons.hasChannel()) return;
+  addons.getChannel().on(PLAY_FUNCTION_THREW_EXCEPTION, (error) => {
+    playError = error?.message ?? "the play function threw";
+  });
+  listening = true;
+}
+function harnessed() {
+  if (!matchersRegistered) {
+    expect.extend(harnessMatchers);
+    matchersRegistered = true;
+  }
+  return {
+    async beforeEach(context) {
+      readyMarker(context.canvasElement.ownerDocument)?.remove();
+      listenForPlayErrors();
+      playError = void 0;
+      const HarnessClass = context.parameters.harness;
+      if (HarnessClass === void 0) return;
+      const env = dom({
+        // Storybook's own instance, so each keystroke shows up in the panel. It
+        // is only set where a clipboard exists; fall back to a plain one.
+        user: hasClick(context.userEvent) ? context.userEvent : userEvent.setup(),
+        container: context.canvasElement
+      });
+      context.harness = withSteps(new HarnessClass(env), context.step);
+    },
+    async afterEach(context) {
+      const document = context.canvasElement.ownerDocument;
+      if (readyMarker(document) !== null) return;
+      const marker = document.createElement("div");
+      const attribute = getConfig().testIdAttribute;
+      if (attribute.endsWith("*"))
+        marker.setAttribute(attribute.slice(0, -1) + STORY_READY_TEST_ID, "");
+      else marker.setAttribute(attribute, STORY_READY_TEST_ID);
+      marker.hidden = true;
+      if (playError !== void 0) marker.setAttribute(PLAY_ERROR_ATTRIBUTE, playError);
+      document.body.append(marker);
+    }
+  };
+}
+function readyMarker(document) {
+  const attribute = getConfig().testIdAttribute;
+  const presence = testIdPresenceSelector(attribute, STORY_READY_TEST_ID);
+  return document.querySelector(presence ?? `[${attribute}="${STORY_READY_TEST_ID}"]`);
+}
+function hasClick(value) {
+  return typeof value?.click === "function";
+}
+
+export { harnessed, stepLabel, withSteps };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/steps.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { ScopedHarness } from '@harnessed-ts/core'\n\n/** Storybook's `context.step`, narrowed to what the proxy needs. */\nexport type StepRunner = (label: string, play: () => Promise<void>) => Promise<unknown> | unknown\n\nconst SECRET = /pass|secret|token|credential/i\n// Short names match whole words only, so `author`, `keyboard` and `typing` stay visible.\nconst SECRET_WORD = /^(key|pin|otp|auth)$/i\n// camelCase, PascalCase acronyms (`APIKey`) and snake/kebab-case word breaks.\nconst WORD_BREAK = /[^a-zA-Z0-9]+|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/\nconst REDACTED = '•••'\nconst MAX_ARG = 40\n\nconst AsyncFunction = (async () => {}).constructor\n\nconst proxies = new WeakMap<object, unknown>()\n\n/**\n * The harness, with every public async method run inside `step()` — so the\n * Interactions panel reads `LoginFormHarness.signInAs(\"ada@…\", \"•••\")` with the\n * raw clicks and keystrokes nested under it, rather than a flat list of events.\n *\n * Methods run against the real instance, not the proxy: a harness calling its\n * own methods does not log a step per call, and decorated `accessor` fields\n * (backed by private slots a proxy cannot reach) keep working. Sync methods stay\n * sync; a harness they return — `nth()`, a child — comes back wrapped too.\n *\n * shortcut: async is detected by `AsyncFunction`, so a plain method that returns\n * a promise, or one down-levelled to a generator, logs no step. Upgrade if a\n * harness or a build ever needs that.\n */\nexport function withSteps<T extends ScopedHarness>(harness: T, step: StepRunner): T {\n  const cached = proxies.get(harness)\n  if (cached !== undefined) return cached as T\n  const className = harness.constructor.name\n\n  const wrap = (value: unknown): unknown => {\n    if (value instanceof ScopedHarness) return withSteps(value, step)\n    if (Array.isArray(value) && value.some(item => item instanceof ScopedHarness)) {\n      return value.map(wrap)\n    }\n    return value\n  }\n\n  const proxy = new Proxy(harness, {\n    get(target, prop) {\n      const value: unknown = Reflect.get(target, prop, target)\n      if (typeof value !== 'function') return wrap(value)\n      if (typeof prop !== 'string' || prop === 'constructor' || prop.startsWith('_')) {\n        return (value as (...args: unknown[]) => unknown).bind(target)\n      }\n      const method = value as (...args: unknown[]) => unknown\n      if (method instanceof AsyncFunction) {\n        return async (...args: unknown[]) => {\n          let result: unknown\n          await step(stepLabel(className, method, args, prop), async () => {\n            result = await method.apply(target, args)\n          })\n          return wrap(result)\n        }\n      }\n      return (...args: unknown[]) => wrap(method.apply(target, args))\n    },\n    // An accessor's setter writes a private slot only the real instance has.\n    set: (target, prop, value) => Reflect.set(target, prop, value, target),\n  })\n  proxies.set(harness, proxy)\n  return proxy\n}\n\n/**\n * `Harness.method(args…)`, each argument shortened, and any argument whose\n * parameter name — or object key — looks like a secret replaced with `•••`.\n *\n * Names are read from the source, so a minified `storybook build` shows mangled\n * class names and masks only object keys, not positional arguments.\n */\nexport function stepLabel(\n  className: string,\n  method: (...args: never[]) => unknown,\n  args: readonly unknown[],\n  name: string = method.name,\n): string {\n  const params = parameterNames(method)\n  const shown = args.map((arg, index) =>\n    isSecret(params[index] ?? '') ? JSON.stringify(REDACTED) : formatArg(arg),\n  )\n  return `${className}.${name}(${shown.join(', ')})`\n}\n\nfunction isSecret(name: string): boolean {\n  return SECRET.test(name) || name.split(WORD_BREAK).some(word => SECRET_WORD.test(word))\n}\n\nfunction formatArg(arg: unknown): string {\n  if (typeof arg === 'function') return 'ƒ'\n  if (arg instanceof ScopedHarness) return arg.constructor.name\n  if (typeof arg === 'string') {\n    return JSON.stringify(arg.length > MAX_ARG ? `${arg.slice(0, MAX_ARG)}…` : arg)\n  }\n  const json =\n    JSON.stringify(arg, (key, value: unknown) => (isSecret(key) ? REDACTED : value)) ?? String(arg)\n  return json.length > MAX_ARG ? `${json.slice(0, MAX_ARG)}…` : json\n}\n\n/** Plain parameter names from the source; none when they are destructured. */\nfunction parameterNames(method: (...args: never[]) => unknown): string[] {\n  const list = /\\(([^)]*)\\)/.exec(Function.prototype.toString.call(method))?.[1] ?? ''\n  if (/[{[]/.test(list)) return []\n  return list.split(',').map(param => param.replace(/[=:].*$/s, '').trim())\n}\n","import { getConfig, harnessMatchers, testIdPresenceSelector } from '@harnessed-ts/core'\nimport type { Assertable, ScopedHarness, ScopedHarnessConstructor } from '@harnessed-ts/core'\nimport { dom } from '@harnessed-ts/dom'\nimport type { UserEvent } from '@testing-library/user-event'\nimport { PLAY_FUNCTION_THREW_EXCEPTION } from 'storybook/internal/core-events'\nimport { addons } from 'storybook/preview-api'\nimport { expect, userEvent } from 'storybook/test'\nimport { PLAY_ERROR_ATTRIBUTE, STORY_READY_TEST_ID } from './ready'\nimport { withSteps } from './steps'\nimport type { StepRunner } from './steps'\n\nexport { PLAY_ERROR_ATTRIBUTE, STORY_READY_TEST_ID } from './ready'\nexport { stepLabel, withSteps } from './steps'\nexport type { StepRunner } from './steps'\n\n/** What `harnessed()` reads from, and adds to, Storybook's story context. */\nexport interface HarnessedContext {\n  canvasElement: HTMLElement\n  parameters: { harness?: ScopedHarnessConstructor }\n  userEvent?: unknown\n  step: StepRunner\n  harness?: ScopedHarness\n}\n\nlet matchersRegistered = false\nlet listening = false\n/** The message of the current story's play error, if it threw. */\nlet playError: string | undefined\n\n/**\n * Storybook catches a play function's error, reports it on its channel, and\n * then finishes the render (running `afterEach`) as if it had passed, so the\n * error has to be caught here to reach the ready mark.\n */\nfunction listenForPlayErrors(): void {\n  if (listening || !addons.hasChannel()) return\n  addons.getChannel().on(PLAY_FUNCTION_THREW_EXCEPTION, (error?: { message?: string }) => {\n    playError = error?.message ?? 'the play function threw'\n  })\n  listening = true\n}\n\n/**\n * Preview annotations that put a harness in every play function. Spread them\n * into `.storybook/preview.ts`:\n *\n * ```ts\n * import { harnessed } from '@harnessed-ts/storybook'\n * export default { ...harnessed() } satisfies Preview\n * ```\n *\n * A story (or its meta) names its harness in `parameters.harness`, and `play`\n * receives it as `context.harness`, driving the canvas through Storybook's\n * instrumented `userEvent` with each method logged as a step. The harness\n * matchers are added to `storybook/test`'s `expect`.\n */\nexport function harnessed(): {\n  beforeEach: (context: HarnessedContext) => Promise<void>\n  afterEach: (context: HarnessedContext) => Promise<void>\n} {\n  if (!matchersRegistered) {\n    expect.extend(harnessMatchers)\n    matchersRegistered = true\n  }\n  return {\n    async beforeEach(context: HarnessedContext) {\n      readyMarker(context.canvasElement.ownerDocument)?.remove()\n      listenForPlayErrors()\n      playError = undefined\n      const HarnessClass = context.parameters.harness\n      if (HarnessClass === undefined) return\n      const env = dom({\n        // Storybook's own instance, so each keystroke shows up in the panel. It\n        // is only set where a clipboard exists; fall back to a plain one.\n        user: (hasClick(context.userEvent) ? context.userEvent : userEvent.setup()) as UserEvent,\n        container: context.canvasElement,\n      })\n      context.harness = withSteps(new HarnessClass(env), context.step)\n    },\n    async afterEach(context: HarnessedContext) {\n      const document = context.canvasElement.ownerDocument\n      if (readyMarker(document) !== null) return\n      const marker = document.createElement('div')\n      const attribute = getConfig().testIdAttribute\n      // Under a presence pattern the id is part of the name: `data-test-<id>`.\n      if (attribute.endsWith('*'))\n        marker.setAttribute(attribute.slice(0, -1) + STORY_READY_TEST_ID, '')\n      else marker.setAttribute(attribute, STORY_READY_TEST_ID)\n      marker.hidden = true\n      if (playError !== undefined) marker.setAttribute(PLAY_ERROR_ATTRIBUTE, playError)\n      document.body.append(marker)\n    },\n  }\n}\n\n/** Found the way `testId(STORY_READY_TEST_ID)` finds it, which is what `StoryPage` waits on. */\nfunction readyMarker(document: Document): Element | null {\n  const attribute = getConfig().testIdAttribute\n  const presence = testIdPresenceSelector(attribute, STORY_READY_TEST_ID)\n  return document.querySelector(presence ?? `[${attribute}=\"${STORY_READY_TEST_ID}\"]`)\n}\n\nfunction hasClick(value: unknown): boolean {\n  return typeof (value as { click?: unknown } | undefined)?.click === 'function'\n}\n\n/**\n * A story type whose `play` receives `harness` typed as `H`.\n *\n * ```ts\n * type Story = WithHarness<StoryObj<typeof meta>, LoginFormHarness>\n * ```\n */\nexport type WithHarness<S, H extends ScopedHarness> = Omit<S, 'play'> & {\n  play?: S extends { play?: infer P }\n    ? P extends (context: infer C) => infer R\n      ? (context: C & { harness: H }) => R\n      : never\n    : never\n}\n\ndeclare module 'storybook/test' {\n  // The type parameter must keep Storybook's own name. Gating on `T` makes calling\n  // these on something that is not a target or a harness a type error.\n  interface Assertion<T> {\n    toBeSelected(): T extends Assertable ? Promise<void> : never\n    toBeAbsent(): T extends Assertable ? Promise<void> : never\n    toReadAs(expected: string | RegExp): T extends Assertable ? Promise<void> : never\n  }\n}\n"]}

package/dist/page.cjs

@@ -0,0 +1,120 @@
+'use strict';
+
+var core = require('@harnessed-ts/core');
+var page = require('@harnessed-ts/page');
+var csf = require('storybook/internal/csf');
+
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length; i < n; i++) fns[i].call(self) ;
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var it, done, ctx, k = flags & 7, p = false;
+  var j = 0;
+  var extraInitializers = array[j] || (array[j] = []);
+  var desc = k && ((target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(target , name));
+  __name(target, name);
+  for (var i = decorators.length - 1; i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    it = (0, decorators[i])(target, ctx), done._ = 1;
+    __expectFn(it) && (target = it);
+  }
+  return __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+
+// src/ready.ts
+var STORY_READY_TEST_ID = "harnessed-story-ready";
+var PLAY_ERROR_ATTRIBUTE = "data-harnessed-play-error";
+
+// src/page.ts
+var SAFE_KEY = /^[a-zA-Z0-9 _-]+$/;
+var SAFE_STRING = /^[a-zA-Z0-9 _-]*$/;
+var NUMERIC = /^-?[0-9]+(\.[0-9]+)?$/;
+function storyUrl(stories, name, options = {}) {
+  const title = stories.default.id ?? stories.default.title;
+  if (title === void 0) {
+    throw new Error(
+      `harnessed: the stories module for "${name}" has no \`title\` on its default export, so its story id cannot be derived outside Storybook. Fix: set \`title\` on the meta (or \`id\`, if the story id must not follow the title).`
+    );
+  }
+  const params = [`id=${csf.toId(title, csf.storyNameFromExport(name))}`, "viewMode=story"];
+  const args = encode(options.args ?? {});
+  if (args !== "") params.push(`args=${args}`);
+  const globals = encode(options.globals ?? {});
+  if (globals !== "") params.push(`globals=${globals}`);
+  if (options.play === false) params.push("embed=true");
+  return `/iframe.html?${params.join("&")}`;
+}
+function encode(values) {
+  return Object.entries(values).map(([key, value]) => `${key}:${encodeValue(key, value)}`).join(";");
+}
+function encodeValue(key, value) {
+  if (SAFE_KEY.test(key)) {
+    if (value === void 0) return "!undefined";
+    if (value === null) return "!null";
+    if (typeof value === "boolean") return `!${value}`;
+    if (typeof value === "number" && NUMERIC.test(String(value))) return String(value);
+    if (typeof value === "string" && SAFE_STRING.test(value) && !NUMERIC.test(value)) {
+      return value.replaceAll(" ", "+");
+    }
+  }
+  throw new Error(
+    `harnessed: arg \`${key}\` = ${typeof value === "number" ? value : JSON.stringify(value)} cannot travel in a Storybook URL \u2014 Storybook drops anything but letters, digits, spaces, \`_\`, \`-\`, numbers and booleans (and reads a numeric string back as a number), so the story would render without it. Fix: add a story with that state in its \`args\`.`
+  );
+}
+var _StoryPage_decorators, _init, _a;
+_StoryPage_decorators = [core.Harness({ host: core.testId(STORY_READY_TEST_ID) })];
+var _StoryPage = class _StoryPage extends (_a = page.PageHarness) {
+  #url = "";
+  static async goto(env, stories, name, options) {
+    const story = new _StoryPage(env);
+    story.#url = storyUrl(stories, name, options);
+    await story.goto();
+    return story;
+  }
+  get path() {
+    return this.#url;
+  }
+  /** A harness for something in the story, scoped to the whole iframe. */
+  harness(HarnessClass) {
+    return new HarnessClass(this._env);
+  }
+  async waitForReady() {
+    const deadline = Date.now() + core.timeoutFor();
+    while (await this.self.count() === 0) {
+      if (Date.now() > deadline) {
+        throw new Error(
+          `harnessed: story ${this.#url} did not finish rendering. Either it threw while rendering (open it in Storybook to see why), or \`.storybook/preview.ts\` does not spread \`harnessed()\`.`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    const playError = await this.self.attribute(PLAY_ERROR_ATTRIBUTE);
+    if (playError !== null) {
+      throw new Error(`harnessed: the play function of story ${this.#url} threw: ${playError}`);
+    }
+  }
+};
+_init = __decoratorStart(_a);
+_StoryPage = __decorateElement(_init, 0, "StoryPage", _StoryPage_decorators, _StoryPage);
+__runInitializers(_init, 1, _StoryPage);
+var StoryPage = _StoryPage;
+
+exports.StoryPage = StoryPage;
+exports.storyUrl = storyUrl;
+//# sourceMappingURL=page.cjs.map
+//# sourceMappingURL=page.cjs.map

package/dist/page.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ready.ts","../src/page.ts"],"names":["toId","storyNameFromExport","Harness","testId","PageHarness","timeoutFor"],"mappings":"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","file":"page.cjs","sourcesContent":["/**\n * The test id of the node `harnessed()` adds once a story has rendered and its\n * play function has finished. `StoryPage` waits for it: Storybook's own\n * \"rendered\" signal is a channel event, which a runner outside the iframe's\n * realm cannot listen for, while a node is something every driver can count.\n */\nexport const STORY_READY_TEST_ID = 'harnessed-story-ready'\n\n/** Set on that node when the play function threw, holding the error's message. */\nexport const PLAY_ERROR_ATTRIBUTE = 'data-harnessed-play-error'\n","import { Harness, testId, timeoutFor } from '@harnessed-ts/core'\nimport type { EnvConfig, ScopedHarness, ScopedHarnessConstructor } from '@harnessed-ts/core'\nimport { PageHarness } from '@harnessed-ts/page'\nimport { storyNameFromExport, toId } from 'storybook/internal/csf'\nimport { PLAY_ERROR_ATTRIBUTE, STORY_READY_TEST_ID } from './ready'\n\n/** A CSF module as imported with `import * as Stories from './X.stories'`. */\nexport interface StoriesModule {\n  default: { title?: string; id?: string }\n}\n\n/** The export names in a CSF module that are stories, not the meta. */\nexport type StoryName<M extends StoriesModule> = Exclude<keyof M, 'default'> & string\n\n/** The args a story declares, all optional: a URL overrides some, never must set all. */\nexport type StoryArgs<M extends StoriesModule, K extends StoryName<M>> = Partial<\n  ArgsOf<M[K]> & ArgsOf<M['default']>\n>\n\n// An empty record rather than `never` when there are none: a meta without\n// `args` must not erase the story's own.\ntype ArgsOf<T> = T extends { args?: infer A } ? NonNullable<A> : Record<never, never>\n\nexport interface StoryOptions<Args> {\n  /**\n   * Overrides for the story's args, encoded in Storybook's own URL syntax.\n   * Storybook applies one only when the arg has an argType — inferred from the\n   * component's props, or declared in `argTypes` — and drops it otherwise.\n   */\n  args?: Args\n  /** Toolbar globals — theme, locale, viewport. */\n  globals?: Record<string, Scalar>\n  /**\n   * Whether the story's play function runs. Defaults to `true`, as it does in\n   * Storybook; `false` opens the story in its initial state for the test to drive.\n   */\n  play?: boolean\n}\n\ntype Scalar = string | number | boolean | null | undefined\n\n// Storybook's own rules (storybook/internal/router): it silently drops any arg\n// that fails them, so a test would run against the wrong state. Refuse instead.\nconst SAFE_KEY = /^[a-zA-Z0-9 _-]+$/\n// Storybook reads a numeric-looking string back as a number, so '02134' would\n// arrive as 2134: letters, digits, spaces, `_` and `-`, but not a number.\nconst SAFE_STRING = /^[a-zA-Z0-9 _-]*$/\nconst NUMERIC = /^-?[0-9]+(\\.[0-9]+)?$/\n\n/**\n * The iframe URL of one story — id from the meta and export name, exactly as\n * Storybook derives it — relative to the Storybook root.\n */\nexport function storyUrl<M extends StoriesModule, K extends StoryName<M>>(\n  stories: M,\n  name: K,\n  options: StoryOptions<StoryArgs<M, K>> = {},\n): string {\n  const title = stories.default.id ?? stories.default.title\n  if (title === undefined) {\n    throw new Error(\n      `harnessed: the stories module for \"${name}\" has no \\`title\\` on its default export, ` +\n        'so its story id cannot be derived outside Storybook. Fix: set `title` on the meta ' +\n        '(or `id`, if the story id must not follow the title).',\n    )\n  }\n  const params = [`id=${toId(title, storyNameFromExport(name))}`, 'viewMode=story']\n  const args = encode(options.args ?? {})\n  if (args !== '') params.push(`args=${args}`)\n  const globals = encode(options.globals ?? {})\n  if (globals !== '') params.push(`globals=${globals}`)\n  // The switch Storybook itself reads: an embedded story renders without autoplay.\n  if (options.play === false) params.push('embed=true')\n  return `/iframe.html?${params.join('&')}`\n}\n\nfunction encode(values: Record<string, unknown>): string {\n  return Object.entries(values)\n    .map(([key, value]) => `${key}:${encodeValue(key, value)}`)\n    .join(';')\n}\n\nfunction encodeValue(key: string, value: unknown): string {\n  if (SAFE_KEY.test(key)) {\n    if (value === undefined) return '!undefined'\n    if (value === null) return '!null'\n    if (typeof value === 'boolean') return `!${value}`\n    // NaN, Infinity and exponents (`1e+21`, whose `+` reads back as a space) do not survive.\n    if (typeof value === 'number' && NUMERIC.test(String(value))) return String(value)\n    if (typeof value === 'string' && SAFE_STRING.test(value) && !NUMERIC.test(value)) {\n      return value.replaceAll(' ', '+')\n    }\n  }\n  throw new Error(\n    `harnessed: arg \\`${key}\\` = ${typeof value === 'number' ? value : JSON.stringify(value)} cannot travel in a Storybook URL — ` +\n      'Storybook drops anything but letters, digits, spaces, `_`, `-`, numbers and booleans ' +\n      '(and reads a numeric string back as a number), so the story would render without it. ' +\n      'Fix: add a story with that state in its `args`.',\n  )\n}\n\n/**\n * One Storybook story, opened as a fixture by any runner that can navigate.\n *\n * ```ts\n * import * as LoginStories from './LoginForm.stories'\n * const story = await StoryPage.goto(pw(page), LoginStories, 'Default', { play: false })\n * const form = story.harness(LoginFormHarness)\n * ```\n *\n * Ready means rendered *and* played: it waits for the node `harnessed()` adds\n * after the story's play function finishes, so `.storybook/preview.ts` must\n * spread `harnessed()`.\n */\n@Harness({ host: testId(STORY_READY_TEST_ID) })\nexport class StoryPage extends PageHarness {\n  #url = ''\n\n  static async goto<M extends StoriesModule, K extends StoryName<M>>(\n    env: EnvConfig,\n    stories: M,\n    name: K,\n    options?: StoryOptions<StoryArgs<M, K>>,\n  ): Promise<StoryPage> {\n    const story = new StoryPage(env)\n    story.#url = storyUrl(stories, name, options)\n    await story.goto()\n    return story\n  }\n\n  override get path(): string {\n    return this.#url\n  }\n\n  /** A harness for something in the story, scoped to the whole iframe. */\n  harness<T extends ScopedHarness>(HarnessClass: ScopedHarnessConstructor<T>): T {\n    return new HarnessClass(this._env)\n  }\n\n  protected async waitForReady(): Promise<void> {\n    // The marker is an empty node, so \"visible\" means nothing; count it instead.\n    const deadline = Date.now() + timeoutFor()\n    while ((await this.self.count()) === 0) {\n      if (Date.now() > deadline) {\n        throw new Error(\n          `harnessed: story ${this.#url} did not finish rendering. Either it threw ` +\n            'while rendering (open it in Storybook to see why), or ' +\n            '`.storybook/preview.ts` does not spread `harnessed()`.',\n        )\n      }\n      await new Promise(resolve => setTimeout(resolve, 50))\n    }\n    const playError = await this.self.attribute(PLAY_ERROR_ATTRIBUTE)\n    if (playError !== null) {\n      throw new Error(`harnessed: the play function of story ${this.#url} threw: ${playError}`)\n    }\n  }\n}\n"]}

package/dist/page.d.ts

@@ -0,0 +1,60 @@
+import type { EnvConfig, ScopedHarness, ScopedHarnessConstructor } from '@harnessed-ts/core';
+import { PageHarness } from '@harnessed-ts/page';
+/** A CSF module as imported with `import * as Stories from './X.stories'`. */
+export interface StoriesModule {
+    default: {
+        title?: string;
+        id?: string;
+    };
+}
+/** The export names in a CSF module that are stories, not the meta. */
+export type StoryName<M extends StoriesModule> = Exclude<keyof M, 'default'> & string;
+/** The args a story declares, all optional: a URL overrides some, never must set all. */
+export type StoryArgs<M extends StoriesModule, K extends StoryName<M>> = Partial<ArgsOf<M[K]> & ArgsOf<M['default']>>;
+type ArgsOf<T> = T extends {
+    args?: infer A;
+} ? NonNullable<A> : Record<never, never>;
+export interface StoryOptions<Args> {
+    /**
+     * Overrides for the story's args, encoded in Storybook's own URL syntax.
+     * Storybook applies one only when the arg has an argType — inferred from the
+     * component's props, or declared in `argTypes` — and drops it otherwise.
+     */
+    args?: Args;
+    /** Toolbar globals — theme, locale, viewport. */
+    globals?: Record<string, Scalar>;
+    /**
+     * Whether the story's play function runs. Defaults to `true`, as it does in
+     * Storybook; `false` opens the story in its initial state for the test to drive.
+     */
+    play?: boolean;
+}
+type Scalar = string | number | boolean | null | undefined;
+/**
+ * The iframe URL of one story — id from the meta and export name, exactly as
+ * Storybook derives it — relative to the Storybook root.
+ */
+export declare function storyUrl<M extends StoriesModule, K extends StoryName<M>>(stories: M, name: K, options?: StoryOptions<StoryArgs<M, K>>): string;
+/**
+ * One Storybook story, opened as a fixture by any runner that can navigate.
+ *
+ * ```ts
+ * import * as LoginStories from './LoginForm.stories'
+ * const story = await StoryPage.goto(pw(page), LoginStories, 'Default', { play: false })
+ * const form = story.harness(LoginFormHarness)
+ * ```
+ *
+ * Ready means rendered *and* played: it waits for the node `harnessed()` adds
+ * after the story's play function finishes, so `.storybook/preview.ts` must
+ * spread `harnessed()`.
+ */
+export declare class StoryPage extends PageHarness {
+    #private;
+    static goto<M extends StoriesModule, K extends StoryName<M>>(env: EnvConfig, stories: M, name: K, options?: StoryOptions<StoryArgs<M, K>>): Promise<StoryPage>;
+    get path(): string;
+    /** A harness for something in the story, scoped to the whole iframe. */
+    harness<T extends ScopedHarness>(HarnessClass: ScopedHarnessConstructor<T>): T;
+    protected waitForReady(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=page.d.ts.map

package/dist/page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAC5F,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAIhD,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACzC;AAED,uEAAuE;AACvE,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,CAAA;AAErF,yFAAyF;AACzF,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,IAAI,OAAO,CAC9E,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CACpC,CAAA;AAID,KAAK,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;AAErF,MAAM,WAAW,YAAY,CAAC,IAAI;IAChC;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,KAAK,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;AAU1D;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EACtE,OAAO,EAAE,CAAC,EACV,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,YAAY,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAM,GAC1C,MAAM,CAiBR;AA2BD;;;;;;;;;;;;GAYG;AACH,qBACa,SAAU,SAAQ,WAAW;;WAG3B,IAAI,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EAC/D,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,CAAC,EACV,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,SAAS,CAAC;IAOrB,IAAa,IAAI,IAAI,MAAM,CAE1B;IAED,wEAAwE;IACxE,OAAO,CAAC,CAAC,SAAS,aAAa,EAAE,YAAY,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,CAAC;cAI9D,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAkB9C"}

package/dist/page.js

@@ -0,0 +1,81 @@
+import { STORY_READY_TEST_ID, __decoratorStart, __decorateElement, __runInitializers, PLAY_ERROR_ATTRIBUTE } from './chunk-J6DS34J4.js';
+import { Harness, testId, timeoutFor } from '@harnessed-ts/core';
+import { PageHarness } from '@harnessed-ts/page';
+import { toId, storyNameFromExport } from 'storybook/internal/csf';
+
+var SAFE_KEY = /^[a-zA-Z0-9 _-]+$/;
+var SAFE_STRING = /^[a-zA-Z0-9 _-]*$/;
+var NUMERIC = /^-?[0-9]+(\.[0-9]+)?$/;
+function storyUrl(stories, name, options = {}) {
+  const title = stories.default.id ?? stories.default.title;
+  if (title === void 0) {
+    throw new Error(
+      `harnessed: the stories module for "${name}" has no \`title\` on its default export, so its story id cannot be derived outside Storybook. Fix: set \`title\` on the meta (or \`id\`, if the story id must not follow the title).`
+    );
+  }
+  const params = [`id=${toId(title, storyNameFromExport(name))}`, "viewMode=story"];
+  const args = encode(options.args ?? {});
+  if (args !== "") params.push(`args=${args}`);
+  const globals = encode(options.globals ?? {});
+  if (globals !== "") params.push(`globals=${globals}`);
+  if (options.play === false) params.push("embed=true");
+  return `/iframe.html?${params.join("&")}`;
+}
+function encode(values) {
+  return Object.entries(values).map(([key, value]) => `${key}:${encodeValue(key, value)}`).join(";");
+}
+function encodeValue(key, value) {
+  if (SAFE_KEY.test(key)) {
+    if (value === void 0) return "!undefined";
+    if (value === null) return "!null";
+    if (typeof value === "boolean") return `!${value}`;
+    if (typeof value === "number" && NUMERIC.test(String(value))) return String(value);
+    if (typeof value === "string" && SAFE_STRING.test(value) && !NUMERIC.test(value)) {
+      return value.replaceAll(" ", "+");
+    }
+  }
+  throw new Error(
+    `harnessed: arg \`${key}\` = ${typeof value === "number" ? value : JSON.stringify(value)} cannot travel in a Storybook URL \u2014 Storybook drops anything but letters, digits, spaces, \`_\`, \`-\`, numbers and booleans (and reads a numeric string back as a number), so the story would render without it. Fix: add a story with that state in its \`args\`.`
+  );
+}
+var _StoryPage_decorators, _init, _a;
+_StoryPage_decorators = [Harness({ host: testId(STORY_READY_TEST_ID) })];
+var _StoryPage = class _StoryPage extends (_a = PageHarness) {
+  #url = "";
+  static async goto(env, stories, name, options) {
+    const story = new _StoryPage(env);
+    story.#url = storyUrl(stories, name, options);
+    await story.goto();
+    return story;
+  }
+  get path() {
+    return this.#url;
+  }
+  /** A harness for something in the story, scoped to the whole iframe. */
+  harness(HarnessClass) {
+    return new HarnessClass(this._env);
+  }
+  async waitForReady() {
+    const deadline = Date.now() + timeoutFor();
+    while (await this.self.count() === 0) {
+      if (Date.now() > deadline) {
+        throw new Error(
+          `harnessed: story ${this.#url} did not finish rendering. Either it threw while rendering (open it in Storybook to see why), or \`.storybook/preview.ts\` does not spread \`harnessed()\`.`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    const playError = await this.self.attribute(PLAY_ERROR_ATTRIBUTE);
+    if (playError !== null) {
+      throw new Error(`harnessed: the play function of story ${this.#url} threw: ${playError}`);
+    }
+  }
+};
+_init = __decoratorStart(_a);
+_StoryPage = __decorateElement(_init, 0, "StoryPage", _StoryPage_decorators, _StoryPage);
+__runInitializers(_init, 1, _StoryPage);
+var StoryPage = _StoryPage;
+
+export { StoryPage, storyUrl };
+//# sourceMappingURL=page.js.map
+//# sourceMappingURL=page.js.map

package/dist/page.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/page.ts"],"names":[],"mappings":"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","file":"page.js","sourcesContent":["import { Harness, testId, timeoutFor } from '@harnessed-ts/core'\nimport type { EnvConfig, ScopedHarness, ScopedHarnessConstructor } from '@harnessed-ts/core'\nimport { PageHarness } from '@harnessed-ts/page'\nimport { storyNameFromExport, toId } from 'storybook/internal/csf'\nimport { PLAY_ERROR_ATTRIBUTE, STORY_READY_TEST_ID } from './ready'\n\n/** A CSF module as imported with `import * as Stories from './X.stories'`. */\nexport interface StoriesModule {\n  default: { title?: string; id?: string }\n}\n\n/** The export names in a CSF module that are stories, not the meta. */\nexport type StoryName<M extends StoriesModule> = Exclude<keyof M, 'default'> & string\n\n/** The args a story declares, all optional: a URL overrides some, never must set all. */\nexport type StoryArgs<M extends StoriesModule, K extends StoryName<M>> = Partial<\n  ArgsOf<M[K]> & ArgsOf<M['default']>\n>\n\n// An empty record rather than `never` when there are none: a meta without\n// `args` must not erase the story's own.\ntype ArgsOf<T> = T extends { args?: infer A } ? NonNullable<A> : Record<never, never>\n\nexport interface StoryOptions<Args> {\n  /**\n   * Overrides for the story's args, encoded in Storybook's own URL syntax.\n   * Storybook applies one only when the arg has an argType — inferred from the\n   * component's props, or declared in `argTypes` — and drops it otherwise.\n   */\n  args?: Args\n  /** Toolbar globals — theme, locale, viewport. */\n  globals?: Record<string, Scalar>\n  /**\n   * Whether the story's play function runs. Defaults to `true`, as it does in\n   * Storybook; `false` opens the story in its initial state for the test to drive.\n   */\n  play?: boolean\n}\n\ntype Scalar = string | number | boolean | null | undefined\n\n// Storybook's own rules (storybook/internal/router): it silently drops any arg\n// that fails them, so a test would run against the wrong state. Refuse instead.\nconst SAFE_KEY = /^[a-zA-Z0-9 _-]+$/\n// Storybook reads a numeric-looking string back as a number, so '02134' would\n// arrive as 2134: letters, digits, spaces, `_` and `-`, but not a number.\nconst SAFE_STRING = /^[a-zA-Z0-9 _-]*$/\nconst NUMERIC = /^-?[0-9]+(\\.[0-9]+)?$/\n\n/**\n * The iframe URL of one story — id from the meta and export name, exactly as\n * Storybook derives it — relative to the Storybook root.\n */\nexport function storyUrl<M extends StoriesModule, K extends StoryName<M>>(\n  stories: M,\n  name: K,\n  options: StoryOptions<StoryArgs<M, K>> = {},\n): string {\n  const title = stories.default.id ?? stories.default.title\n  if (title === undefined) {\n    throw new Error(\n      `harnessed: the stories module for \"${name}\" has no \\`title\\` on its default export, ` +\n        'so its story id cannot be derived outside Storybook. Fix: set `title` on the meta ' +\n        '(or `id`, if the story id must not follow the title).',\n    )\n  }\n  const params = [`id=${toId(title, storyNameFromExport(name))}`, 'viewMode=story']\n  const args = encode(options.args ?? {})\n  if (args !== '') params.push(`args=${args}`)\n  const globals = encode(options.globals ?? {})\n  if (globals !== '') params.push(`globals=${globals}`)\n  // The switch Storybook itself reads: an embedded story renders without autoplay.\n  if (options.play === false) params.push('embed=true')\n  return `/iframe.html?${params.join('&')}`\n}\n\nfunction encode(values: Record<string, unknown>): string {\n  return Object.entries(values)\n    .map(([key, value]) => `${key}:${encodeValue(key, value)}`)\n    .join(';')\n}\n\nfunction encodeValue(key: string, value: unknown): string {\n  if (SAFE_KEY.test(key)) {\n    if (value === undefined) return '!undefined'\n    if (value === null) return '!null'\n    if (typeof value === 'boolean') return `!${value}`\n    // NaN, Infinity and exponents (`1e+21`, whose `+` reads back as a space) do not survive.\n    if (typeof value === 'number' && NUMERIC.test(String(value))) return String(value)\n    if (typeof value === 'string' && SAFE_STRING.test(value) && !NUMERIC.test(value)) {\n      return value.replaceAll(' ', '+')\n    }\n  }\n  throw new Error(\n    `harnessed: arg \\`${key}\\` = ${typeof value === 'number' ? value : JSON.stringify(value)} cannot travel in a Storybook URL — ` +\n      'Storybook drops anything but letters, digits, spaces, `_`, `-`, numbers and booleans ' +\n      '(and reads a numeric string back as a number), so the story would render without it. ' +\n      'Fix: add a story with that state in its `args`.',\n  )\n}\n\n/**\n * One Storybook story, opened as a fixture by any runner that can navigate.\n *\n * ```ts\n * import * as LoginStories from './LoginForm.stories'\n * const story = await StoryPage.goto(pw(page), LoginStories, 'Default', { play: false })\n * const form = story.harness(LoginFormHarness)\n * ```\n *\n * Ready means rendered *and* played: it waits for the node `harnessed()` adds\n * after the story's play function finishes, so `.storybook/preview.ts` must\n * spread `harnessed()`.\n */\n@Harness({ host: testId(STORY_READY_TEST_ID) })\nexport class StoryPage extends PageHarness {\n  #url = ''\n\n  static async goto<M extends StoriesModule, K extends StoryName<M>>(\n    env: EnvConfig,\n    stories: M,\n    name: K,\n    options?: StoryOptions<StoryArgs<M, K>>,\n  ): Promise<StoryPage> {\n    const story = new StoryPage(env)\n    story.#url = storyUrl(stories, name, options)\n    await story.goto()\n    return story\n  }\n\n  override get path(): string {\n    return this.#url\n  }\n\n  /** A harness for something in the story, scoped to the whole iframe. */\n  harness<T extends ScopedHarness>(HarnessClass: ScopedHarnessConstructor<T>): T {\n    return new HarnessClass(this._env)\n  }\n\n  protected async waitForReady(): Promise<void> {\n    // The marker is an empty node, so \"visible\" means nothing; count it instead.\n    const deadline = Date.now() + timeoutFor()\n    while ((await this.self.count()) === 0) {\n      if (Date.now() > deadline) {\n        throw new Error(\n          `harnessed: story ${this.#url} did not finish rendering. Either it threw ` +\n            'while rendering (open it in Storybook to see why), or ' +\n            '`.storybook/preview.ts` does not spread `harnessed()`.',\n        )\n      }\n      await new Promise(resolve => setTimeout(resolve, 50))\n    }\n    const playError = await this.self.attribute(PLAY_ERROR_ATTRIBUTE)\n    if (playError !== null) {\n      throw new Error(`harnessed: the play function of story ${this.#url} threw: ${playError}`)\n    }\n  }\n}\n"]}

package/dist/ready.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The test id of the node `harnessed()` adds once a story has rendered and its
+ * play function has finished. `StoryPage` waits for it: Storybook's own
+ * "rendered" signal is a channel event, which a runner outside the iframe's
+ * realm cannot listen for, while a node is something every driver can count.
+ */
+export declare const STORY_READY_TEST_ID = "harnessed-story-ready";
+/** Set on that node when the play function threw, holding the error's message. */
+export declare const PLAY_ERROR_ATTRIBUTE = "data-harnessed-play-error";
+//# sourceMappingURL=ready.d.ts.map

package/dist/ready.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../src/ready.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,0BAA0B,CAAA;AAE1D,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,8BAA8B,CAAA"}

package/dist/steps.d.ts

@@ -0,0 +1,27 @@
+import { ScopedHarness } from '@harnessed-ts/core';
+/** Storybook's `context.step`, narrowed to what the proxy needs. */
+export type StepRunner = (label: string, play: () => Promise<void>) => Promise<unknown> | unknown;
+/**
+ * The harness, with every public async method run inside `step()` — so the
+ * Interactions panel reads `LoginFormHarness.signInAs("ada@…", "•••")` with the
+ * raw clicks and keystrokes nested under it, rather than a flat list of events.
+ *
+ * Methods run against the real instance, not the proxy: a harness calling its
+ * own methods does not log a step per call, and decorated `accessor` fields
+ * (backed by private slots a proxy cannot reach) keep working. Sync methods stay
+ * sync; a harness they return — `nth()`, a child — comes back wrapped too.
+ *
+ * shortcut: async is detected by `AsyncFunction`, so a plain method that returns
+ * a promise, or one down-levelled to a generator, logs no step. Upgrade if a
+ * harness or a build ever needs that.
+ */
+export declare function withSteps<T extends ScopedHarness>(harness: T, step: StepRunner): T;
+/**
+ * `Harness.method(args…)`, each argument shortened, and any argument whose
+ * parameter name — or object key — looks like a secret replaced with `•••`.
+ *
+ * Names are read from the source, so a minified `storybook build` shows mangled
+ * class names and masks only object keys, not positional arguments.
+ */
+export declare function stepLabel(className: string, method: (...args: never[]) => unknown, args: readonly unknown[], name?: string): string;
+//# sourceMappingURL=steps.d.ts.map

package/dist/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;AAcjG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,aAAa,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,GAAG,CAAC,CAqClF;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,EACrC,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,IAAI,GAAE,MAAoB,GACzB,MAAM,CAMR"}

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@harnessed-ts/storybook",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.0",
+  "description": "Harnesses in Storybook: drive play() functions through a harness, and open stories as fixtures from any runner that can navigate.",
+  "keywords": [
+    "testing",
+    "harness",
+    "storybook",
+    "play-function",
+    "interactions"
+  ],
+  "license": "MIT",
+  "contributors": [
+    {
+      "name": "Joe Gaudet",
+      "url": "https://github.com/joegaudet"
+    },
+    {
+      "name": "Jay Seo",
+      "url": "https://github.com/jayseo5953"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joegaudet/harnessed.git",
+    "directory": "packages/storybook"
+  },
+  "homepage": "https://github.com/joegaudet/harnessed#readme",
+  "bugs": "https://github.com/joegaudet/harnessed/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./page": {
+      "types": "./dist/page.d.ts",
+      "import": "./dist/page.js",
+      "require": "./dist/page.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "@harnessed-ts/core": "^0.6.0",
+    "@harnessed-ts/dom": "^0.6.0",
+    "@harnessed-ts/page": "^0.6.0"
+  },
+  "peerDependencies": {
+    "@testing-library/dom": ">=10",
+    "@testing-library/user-event": ">=14",
+    "storybook": ">=9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/user-event": "^14.6.7",
+    "jsdom": "^30.1.2",
+    "storybook": "10.6.1",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run"
+  }
 }