cursedbelt-core 1.0.0

package/dist/shared/errors.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The canonical server error class + error/validation envelope for the whole
+ * monorepo — cursedbelt apps AND cursedshell plugins.
+ *
+ * Every API failure — thrown deep in a handler, surfaced by middleware, or raised
+ * by a plugin service — is shaped into ONE wire contract, the **rich** envelope
+ * defined once in cwip (`cwip/error`):
+ *
+ *   { "error": { "name", "message", "code?", "status?", "category?", "context?",
+ *       "isOperational", "timestamp" }, "correlationId?": "…" }
+ *
+ * Clients parse exactly this shape, so there is no per-route error drift — and no
+ * drift between a cwip-based server (which already emits it via `cwip/server`'s
+ * `errorHandler`) and a cursedshell one. The extra fields are additive:
+ * a client that only reads `message`/`code`/`context` keeps working unchanged.
+ *
+ * `ApiError` is the ergonomic throwable: `throw new ApiError(404, 'not found')`.
+ * It is a thin subclass of cwip's `AppError` with the status-first constructor
+ * shape every plugin already uses, so a single `getSummary()`/`toErrorEnvelope`
+ * produces the rich body. The `errorEnvelope` Hono `onError` handler
+ * (cursedbelt-server) turns it (and any other thrown value) into the envelope +
+ * the right HTTP status; {@link ApiError.fromEnvelope} rebuilds one on the CLIENT
+ * from a parsed error body.
+ *
+ * This module is **framework-free** (no Hono, no DOM, no server deps — it imports
+ * only cwip's framework-free `cwip/error` and a type-only `zod` for the validation
+ * builder), so it is safe to import from browser bundles and from cursedshell's
+ * plugin-pure layer via the `cursedbelt-core/errors` subpath. Server code reaches the
+ * same symbols through `cursedbelt-server` (which re-exports this module).
+ */
+import { AppError, type AppErrorSummary, type ErrorEnvelope, isAppError, type ToErrorEnvelopeOptions, toErrorEnvelope } from 'cwip/error';
+import type { ZodError } from 'zod';
+export { AppError, type AppErrorSummary, type ErrorEnvelope, isAppError, type ToErrorEnvelopeOptions, toErrorEnvelope };
+export interface ApiErrorOptions {
+    /** Stable machine code carried into the envelope. */
+    code?: string;
+    /** Structured detail carried into the envelope (e.g. `{ issues }`). */
+    context?: Record<string, unknown>;
+    /** Underlying cause, preserved for server-side logging (never serialized). */
+    cause?: unknown;
+}
+/**
+ * A throwable HTTP error carrying its status + canonical-envelope fields. A thin,
+ * status-first subclass of cwip's {@link AppError} — `new ApiError(404, 'nope',
+ * { code, context })` is the ergonomic form every handler/middleware/plugin
+ * service uses; the inherited `getSummary()` yields the rich `AppErrorSummary` so
+ * `toErrorEnvelope` maps it to the response with no extra work. On the client,
+ * {@link ApiError.fromEnvelope} rebuilds it from a parsed error body so callers
+ * can branch on `.status`/`.code`/`.context`.
+ */
+export declare class ApiError extends AppError {
+    /**
+     * Always set — narrows the base's optional `status` (an `ApiError` is defined
+     * by its HTTP status). The value is assigned by `AppError`'s constructor from
+     * the `status` we pass through; `declare` just re-types it without re-emitting
+     * the field (so the base's assignment isn't shadowed under class-field semantics).
+     */
+    readonly status: number;
+    constructor(status: number, message: string, options?: ApiErrorOptions);
+    /**
+     * Rebuild an `ApiError` from a parsed error envelope's `error` object — the
+     * client half of the contract (e.g. `createServiceClient`'s response parser).
+     * Reads only `message`/`code`/`context`, so it works against both the rich
+     * envelope and any legacy minimal body. Missing/absent envelope falls back to a
+     * status-derived message.
+     */
+    static fromEnvelope(status: number, envelope?: Partial<AppErrorSummary>): ApiError;
+}
+/** Type guard for {@link ApiError} (the status-first server throwable). */
+export declare const isApiError: (value: unknown) => value is ApiError;
+/**
+ * One field-level validation error on the wire. `path` is the dotted Zod path to
+ * the offending field (`''` for a top-level/whole-body issue) — it mirrors
+ * `z.ZodIssue.path`, so server code maps 1:1 and clients read a stable name.
+ */
+export interface ValidationIssue {
+    /** Dotted path to the offending field (`''` for a top-level issue). */
+    path: string;
+    /** Human-readable, zod-authored message. */
+    message: string;
+}
+/**
+ * The canonical machine code carried in a validation envelope's `error.code`, so a
+ * client can branch on it without string-matching the (localizable) message.
+ */
+export declare const VALIDATION_ERROR_CODE = "validation";
+/** The HTTP status every validation failure maps to (both emitters respond 400). */
+export declare const VALIDATION_STATUS = 400;
+/** Map a {@link https://zod.dev | zod} error's issues to the wire {@link ValidationIssue}s. */
+export declare function toValidationIssues(error: ZodError): ValidationIssue[];
+/**
+ * Build the canonical validation envelope from a zod error (or pre-mapped issues).
+ * It constructs an {@link ApiError} (status {@link VALIDATION_STATUS}, code
+ * {@link VALIDATION_ERROR_CODE}, `context.issues`) and runs it through the shared
+ * {@link toErrorEnvelope}, so a validation failure is shaped identically to every
+ * other error on the wire — `{ error: { …, code: 'validation', status: 400,
+ * context: { issues } } }`. This is the single builder — both cursedbelt's
+ * `zValidator` middleware and cursedshell's `buildServiceRouter` call it, so a
+ * client parses validation failures identically no matter which layer emitted them.
+ */
+export declare function validationEnvelope(errorOrIssues: ZodError | ValidationIssue[], message?: string): ErrorEnvelope;

package/dist/shared/errors.js

@@ -0,0 +1,99 @@
+/**
+ * The canonical server error class + error/validation envelope for the whole
+ * monorepo — cursedbelt apps AND cursedshell plugins.
+ *
+ * Every API failure — thrown deep in a handler, surfaced by middleware, or raised
+ * by a plugin service — is shaped into ONE wire contract, the **rich** envelope
+ * defined once in cwip (`cwip/error`):
+ *
+ *   { "error": { "name", "message", "code?", "status?", "category?", "context?",
+ *       "isOperational", "timestamp" }, "correlationId?": "…" }
+ *
+ * Clients parse exactly this shape, so there is no per-route error drift — and no
+ * drift between a cwip-based server (which already emits it via `cwip/server`'s
+ * `errorHandler`) and a cursedshell one. The extra fields are additive:
+ * a client that only reads `message`/`code`/`context` keeps working unchanged.
+ *
+ * `ApiError` is the ergonomic throwable: `throw new ApiError(404, 'not found')`.
+ * It is a thin subclass of cwip's `AppError` with the status-first constructor
+ * shape every plugin already uses, so a single `getSummary()`/`toErrorEnvelope`
+ * produces the rich body. The `errorEnvelope` Hono `onError` handler
+ * (cursedbelt-server) turns it (and any other thrown value) into the envelope +
+ * the right HTTP status; {@link ApiError.fromEnvelope} rebuilds one on the CLIENT
+ * from a parsed error body.
+ *
+ * This module is **framework-free** (no Hono, no DOM, no server deps — it imports
+ * only cwip's framework-free `cwip/error` and a type-only `zod` for the validation
+ * builder), so it is safe to import from browser bundles and from cursedshell's
+ * plugin-pure layer via the `cursedbelt-core/errors` subpath. Server code reaches the
+ * same symbols through `cursedbelt-server` (which re-exports this module).
+ */
+import { AppError, isAppError, toErrorEnvelope, } from 'cwip/error';
+// ── Re-export the ONE canonical envelope + formatter (defined in cwip) ────────
+//    So `cursedbelt-core/errors` and `cwip/error` speak the exact same wire contract.
+export { AppError, isAppError, toErrorEnvelope };
+/**
+ * A throwable HTTP error carrying its status + canonical-envelope fields. A thin,
+ * status-first subclass of cwip's {@link AppError} — `new ApiError(404, 'nope',
+ * { code, context })` is the ergonomic form every handler/middleware/plugin
+ * service uses; the inherited `getSummary()` yields the rich `AppErrorSummary` so
+ * `toErrorEnvelope` maps it to the response with no extra work. On the client,
+ * {@link ApiError.fromEnvelope} rebuilds it from a parsed error body so callers
+ * can branch on `.status`/`.code`/`.context`.
+ */
+export class ApiError extends AppError {
+    constructor(status, message, options = {}) {
+        super(message, {
+            status,
+            code: options.code,
+            context: options.context,
+            cause: options.cause,
+        });
+        // `AppError` sets `this.name = new.target.name` → 'ApiError' already.
+    }
+    /**
+     * Rebuild an `ApiError` from a parsed error envelope's `error` object — the
+     * client half of the contract (e.g. `createServiceClient`'s response parser).
+     * Reads only `message`/`code`/`context`, so it works against both the rich
+     * envelope and any legacy minimal body. Missing/absent envelope falls back to a
+     * status-derived message.
+     */
+    static fromEnvelope(status, envelope) {
+        return new ApiError(status, envelope?.message ?? `Request failed with status ${status}`, {
+            code: envelope?.code,
+            context: envelope?.context,
+        });
+    }
+}
+/** Type guard for {@link ApiError} (the status-first server throwable). */
+export const isApiError = (value) => value instanceof ApiError;
+/**
+ * The canonical machine code carried in a validation envelope's `error.code`, so a
+ * client can branch on it without string-matching the (localizable) message.
+ */
+export const VALIDATION_ERROR_CODE = 'validation';
+/** The HTTP status every validation failure maps to (both emitters respond 400). */
+export const VALIDATION_STATUS = 400;
+/** The default client-facing message when validation fails. */
+const DEFAULT_VALIDATION_MESSAGE = 'Validation failed';
+/** Map a {@link https://zod.dev | zod} error's issues to the wire {@link ValidationIssue}s. */
+export function toValidationIssues(error) {
+    return error.issues.map((issue) => ({
+        path: issue.path.map((segment) => String(segment)).join('.'),
+        message: issue.message,
+    }));
+}
+/**
+ * Build the canonical validation envelope from a zod error (or pre-mapped issues).
+ * It constructs an {@link ApiError} (status {@link VALIDATION_STATUS}, code
+ * {@link VALIDATION_ERROR_CODE}, `context.issues`) and runs it through the shared
+ * {@link toErrorEnvelope}, so a validation failure is shaped identically to every
+ * other error on the wire — `{ error: { …, code: 'validation', status: 400,
+ * context: { issues } } }`. This is the single builder — both cursedbelt's
+ * `zValidator` middleware and cursedshell's `buildServiceRouter` call it, so a
+ * client parses validation failures identically no matter which layer emitted them.
+ */
+export function validationEnvelope(errorOrIssues, message = DEFAULT_VALIDATION_MESSAGE) {
+    const issues = Array.isArray(errorOrIssues) ? errorOrIssues : toValidationIssues(errorOrIssues);
+    return toErrorEnvelope(new ApiError(VALIDATION_STATUS, message, { code: VALIDATION_ERROR_CODE, context: { issues } }));
+}

package/dist/testing/bytes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `Uint8Array` → a body the DOM types accept, in ONE place.
+ *
+ * ## The problem this exists to stop being solved five different ways
+ *
+ * TypeScript 5.7 made `Uint8Array` generic in its buffer: `Uint8Array<ArrayBufferLike>`.
+ * `BodyInit` accepts `ArrayBufferView<ArrayBuffer>` — an ArrayBuffer view, NOT a
+ * possibly-shared one — so `new Response(bytes)` and `fetch(url, { body: bytes })`
+ * stopped compiling for every plain `new Uint8Array([…])` in the repo. Nothing
+ * about the runtime changed; the types got more precise about `SharedArrayBuffer`.
+ *
+ * Two fixes suggest themselves and one of them is a bug:
+ *
+ *   * `bytes.buffer as ArrayBuffer` — **wrong in general.** `.buffer` is the
+ *     WHOLE underlying buffer, so for any view that does not span it (`subarray`,
+ *     a slice of a decoder's output, a chunk read off a stream) this silently
+ *     sends more bytes than the caller holds. It happens to be right for a
+ *     literal `new Uint8Array([1,2,3,4])` and that is exactly what makes it a
+ *     trap: it works everywhere it is first tried.
+ *   * `bytes as Uint8Array<ArrayBuffer>` — correct, and what this does. It
+ *     asserts the one thing the caller actually knows (this buffer is not
+ *     shared), changes no lengths, and keeps the view's own offset.
+ *
+ * Test-only by intent: production code that needs to send bytes should hold a
+ * correctly-typed buffer rather than assert one.
+ */
+/** A `Uint8Array` as a `BodyInit`, preserving byte offset and length. */
+export declare const asBody: (bytes: Uint8Array) => Uint8Array<ArrayBuffer>;
+/** `new Response(bytes)` with the assertion applied — the common case. */
+export declare const bytesResponse: (bytes: Uint8Array, init?: ResponseInit) => Response;
+/** A readable stream of `bytes` — what the media catalogue's ingest paths take. */
+export declare const bytesStream: (bytes: Uint8Array | string) => ReadableStream<Uint8Array>;

package/dist/testing/bytes.js

@@ -0,0 +1,33 @@
+/**
+ * `Uint8Array` → a body the DOM types accept, in ONE place.
+ *
+ * ## The problem this exists to stop being solved five different ways
+ *
+ * TypeScript 5.7 made `Uint8Array` generic in its buffer: `Uint8Array<ArrayBufferLike>`.
+ * `BodyInit` accepts `ArrayBufferView<ArrayBuffer>` — an ArrayBuffer view, NOT a
+ * possibly-shared one — so `new Response(bytes)` and `fetch(url, { body: bytes })`
+ * stopped compiling for every plain `new Uint8Array([…])` in the repo. Nothing
+ * about the runtime changed; the types got more precise about `SharedArrayBuffer`.
+ *
+ * Two fixes suggest themselves and one of them is a bug:
+ *
+ *   * `bytes.buffer as ArrayBuffer` — **wrong in general.** `.buffer` is the
+ *     WHOLE underlying buffer, so for any view that does not span it (`subarray`,
+ *     a slice of a decoder's output, a chunk read off a stream) this silently
+ *     sends more bytes than the caller holds. It happens to be right for a
+ *     literal `new Uint8Array([1,2,3,4])` and that is exactly what makes it a
+ *     trap: it works everywhere it is first tried.
+ *   * `bytes as Uint8Array<ArrayBuffer>` — correct, and what this does. It
+ *     asserts the one thing the caller actually knows (this buffer is not
+ *     shared), changes no lengths, and keeps the view's own offset.
+ *
+ * Test-only by intent: production code that needs to send bytes should hold a
+ * correctly-typed buffer rather than assert one.
+ */
+/** A `Uint8Array` as a `BodyInit`, preserving byte offset and length. */
+export const asBody = (bytes) => bytes;
+/** `new Response(bytes)` with the assertion applied — the common case. */
+export const bytesResponse = (bytes, init) => new Response(asBody(bytes), init);
+/** A readable stream of `bytes` — what the media catalogue's ingest paths take. */
+export const bytesStream = (bytes) => new Response(typeof bytes === 'string' ? asBody(new TextEncoder().encode(bytes)) : asBody(bytes))
+    .body;

package/dist/testing/domInspect.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Make a happy-dom node CHEAP to serialize, for every `bun test` process in this
+ * repo. Imported by `packages/cursedbelt/happydom.ts` and
+ * `packages/cursedshell/happydom.ts` — the two test preloads — so it is the ONE
+ * place this behavior is defined.
+ *
+ * ## The bug this exists to not have
+ *
+ * `expect(received)` builds its failure message EAGERLY, before anything decides
+ * whether that message will ever be read. When `received` is a happy-dom node,
+ * Bun's inspector walks the node's own object graph — and a happy-dom node holds
+ * `[Symbol(parentNode)]`, so the walk goes UPWARD through the parent chain into
+ * `HTMLBodyElement` → `HTMLHtmlElement` → `HTMLDocument` → the window, and back
+ * down through every sibling subtree it meets on the way.
+ *
+ * Measured on this repo's own studio spec (2026-07-26):
+ *
+ * | received value                        | cost of ONE failing `expect` |
+ * |---------------------------------------|------------------------------|
+ * | `true`                                | 0.1 ms                       |
+ * | a plain object                        | 0.0 ms                       |
+ * | a detached empty `<div>`              | 9.8 ms                       |
+ * | an ATTACHED empty `<div>`             | 29.8 ms                      |
+ * | an attached `<div>` with 50 children  | **1,576 ms**                 |
+ *
+ * That cost is paid on assertions that FAIL, which sounds rare until you notice
+ * that `waitFor(() => expect(el).toBeNull())` fails on purpose on every poll
+ * until the condition comes true. The studio spec's `settled()` helper spent
+ * ~790 ms per mount building error strings that `waitFor` then threw away — 12
+ * mounts, ~9.5 s of a 10.5 s file, and on the CI runner the same two assertions
+ * blew through Bun's 5,000 ms per-test timeout and turned `main` red.
+ *
+ * ## The fix
+ *
+ * Install `nodejs.util.inspect.custom` on happy-dom's `Node.prototype` (the
+ * common ancestor of every element, text node, fragment and document), returning
+ * TRUNCATED `outerHTML`. Bun's inspector honors that hook and stops walking.
+ * Same measurement, after: **1,576 ms → 0.1 ms.**
+ *
+ * The message gets BETTER as well as faster. What it replaces is not an HTML
+ * dump; it is a `[Symbol(listeners)] / [Symbol(parentNode)]` object graph that
+ * scrolls for thousands of lines and never shows the markup. `outerHTML` is what
+ * someone reading a failure actually wants.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It does not touch `prettyDOM`, `screen.debug()` or any Testing Library output
+ * — those have their own serializer and are called only when someone asks for
+ * them, so they were never the cost. Only the implicit `expect`/`console.log`
+ * path changes.
+ */
+/**
+ * Install the cheap inspector. Idempotent, and a no-op when happy-dom has not
+ * registered its globals (a pure-logic preload has no `Node`).
+ *
+ * Call AFTER `GlobalRegistrator.register()` — before it, `globalThis.Node` is
+ * whatever Bun ships and patching it would miss the class the specs actually get.
+ */
+export declare function installCheapDomInspect(): void;

package/dist/testing/domInspect.js

@@ -0,0 +1,115 @@
+/**
+ * Make a happy-dom node CHEAP to serialize, for every `bun test` process in this
+ * repo. Imported by `packages/cursedbelt/happydom.ts` and
+ * `packages/cursedshell/happydom.ts` — the two test preloads — so it is the ONE
+ * place this behavior is defined.
+ *
+ * ## The bug this exists to not have
+ *
+ * `expect(received)` builds its failure message EAGERLY, before anything decides
+ * whether that message will ever be read. When `received` is a happy-dom node,
+ * Bun's inspector walks the node's own object graph — and a happy-dom node holds
+ * `[Symbol(parentNode)]`, so the walk goes UPWARD through the parent chain into
+ * `HTMLBodyElement` → `HTMLHtmlElement` → `HTMLDocument` → the window, and back
+ * down through every sibling subtree it meets on the way.
+ *
+ * Measured on this repo's own studio spec (2026-07-26):
+ *
+ * | received value                        | cost of ONE failing `expect` |
+ * |---------------------------------------|------------------------------|
+ * | `true`                                | 0.1 ms                       |
+ * | a plain object                        | 0.0 ms                       |
+ * | a detached empty `<div>`              | 9.8 ms                       |
+ * | an ATTACHED empty `<div>`             | 29.8 ms                      |
+ * | an attached `<div>` with 50 children  | **1,576 ms**                 |
+ *
+ * That cost is paid on assertions that FAIL, which sounds rare until you notice
+ * that `waitFor(() => expect(el).toBeNull())` fails on purpose on every poll
+ * until the condition comes true. The studio spec's `settled()` helper spent
+ * ~790 ms per mount building error strings that `waitFor` then threw away — 12
+ * mounts, ~9.5 s of a 10.5 s file, and on the CI runner the same two assertions
+ * blew through Bun's 5,000 ms per-test timeout and turned `main` red.
+ *
+ * ## The fix
+ *
+ * Install `nodejs.util.inspect.custom` on happy-dom's `Node.prototype` (the
+ * common ancestor of every element, text node, fragment and document), returning
+ * TRUNCATED `outerHTML`. Bun's inspector honors that hook and stops walking.
+ * Same measurement, after: **1,576 ms → 0.1 ms.**
+ *
+ * The message gets BETTER as well as faster. What it replaces is not an HTML
+ * dump; it is a `[Symbol(listeners)] / [Symbol(parentNode)]` object graph that
+ * scrolls for thousands of lines and never shows the markup. `outerHTML` is what
+ * someone reading a failure actually wants.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It does not touch `prettyDOM`, `screen.debug()` or any Testing Library output
+ * — those have their own serializer and are called only when someone asks for
+ * them, so they were never the cost. Only the implicit `expect`/`console.log`
+ * path changes.
+ */
+/** Longest markup we will put in a failure message before eliding the middle. */
+const MAX_MARKUP = 800;
+/** Node.nodeType constants, spelled out so this file needs no DOM lib types. */
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+const COMMENT_NODE = 8;
+const DOCUMENT_NODE = 9;
+const DOCUMENT_FRAGMENT_NODE = 11;
+const INSPECT = Symbol.for('nodejs.util.inspect.custom');
+/** Keep the head and the tail: the opening tag says what it is, the closing tag
+ *  says where it ended, and the middle of a 40 KB body is never the useful part. */
+function elide(markup) {
+    if (markup.length <= MAX_MARKUP)
+        return markup;
+    const head = markup.slice(0, MAX_MARKUP - 120);
+    const tail = markup.slice(-100);
+    return `${head}\n  … ${markup.length - MAX_MARKUP + 20} more chars …\n${tail}`;
+}
+function describe(node) {
+    switch (node.nodeType) {
+        case ELEMENT_NODE:
+            return elide(node.outerHTML ?? `<${(node.nodeName ?? 'element').toLowerCase()} />`);
+        case TEXT_NODE:
+            return `#text ${JSON.stringify(node.data ?? '')}`;
+        case COMMENT_NODE:
+            return `<!--${node.data ?? ''}-->`;
+        case DOCUMENT_NODE:
+            return '#document';
+        case DOCUMENT_FRAGMENT_NODE:
+            return elide(`#document-fragment ${node.innerHTML ?? `(${node.childNodes?.length ?? 0} children)`}`);
+        default:
+            return `${node.nodeName ?? 'Node'}(nodeType ${node.nodeType})`;
+    }
+}
+/**
+ * Install the cheap inspector. Idempotent, and a no-op when happy-dom has not
+ * registered its globals (a pure-logic preload has no `Node`).
+ *
+ * Call AFTER `GlobalRegistrator.register()` — before it, `globalThis.Node` is
+ * whatever Bun ships and patching it would miss the class the specs actually get.
+ */
+export function installCheapDomInspect() {
+    const NodeCtor = globalThis.Node;
+    const proto = NodeCtor?.prototype;
+    if (!proto)
+        return;
+    if (Object.hasOwn(proto, INSPECT))
+        return; // already installed
+    Object.defineProperty(proto, INSPECT, {
+        value() {
+            // An inspector that throws turns a readable assertion failure into an
+            // unreadable one, so every branch here is best-effort.
+            try {
+                return describe(this);
+            }
+            catch {
+                return '[unserializable DOM node]';
+            }
+        },
+        configurable: true,
+        enumerable: false,
+        writable: true,
+    });
+}

package/dist/testing/fakeFetch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A `fetch` stand-in that actually satisfies `typeof fetch`.
+ *
+ * `typeof fetch` is not just a call signature: the DOM lib declares `preconnect`
+ * on it, so a bare `async (input) => new Response(…)` is NOT assignable and
+ * `as typeof fetch` is refused outright ("neither type sufficiently overlaps").
+ * The reflexive workaround is `as unknown as typeof fetch`, and that is the
+ * pattern worth stopping: a double assertion silences THIS mismatch and every
+ * future one, including a genuine argument-shape error in the fake.
+ *
+ * This attaches the missing member instead. The result is a real value of the
+ * type, so the fake's own `(input, init)` signature stays checked — which is the
+ * whole reason to type a fake at all.
+ */
+/** The part of `fetch` a test actually implements. */
+export type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Wrap a fake so it is a complete `typeof fetch`.
+ *
+ * `preconnect` is a no-op: it is a resource HINT with no observable result, so a
+ * test that triggered one and got nothing has lost nothing.
+ */
+export declare const fakeFetch: (impl: FetchImpl) => typeof fetch;

package/dist/testing/fakeFetch.js

@@ -0,0 +1,21 @@
+/**
+ * A `fetch` stand-in that actually satisfies `typeof fetch`.
+ *
+ * `typeof fetch` is not just a call signature: the DOM lib declares `preconnect`
+ * on it, so a bare `async (input) => new Response(…)` is NOT assignable and
+ * `as typeof fetch` is refused outright ("neither type sufficiently overlaps").
+ * The reflexive workaround is `as unknown as typeof fetch`, and that is the
+ * pattern worth stopping: a double assertion silences THIS mismatch and every
+ * future one, including a genuine argument-shape error in the fake.
+ *
+ * This attaches the missing member instead. The result is a real value of the
+ * type, so the fake's own `(input, init)` signature stays checked — which is the
+ * whole reason to type a fake at all.
+ */
+/**
+ * Wrap a fake so it is a complete `typeof fetch`.
+ *
+ * `preconnect` is a no-op: it is a resource HINT with no observable result, so a
+ * test that triggered one and got nothing has lost nothing.
+ */
+export const fakeFetch = (impl) => Object.assign(impl, { preconnect: () => undefined });

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { installCheapDomInspect } from "./domInspect";
+export { asBody, bytesResponse, bytesStream } from "./bytes";
+export { type FetchImpl, fakeFetch } from "./fakeFetch";

package/dist/testing/index.js

@@ -0,0 +1,11 @@
+// cursedbelt-core/testing — test-only helpers shared across every `bun test` process
+// in the fleet. Its own subpath so nothing test-related is reachable from the
+// runtime entrypoints.
+//
+// Exposed on 2026-08-02 so consumers (e.g. cursed-satellites' happydom preload)
+// can `import { installCheapDomInspect } from "cursedbelt-core/testing"` instead of
+// keeping a ~60-line hand-port of domInspect.ts — the file already lived here,
+// it just had no export.
+export { installCheapDomInspect } from "./domInspect";
+export { asBody, bytesResponse, bytesStream } from "./bytes";
+export { fakeFetch } from "./fakeFetch";