@agentrhq/webcmd 0.3.0 → 0.3.1

package/dist/src/release-notes.test.js

@@ -20,8 +20,11 @@ describe('release notes helpers', () => {
     it('detects major releases from semver tag ranges', () => {
         expect(isMajorRelease({ tag: 'webcmd-v2.0.0', previousTag: 'webcmd-v1.9.9' })).toBe(true);
         expect(isMajorRelease({ tag: 'v3.1.0', previousTag: 'v2.9.9' })).toBe(true);
+        expect(isMajorRelease({ tag: 'webcmd-v0.3.0', previousTag: 'webcmd-v0.2.5' })).toBe(true);
+        expect(isMajorRelease({ tag: 'webcmd-v0.1.0', previousTag: 'webcmd-v0.0.9' })).toBe(true);
         expect(isMajorRelease({ tag: 'webcmd-v2.1.0', previousTag: 'webcmd-v2.0.0' })).toBe(false);
-        expect(isMajorRelease({ tag: 'webcmd-v0.3.0', previousTag: 'webcmd-v0.2.5' })).toBe(false);
+        expect(isMajorRelease({ tag: 'webcmd-v0.3.1', previousTag: 'webcmd-v0.3.0' })).toBe(false);
+        expect(isMajorRelease({ tag: 'webcmd-v0.0.1', previousTag: 'webcmd-v0.0.0' })).toBe(false);
     });
     it('deduplicates PR author contributors and excludes service accounts', () => {
         const prs = [
@@ -83,11 +86,19 @@ describe('release notes helpers', () => {
                 },
                 {
                     number: 43,
+                    title: 'feat: improve release presentation',
+                    author: { login: 'bob' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'src/release-notes.ts' }],
+                    url: 'https://github.com/agentrhq/webcmd/pull/43',
+                },
+                {
+                    number: 44,
                     title: 'chore: release automation',
                     author: { login: 'github-actions[bot]' },
                     labels: [],
                     files: [{ path: '.github/workflows/release.yml' }],
-                    url: 'https://github.com/agentrhq/webcmd/pull/43',
+                    url: 'https://github.com/agentrhq/webcmd/pull/44',
                 },
             ],
         };
@@ -100,15 +111,16 @@ describe('release notes helpers', () => {
         const normalized = normalizeReleaseNotes(raw, { context });
         expect(normalized).toContain('# webcmd v2.0.0: The Command Surface Opens');
         expect(normalized).toContain('## Contributors');
-        expect(normalized).toContain('<img src="https://github.com/alice.png?size=64" width="64" height="64" alt="@alice" />');
+        expect(normalized).toContain('<img src="https://github.com/alice.png?size=40" width="40" height="40" alt="@alice" /></a> <a href="https://github.com/bob"');
         expect(normalized).toContain('[@alice](https://github.com/alice)');
+        expect(normalized).toContain('[@alice](https://github.com/alice) | [@bob](https://github.com/bob)');
         expect(normalized).not.toContain('github-actions');
     });
     it('uses a deterministic major release title fallback when the model omits one', () => {
         const context = {
-            tag: 'webcmd-v2.0.0',
-            previousTag: 'webcmd-v1.9.9',
-            currentRef: 'webcmd-v2.0.0',
+            tag: 'webcmd-v0.3.0',
+            previousTag: 'webcmd-v0.2.5',
+            currentRef: 'webcmd-v0.3.0',
             pullRequests: [
                 {
                     number: 42,
@@ -121,7 +133,7 @@ describe('release notes helpers', () => {
             ],
         };
         const normalized = normalizeReleaseNotes('## Highlights\n- Added a GitHub adapter.', { context });
-        expect(normalized).toContain('# webcmd v2.0.0: The Command Surface Expands');
+        expect(normalized).toContain('# webcmd v0.3.0: The Command Surface Expands');
     });
     it('does not add major release title treatment to minor releases', () => {
         const context = {
@@ -172,7 +184,7 @@ describe('release notes helpers', () => {
             '- Improved district checkout.',
             '',
             '## Contributors',
-            '<a href="https://github.com/alice" title="@alice"><img src="https://github.com/alice.png?size=64" width="64" height="64" alt="@alice" /></a>',
+            '<a href="https://github.com/alice" title="@alice"><img src="https://github.com/alice.png?size=40" width="40" height="40" alt="@alice" /></a>',
             '',
             '[@alice](https://github.com/alice)',
         ].join('\n');
@@ -189,8 +201,8 @@ describe('release notes helpers', () => {
     });
     it('builds a prompt grounded in the exact release range and PR list', () => {
         const context = {
-            tag: 'v0.2.0',
-            previousTag: 'v0.1.1',
+            tag: 'v0.2.1',
+            previousTag: 'v0.2.0',
             currentRef: 'abc123',
             pullRequests: [
                 {
@@ -206,7 +218,7 @@ describe('release notes helpers', () => {
             ],
         };
         const prompt = buildReleaseNotesPrompt(context);
-        expect(prompt).toContain('v0.1.1...abc123');
+        expect(prompt).toContain('v0.2.0...abc123');
         expect(prompt).toContain('PR #42: feat: add docs scaffold');
         expect(prompt).toContain('docs/docs.json');
         expect(prompt).toContain('## Highlights');
@@ -222,9 +234,9 @@ describe('release notes helpers', () => {
     });
     it('asks for a tasteful H1 title only when building major release notes', () => {
         const context = {
-            tag: 'webcmd-v2.0.0',
-            previousTag: 'webcmd-v1.9.9',
-            currentRef: 'webcmd-v2.0.0',
+            tag: 'webcmd-v0.3.0',
+            previousTag: 'webcmd-v0.2.5',
+            currentRef: 'webcmd-v0.3.0',
             pullRequests: [
                 {
                     number: 42,
@@ -240,7 +252,7 @@ describe('release notes helpers', () => {
         };
         const prompt = buildReleaseNotesPrompt(context);
         expect(prompt).toContain('This is a major release');
-        expect(prompt).toContain('# webcmd v2.0.0: <Elegant Release Title>');
+        expect(prompt).toContain('# webcmd v0.3.0: <Elegant Release Title>');
         expect(prompt).toContain('grand enough to feel memorable, but polished rather than loud');
     });
 });

package/dist/src/root-command-surface.d.ts

@@ -0,0 +1,31 @@
+import { Command } from 'commander';
+export declare const ROOT_PROFILE_FLAGS = "--profile <name>";
+export declare const ROOT_PROFILE_DESCRIPTION = "Chrome profile/context alias for browser runtime commands";
+export declare const COMPLETION_SENTINEL = "--get-completions";
+/**
+ * Configure the structural root options shared by the local and hosted CLI.
+ * Keeping this in one place makes Commander the source of truth for attached
+ * values, short-option clusters, missing values, and help/version precedence.
+ */
+export declare function configureRootCommandSurface(program: Command): Command;
+export type HostedRootCommandSurface = {
+    kind: 'help';
+    exitCode: number;
+} | {
+    kind: 'version';
+    output: string;
+} | {
+    kind: 'completion';
+    argv: string[];
+} | {
+    kind: 'dispatch';
+    argv: string[];
+    profile?: string;
+    literal: boolean;
+};
+/**
+ * Parse only the root command surface without registering or discovering local
+ * commands. The completion/version checks reproduce the entry-point fast paths
+ * in main.ts; all remaining root grammar is delegated to Commander itself.
+ */
+export declare function parseHostedRootCommandSurface(argv: readonly string[]): HostedRootCommandSurface;

package/dist/src/root-command-surface.js

@@ -0,0 +1,106 @@
+import { Command, CommanderError } from 'commander';
+import { CommanderStructuralError } from './command-surface.js';
+import { PKG_VERSION } from './version.js';
+export const ROOT_PROFILE_FLAGS = '--profile <name>';
+export const ROOT_PROFILE_DESCRIPTION = 'Chrome profile/context alias for browser runtime commands';
+export const COMPLETION_SENTINEL = '--get-completions';
+/**
+ * Configure the structural root options shared by the local and hosted CLI.
+ * Keeping this in one place makes Commander the source of truth for attached
+ * values, short-option clusters, missing values, and help/version precedence.
+ */
+export function configureRootCommandSurface(program) {
+    return program
+        .version(PKG_VERSION)
+        .option(ROOT_PROFILE_FLAGS, ROOT_PROFILE_DESCRIPTION)
+        .enablePositionalOptions();
+}
+/**
+ * Parse only the root command surface without registering or discovering local
+ * commands. The completion/version checks reproduce the entry-point fast paths
+ * in main.ts; all remaining root grammar is delegated to Commander itself.
+ */
+export function parseHostedRootCommandSurface(argv) {
+    const input = [...argv];
+    // main.ts checks an exact first-token version before its completion scan.
+    if (input[0] === '--version' || input[0] === '-V') {
+        return { kind: 'version', output: `${PKG_VERSION}\n` };
+    }
+    // The local completion path scans the complete raw argv before discovery or
+    // Commander parsing, including after `--` and malformed root options.
+    if (input.includes(COMPLETION_SENTINEL)) {
+        return { kind: 'completion', argv: input };
+    }
+    let stdout = '';
+    let stderr = '';
+    const boundary = findRootCommandBoundary(input);
+    const root = configureRootCommandSurface(new Command('webcmd'))
+        .exitOverride()
+        .configureOutput({
+        writeOut: value => { stdout += value; },
+        writeErr: value => { stderr += value; },
+    });
+    if (boundary.commandIndex !== undefined) {
+        // Register only the token Commander needs in order to stop root option
+        // parsing. This is structural scaffolding, not adapter discovery.
+        root.command(input[boundary.commandIndex])
+            .helpOption(false)
+            .allowUnknownOption(true)
+            .allowExcessArguments(true)
+            .argument('[commandArgs...]')
+            .exitOverride()
+            .configureOutput({ writeOut: () => undefined, writeErr: () => undefined });
+    }
+    const structuralArgv = boundary.commandIndex !== undefined
+        ? input
+        : boundary.separatorIndex !== undefined
+            ? input.slice(0, boundary.separatorIndex + 1)
+            : input;
+    try {
+        root.parse(structuralArgv, { from: 'user' });
+    }
+    catch (error) {
+        if (!(error instanceof CommanderError))
+            throw error;
+        if (error.code === 'commander.helpDisplayed')
+            return { kind: 'help', exitCode: error.exitCode };
+        if (error.code === 'commander.version') {
+            return { kind: 'version', output: stdout || `${PKG_VERSION}\n` };
+        }
+        throw new CommanderStructuralError(stderr || `${error.message}\n`, error.exitCode);
+    }
+    const profile = root.opts().profile;
+    if (boundary.commandIndex === undefined && boundary.separatorIndex === undefined)
+        return { kind: 'help', exitCode: 1 };
+    const literal = boundary.separatorIndex !== undefined;
+    const parsedArgv = boundary.commandIndex !== undefined
+        ? input.slice(boundary.commandIndex)
+        : input.slice(boundary.separatorIndex + 1);
+    if (parsedArgv.length === 0)
+        return { kind: 'help', exitCode: 1 };
+    return {
+        kind: 'dispatch',
+        argv: parsedArgv,
+        ...(profile !== undefined ? { profile } : {}),
+        literal,
+    };
+}
+/** Locates the undiscovered command token while respecting root value options. */
+function findRootCommandBoundary(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--profile') {
+            // Commander requires and consumes the next token even when it is `--` or
+            // starts with a dash. Structural failures have already been reported.
+            index += 1;
+            continue;
+        }
+        if (token.startsWith('--profile='))
+            continue;
+        if (token === '--')
+            return { separatorIndex: index };
+        if (!token.startsWith('-') || token === '-')
+            return { commandIndex: index };
+    }
+    return {};
+}

package/dist/src/serialization.d.ts

@@ -18,22 +18,7 @@ export type SerializedArg = {
 /** Stable arg schema — every field is always present (no sparse objects). */
 export declare function serializeArg(a: Arg): SerializedArg;
 /** Full command metadata for structured output (json/yaml). */
-export declare function serializeCommand(cmd: CliCommand): {
-    command: string;
-    site: string;
-    name: string;
-    aliases: string[];
-    description: string;
-    access: import("./registry.js").CommandAccess;
-    strategy: string;
-    browser: boolean;
-    args: SerializedArg[];
-    columns: string[];
-    domain: string | null;
-    example: string;
-    defaultFormat: "table" | "plain" | "json" | "yaml" | "yml" | "md" | "markdown" | "csv" | null;
-    siteSession: import("./registry.js").SiteSessionMode | null;
-};
+export declare function serializeCommand(cmd: CliCommand): Record<string, unknown>;
 /** Human-readable arg summary: `<required> [optional]` style. */
 export declare function formatArgSummary(args: Arg[]): string;
 /** Agent-facing canonical invocation. Adapter authors may override with `example`. */

package/dist/src/serialization.js

@@ -4,78 +4,28 @@
  * Used by the `list` command, Commander --help, and build-manifest.
  * Separated from registry.ts to keep the registry focused on types + registration.
  */
-import { fullName, strategyLabel } from './registry.js';
-import { CLI_COMMAND } from './brand.js';
+import { commandListRows, formatArgumentSummary, formatPresentableCommandExample, serializePresentableArg, toPresentableCommand, } from './command-presentation.js';
 /** Stable arg schema — every field is always present (no sparse objects). */
 export function serializeArg(a) {
-    return {
-        name: a.name,
-        type: a.type ?? 'string',
-        required: !!a.required,
-        valueRequired: !!a.valueRequired,
-        positional: !!a.positional,
-        choices: a.choices ?? [],
-        default: a.default ?? null,
-        help: a.help ?? '',
-    };
+    return serializePresentableArg(a);
 }
 /** Full command metadata for structured output (json/yaml). */
 export function serializeCommand(cmd) {
-    return {
-        command: fullName(cmd),
-        site: cmd.site,
-        name: cmd.name,
-        aliases: cmd.aliases ?? [],
-        description: cmd.description,
-        access: cmd.access,
-        strategy: strategyLabel(cmd),
-        browser: !!cmd.browser,
-        args: cmd.args.map(serializeArg),
-        columns: cmd.columns ?? [],
-        domain: cmd.domain ?? null,
-        example: formatCommandExample(cmd),
-        defaultFormat: cmd.defaultFormat ?? null,
-        siteSession: cmd.siteSession ?? null,
-    };
+    return commandListRows([toPresentableCommand(cmd)], true)[0];
 }
 // ── Formatting ──────────────────────────────────────────────────────────────
 /** Human-readable arg summary: `<required> [optional]` style. */
 export function formatArgSummary(args) {
-    return args
-        .map(a => {
-        if (a.positional)
-            return a.required ? `<${a.name}>` : `[${a.name}]`;
-        return a.required ? `--${a.name}` : `[--${a.name}]`;
-    })
-        .join(' ');
+    return formatArgumentSummary(args);
 }
 function summarizeChoices(choices) {
     if (choices.length <= 4)
         return choices.join(', ');
     return `${choices.slice(0, 4).join(', ')}, ... (+${choices.length - 4} more)`;
 }
-function formatValuePlaceholder(name) {
-    return `<${name}>`;
-}
 /** Agent-facing canonical invocation. Adapter authors may override with `example`. */
 export function formatCommandExample(cmd) {
-    if (cmd.example?.trim())
-        return cmd.example.trim();
-    const parts = [CLI_COMMAND, cmd.site, cmd.name];
-    for (const arg of cmd.args) {
-        if (arg.positional && arg.required) {
-            parts.push(formatValuePlaceholder(arg.name));
-        }
-    }
-    for (const arg of cmd.args) {
-        if (arg.positional || !arg.required)
-            continue;
-        parts.push(`--${arg.name}`);
-        if (arg.type !== 'bool' && arg.type !== 'boolean')
-            parts.push(formatValuePlaceholder(arg.name));
-    }
-    parts.push('-f', 'yaml');
-    return parts.join(' ');
+    return formatPresentableCommandExample(toPresentableCommand(cmd));
 }
 /** Generate the --help appendix showing registry metadata not exposed by Commander. */
 export function formatRegistryHelpText(cmd) {

package/dist/src/stream-write.d.ts

@@ -0,0 +1,12 @@
+/** A write failure that must not be mistaken for a command/runtime failure. */
+export declare class StreamWriteError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+/**
+ * Write one complete chunk without taking ownership of the stream.
+ *
+ * Resolution requires both the write callback and, when write() reports
+ * backpressure, the matching drain event. The stream is never ended.
+ */
+export declare function writeToStream(stream: NodeJS.WritableStream, chunk: string | Uint8Array): Promise<void>;

package/dist/src/stream-write.js

@@ -0,0 +1,91 @@
+/** A write failure that must not be mistaken for a command/runtime failure. */
+export class StreamWriteError extends Error {
+    cause;
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.name = 'StreamWriteError';
+        this.cause = cause;
+    }
+}
+/**
+ * Write one complete chunk without taking ownership of the stream.
+ *
+ * Resolution requires both the write callback and, when write() reports
+ * backpressure, the matching drain event. The stream is never ended.
+ */
+export function writeToStream(stream, chunk) {
+    return new Promise((resolve, reject) => {
+        const prematureCloseError = new Error('Writable stream closed before the write completed');
+        const streamState = stream;
+        if (streamState.closed || streamState.destroyed) {
+            reject(new StreamWriteError(prematureCloseError));
+            return;
+        }
+        let writeReturned = false;
+        let callbackComplete = false;
+        let requiresDrain = false;
+        let drainSeen = false;
+        let settled = false;
+        let pendingCallbackError;
+        let pendingCallbackFailure;
+        const cleanup = () => {
+            stream.removeListener('error', onError);
+            stream.removeListener('drain', onDrain);
+            stream.removeListener('close', onClose);
+            if (pendingCallbackFailure) {
+                clearImmediate(pendingCallbackFailure);
+                pendingCallbackFailure = undefined;
+            }
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error instanceof StreamWriteError ? error : new StreamWriteError(error));
+        };
+        const failFromCallback = (error) => {
+            if (settled)
+                return;
+            pendingCallbackError ??= error;
+            // A real Node Writable reports an _write callback failure to the public
+            // write callback and then emits `error`. Keep the error listener until
+            // that paired event has had a chance to arrive, while still bounding
+            // non-standard streams that only invoke the callback.
+            pendingCallbackFailure ??= setImmediate(() => fail(pendingCallbackError));
+        };
+        const finish = () => {
+            if (settled || !writeReturned || !callbackComplete || (requiresDrain && !drainSeen))
+                return;
+            settled = true;
+            cleanup();
+            resolve();
+        };
+        const onError = (error) => fail(error);
+        const onClose = () => fail(pendingCallbackError ?? prematureCloseError);
+        const onDrain = () => {
+            drainSeen = true;
+            finish();
+        };
+        stream.once('error', onError);
+        stream.once('drain', onDrain);
+        stream.once('close', onClose);
+        try {
+            requiresDrain = stream.write(chunk, (error) => {
+                if (error) {
+                    failFromCallback(error);
+                    return;
+                }
+                callbackComplete = true;
+                finish();
+            }) === false;
+            writeReturned = true;
+            if (!requiresDrain)
+                stream.removeListener('drain', onDrain);
+            finish();
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}

package/dist/src/stream-write.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/stream-write.test.js

@@ -0,0 +1,186 @@
+import { EventEmitter } from 'node:events';
+import { Writable } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import { writeToStream } from './stream-write.js';
+class ManualWritable extends Writable {
+    chunks = [];
+    callbacks = [];
+    constructor() {
+        super({ highWaterMark: 1 });
+    }
+    _write(chunk, _encoding, callback) {
+        this.chunks.push(Buffer.from(chunk));
+        this.callbacks.push(callback);
+    }
+    release(error) {
+        const callback = this.callbacks.shift();
+        if (!callback)
+            throw new Error('No manual write callback is pending');
+        callback(error);
+    }
+}
+class SyntheticBackpressureStream extends EventEmitter {
+    callback;
+    end = vi.fn();
+    write(_chunk, callback) {
+        this.callback = callback;
+        return false;
+    }
+}
+class SyntheticBackpressureWritable extends Writable {
+    callback;
+    write(_chunk, encodingOrCallback, callback) {
+        this.callback = typeof encodingOrCallback === 'function' ? encodingOrCallback : callback;
+        return false;
+    }
+    _write(_chunk, _encoding, callback) {
+        callback();
+    }
+}
+async function within(promise, milliseconds = 500) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(`promise did not settle within ${milliseconds}ms`)), milliseconds);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+describe('writeToStream', () => {
+    it('waits for both the write callback and backpressure drain', async () => {
+        const stream = new SyntheticBackpressureStream();
+        let settled = false;
+        const write = writeToStream(stream, 'payload').then(() => {
+            settled = true;
+        });
+        stream.callback?.();
+        await Promise.resolve();
+        expect(settled).toBe(false);
+        stream.emit('drain');
+        await write;
+        expect(settled).toBe(true);
+        expect(stream.end).not.toHaveBeenCalled();
+    });
+    it('preserves ordering across multiple awaited writes', async () => {
+        const stream = new ManualWritable();
+        let settled = false;
+        const writes = (async () => {
+            await writeToStream(stream, 'first');
+            await writeToStream(stream, 'second');
+            settled = true;
+        })();
+        expect(stream.callbacks).toHaveLength(1);
+        stream.release();
+        await new Promise(resolve => setImmediate(resolve));
+        expect(stream.callbacks).toHaveLength(1);
+        expect(Buffer.concat(stream.chunks).toString('utf8')).toBe('firstsecond');
+        expect(settled).toBe(false);
+        stream.release();
+        await writes;
+        expect(settled).toBe(true);
+    });
+    it('writes and drains a value larger than one MiB', async () => {
+        const stream = new ManualWritable();
+        const payload = Buffer.alloc(1024 * 1024 + 17, 0x61);
+        const write = writeToStream(stream, payload);
+        expect(stream.chunks[0]).toHaveLength(payload.length);
+        stream.release();
+        await write;
+        expect(Buffer.concat(stream.chunks).equals(payload)).toBe(true);
+    });
+    it('rejects an error emitted before drain without hanging', async () => {
+        const stream = new SyntheticBackpressureStream();
+        const write = writeToStream(stream, 'payload');
+        stream.emit('error', new Error('stream failed before drain'));
+        await expect(write).rejects.toThrow('stream failed before drain');
+    });
+    it('rejects a real Writable callback error without an uncaught error event', async () => {
+        const stream = new ManualWritable();
+        const write = writeToStream(stream, 'payload');
+        stream.release(new Error('real writable callback failed'));
+        await expect(write).rejects.toThrow('real writable callback failed');
+        await new Promise(resolve => setImmediate(resolve));
+    });
+    it('rejects a callback error delivered after drain without double resolution', async () => {
+        const stream = new SyntheticBackpressureStream();
+        const write = writeToStream(stream, 'payload');
+        stream.emit('drain');
+        stream.callback?.(new Error('stream failed after drain'));
+        await expect(write).rejects.toThrow('stream failed after drain');
+    });
+    it('rejects when a real Writable is destroyed before its write callback', async () => {
+        const stream = new ManualWritable();
+        const write = writeToStream(stream, 'payload');
+        stream.destroy();
+        await expect(within(write)).rejects.toThrow('closed before the write completed');
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+    it('rejects when close occurs after callback but before required drain', async () => {
+        const stream = new SyntheticBackpressureWritable();
+        const write = writeToStream(stream, 'payload');
+        stream.callback?.();
+        stream.destroy();
+        await expect(within(write)).rejects.toThrow('closed before the write completed');
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+    it('rejects an already-destroyed Writable without attempting a write', async () => {
+        const stream = new ManualWritable();
+        stream.destroy();
+        await new Promise(resolve => stream.once('close', resolve));
+        await expect(within(writeToStream(stream, 'payload'))).rejects.toThrow('closed before the write completed');
+        expect(stream.chunks).toHaveLength(0);
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+    it('ignores a late callback after close has already rejected the write', async () => {
+        const stream = new ManualWritable();
+        const write = writeToStream(stream, 'payload');
+        stream.destroy();
+        await expect(within(write)).rejects.toThrow('closed before the write completed');
+        expect(() => {
+            stream.emit('drain');
+            stream.release(new Error('late callback failure'));
+        }).not.toThrow();
+        await new Promise(resolve => setImmediate(resolve));
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+    it('settles once with the original error when error and close race', async () => {
+        const stream = new ManualWritable();
+        const write = writeToStream(stream, 'payload');
+        stream.destroy(new Error('destroy race failed'));
+        await expect(within(write)).rejects.toThrow('destroy race failed');
+        await new Promise(resolve => setImmediate(resolve));
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+    it('does not let close after success change the resolved result', async () => {
+        const stream = new SyntheticBackpressureWritable();
+        const end = vi.spyOn(stream, 'end');
+        const destroy = vi.spyOn(stream, 'destroy');
+        const write = writeToStream(stream, 'payload');
+        stream.emit('drain');
+        stream.callback?.();
+        await expect(within(write)).resolves.toBeUndefined();
+        expect(end).not.toHaveBeenCalled();
+        expect(destroy).not.toHaveBeenCalled();
+        stream.destroy();
+        await new Promise(resolve => setImmediate(resolve));
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+});

package/dist/src/types.d.ts

@@ -87,6 +87,9 @@ export interface IPage {
     }): Promise<{
         matches_n: number;
         match_level: 'exact' | 'stable' | 'reidentified';
+        click_method?: 'cdp' | 'js' | 'ax';
+        hit?: 'target' | 'ancestor' | 'other' | 'none';
+        retargeted?: boolean;
     }>;
     dblClick?(ref: string, opts?: {
         nth?: number;
@@ -178,6 +181,8 @@ export interface IPage {
     }): Promise<any>;
     getFormState(): Promise<any>;
     wait(options: number | WaitOptions): Promise<void>;
+    /** Pure client-side sleep (bare setTimeout, no page evaluation). */
+    sleep(seconds: number): Promise<void>;
     waitForDownload?(pattern?: string, timeoutMs?: number): Promise<BrowserDownloadWaitResult>;
     tabs(): Promise<any>;
     closeTab?(target?: number | string): Promise<void>;