@orkestrel/test 0.0.13 → 0.0.14

package/README.md

@@ -1,16 +1,13 @@
 # @orkestrel/test
 
-The test helpers the `@orkestrel` fleet kept rewriting, published once. A call recorder that is a
-real callback rather than a spy. A real host delay. A throw-to-value converter and a presence
-narrower, so `!` and `as` stay banned in tests. An async-iterable collector, a stream collector, and
-a JSON copier. A frozen hostile-value corpus for proving guards are total. A cleanup list that gives
-every owned resource back, newest first. A scratch directory the test owns and destroys, a loopback
-port for a server the test built, and a symlink-refusing source-file walker. And the browser journey
-layer, which drives a real interface by role and accessible name through the installed Vitest
-provider. A helper ships here only when enough packages had already written their own; the guide's
-[Limits](guides/test.md#limits) section states that rule, what it excluded, and the one door the
-journey layer came through instead. Add it as a devDependency; nothing here runs in production code.
-Part of the `@orkestrel` line.
+> The test helpers the `@orkestrel` fleet kept rewriting, published once: families of what a test
+> records, what it waits for, and what it owns, with a pair outside all of them and a browser
+> journey layer beside them.
+
+Add it as a devDependency and import the core from `@orkestrel/test`. A helper ships here only when
+enough packages had already written their own; the guide's [Limits](guides/test.md#limits) section
+states that rule, what it excluded, and the one door the journey layer came through instead. Nothing
+here runs in production code. Part of the `@orkestrel` line.
 
 It has **zero runtime dependencies**, and no exported signature names an `@orkestrel/*` type. Both
 rules exist for one reason: a test helper hands its types straight into the consumer's assertions,

package/dist/src/browser/index.d.ts

@@ -1,3 +1,28 @@
+/**
+ * Loads only inside Vitest Browser Mode, where it drives a real browser through the installed
+ * provider.
+ *
+ * @remarks
+ * This entry imports `vitest/browser` at module scope, so importing it from a Node host throws at
+ * module load. That throw is the contract: it arrives at the import that caused it rather than
+ * inside the first helper call, and no Node host half-loads a surface whose every verb assumes the
+ * Browser Mode runner.
+ *
+ * A module that must load under Node as well reaches this entry through a dynamic import behind a
+ * DOM guard. A setup file that a Node project and a browser project both register is the case that
+ * needs it.
+ *
+ * @example
+ * ```ts
+ * let render: ((markup: string) => HTMLDivElement) | undefined
+ * if (typeof document !== 'undefined') {
+ * 	;({ render } = await import('@orkestrel/test/browser'))
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 /**
  * Names the interactive ARIA roles a bare accessible name is searched across.
  *
@@ -45,7 +70,7 @@ export declare function blendColor(front: Color, back: Color): Color;
 export declare function build<K extends keyof HTMLElementTagNameMap>(tag: K, options?: ElementOptions): HTMLElementTagNameMap[K];
 
 /**
- * Names the color a browser paints an unstyled document with.
+ * Names the color a browser paints an unstyled document with: opaque white.
  *
  * @remarks
  * This is the floor a backdrop walk ends on wherever the caller wants the browser's own canvas
@@ -144,7 +169,7 @@ export declare const CAPTURE_STAGINGS = 4;
  */
 export declare function captureFrame(options: FrameOptions): Promise<string>;
 
-/** Represents one theme-and-viewport pair a capture run renders. */
+/** Represents one theme-and-viewport pair a capture run renders, and the document change it needs first. */
 export declare interface CaptureVariant {
     /** Holds the variant's name, which is the second half of every filename the run writes. */
     readonly name: string;
@@ -496,7 +521,7 @@ export declare function describeFocus(element: Element): string;
 export declare function describeTree(element: Element): string;
 
 /**
- * Configures one built element.
+ * Configures one built element: its class list, its text, and its attributes.
  *
  * @remarks
  * `classes` is written the way a `class` attribute is written — one space-separated string — so a
@@ -668,7 +693,7 @@ export declare function findRule(selector: string): CSSStyleRule | undefined;
  */
 export declare const FOCUSABLE_SELECTOR = "a[href], area[href], button, input, select, summary, textarea, [tabindex]";
 
-/** Configures one captured frame. */
+/** Configures one captured frame: where it is written, the viewport it is shot at, and what it shoots. */
 export declare interface FrameOptions {
     /** Holds the frame's path, relative to the calling test file. */
     readonly path: string;
@@ -681,7 +706,8 @@ export declare interface FrameOptions {
 }
 
 /**
- * Represents one written frame, read back from the file a capture produced.
+ * Represents one written frame read back from the file a capture produced: its size in device
+ * pixels, and the single color its bottom row paints.
  *
  * @remarks
  * The floor is the frame's bottom row, because that row is where coverage shows: a frame shot at a
@@ -833,6 +859,8 @@ export declare interface JournalInterface {
      * @param action - What the run did, as one verb.
      * @param trigger - The exact thing it did it to.
      * @param result - What was observed on the surface after the step landed.
+     * @remarks The appended step is frozen. A step taken before `start` or after `stop` is not
+     * recorded at all.
      */
     record(action: string, trigger: string, result: string): void;
 }
@@ -1043,7 +1071,10 @@ export declare interface PortfolioInterface {
     place(state: string, element?: Element): Promise<string | undefined>;
 }
 
-/** Configures a capture portfolio. */
+/**
+ * Configures a capture portfolio: the state registry, the variant matrix, this run's variant, where
+ * it writes, and whether it writes at all.
+ */
 export declare interface PortfolioOptions {
     /**
      * Lists every state name the journeys place, declared once. `place` refuses a name absent from
@@ -1799,6 +1830,10 @@ export declare function traverseAccessible(name: string): Promise<HTMLElement>;
  * @param text - The text to type.
  * @returns A promise resolving after every keystroke completes.
  *
+ * @remarks
+ * The text is escaped against the provider's own key syntax, so a literal `{` or `[` is typed
+ * rather than read as the start of a key sequence.
+ *
  * @example
  * ```ts
  * await typeAccessible('Runs', '3')

package/dist/src/browser/index.js

@@ -27,7 +27,7 @@ var ACCESSIBLE_ROLES = Object.freeze([
 	"treeitem"
 ]);
 /**
-* Names the color a browser paints an unstyled document with.
+* Names the color a browser paints an unstyled document with: opaque white.
 *
 * @remarks
 * This is the floor a backdrop walk ends on wherever the caller wants the browser's own canvas
@@ -435,6 +435,10 @@ async function clickDisclosure(name) {
 * @param text - The text to type.
 * @returns A promise resolving after every keystroke completes.
 *
+* @remarks
+* The text is escaped against the provider's own key syntax, so a literal `{` or `[` is typed
+* rather than read as the start of a key sequence.
+*
 * @example
 * ```ts
 * await typeAccessible('Runs', '3')