release(v4.0.2): consumer-strict reader-shape fixes

4.0.1's typecheck gate compiled each package internally against
lib: ["ES2022"]. That doesn't catch types that only fail when
*consumer* code (lib: ["DOM"] + exactOptionalPropertyTypes) tries to
assign a native browser type into one of our locally-defined narrower
types. Dispatch hit one such case in @shade/files inline-threshold.ts.

This release adds a tests/consumer-strict/ smoke project to the
pre-publish gate. It compiles a tiny "as if I were a downstream app"
TS file against:

  lib: ["ES2022", "DOM", "DOM.Iterable"]
  types: ["bun-types"]
  exactOptionalPropertyTypes: true
  strict: true
  paths → packages/*/src/index.ts

scripts/typecheck-all.ts now runs the smoke after per-package checks.
Both must pass before publish:dry / publish:all proceeds.

### Fixed
- @shade/files inline-threshold.ts: MinimalReader<T> rewritten as the
  explicit disjoint union { done:false, value:T } | { done:true,
  value?: T | undefined } that's assignable from every native reader
  shape (bun, DOM, node:stream/web). Fixes the
  "ReadableStreamReadResult is not assignable" Dispatch reported.
- @shade/files streams-bridge (client + server): stash setTimeout
  return in a local before .unref?.() via { unref?: () => void } cast.
  Fluent .unref?.() failed under lib: ["DOM"] (setTimeout returns
  number there).
- @shade/sdk background.ts: same setInterval .unref?.() fix.

Wire-compatible. No API shape changed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to Shade are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.2] — 2026-05-03 — Consumer-strict reader-shape fixes
+
+`4.0.1` shipped the `tsc --noEmit` gate that compiles each package
+internally against `lib: ["ES2022"]`. That gate did not catch types
+that only fail when *consumer* code (running with `lib: ["DOM"]` +
+`exactOptionalPropertyTypes`) tries to assign a native browser type
+into one of our locally-defined narrower types.
+
+This release adds a consumer-strict smoke test to the pre-publish
+gate and fixes every collision that smoke uncovered.
+
+### Fixed
+
+#### `@shade/files`
+- `inline-threshold.ts`: rewrote the local `MinimalReader<T>` interface
+  as an explicit disjoint union (`{ done: false; value: T } | { done:
+  true; value?: T | undefined }`) so it accepts every native reader
+  shape — `bun-types` (`value?: undefined`), `lib.dom` (`value?: T`),
+  and `node:stream/web`. The previous flat shape was rejected by
+  consumer projects with `exactOptionalPropertyTypes: true` because
+  the present-branch required `value: T`. **Fixes "Type
+  ReadableStreamReadResult<Uint8Array> is not assignable to
+  { value: Uint8Array | undefined; done: boolean }".**
+- `client/streams-bridge.ts`, `server/streams-bridge.ts`: stash the
+  `setTimeout(...)` return value in a local before calling `.unref?.()`
+  through an explicit `{ unref?: () => void }` cast. The previous
+  fluent `.unref?.()` failed under `lib: ["DOM"]` because DOM types
+  `setTimeout` to `number`, which has no `.unref` even as an optional
+  property.
+
+#### `@shade/sdk`
+- `background.ts`: same `setTimeout` / `setInterval` `.unref?.()` fix.
+
+### Tooling
+
+- New `tests/consumer-strict/` — a tiny "as if I were a downstream app"
+  TypeScript project with its own `tsconfig.json`:
+  `lib: ["ES2022", "DOM", "DOM.Iterable"]`, `types: ["bun-types"]`,
+  `exactOptionalPropertyTypes: true`, `strict: true`,
+  `paths`-mapped to the workspace's `packages/*/src/index.ts`.
+  Three smoke files exercise `@shade/files`, `@shade/sdk`, and
+  `@shade/key-transparency` against the consumer-strict tsconfig.
+- `scripts/typecheck-all.ts` now runs the consumer-strict smoke after
+  the per-package internal type-check. Both must pass before
+  `prepublish:check` (and therefore `publish:dry` / `publish:all`)
+  succeeds.
+
+### Migration
+
+`4.0.1 → 4.0.2` is wire-compatible and source-compatible. No API shape
+changed; only internal typing was tightened.
+
 ## [4.0.1] — 2026-05-03 — Strict-TS publishability fixes
 
 `4.0.0` shipped TypeScript source files as the published `main` /

packages/shade-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/cli",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/cli.ts",
   "bin": {

packages/shade-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/core",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-crypto-web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/crypto-web",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-dashboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/dashboard",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "scripts": {
     "dev": "vite",

packages/shade-files/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/files",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-files/src/client/inline-threshold.ts

@@ -161,15 +161,33 @@ async function peekStream(stream: ReadableStream<Uint8Array>): Promise<InlineDec
   }
 }
 
-interface MinimalReader {
-  read(): Promise<{ value: Uint8Array | undefined; done: boolean }>;
+/**
+ * Structural mirror of WHATWG `ReadableStreamDefaultReader<Uint8Array>`.
+ *
+ * The disjoint union shape with `value?: T | undefined` is the lowest
+ * common denominator across every lib environment we care about:
+ * - `bun-types` emits `{ done: true; value?: undefined }`
+ * - `lib.dom`   emits `{ done: true; value?: T }`
+ * - `node:stream/web` emits the union form
+ *
+ * `value?: T | undefined` is assignable from all three. A flat
+ * `{ value?: T; done: boolean }` is rejected by
+ * `exactOptionalPropertyTypes` because the present branches require
+ * `value: T`. Defining it as an explicit union avoids the trap.
+ */
+type MinimalReadResult<T> =
+  | { done: false; value: T }
+  | { done: true; value?: T | undefined };
+
+interface MinimalReader<T> {
+  read(): Promise<MinimalReadResult<T>>;
   cancel(reason?: unknown): Promise<void>;
   releaseLock(): void;
 }
 
 function reconstructStream(
   prefix: Uint8Array[],
-  reader: MinimalReader,
+  reader: MinimalReader<Uint8Array>,
 ): ReadableStream<Uint8Array> {
   let prefixIdx = 0;
   return new ReadableStream<Uint8Array>({

packages/shade-files/src/client/streams-bridge.ts

@@ -142,13 +142,14 @@ export async function createClientStreamsBridge(
     }
 
     parked.set(readStreamId, arrival);
-    setTimeout(() => {
+    const t = setTimeout(() => {
       const stale = parked.get(readStreamId);
       if (stale === arrival) {
         parked.delete(readStreamId);
         void handle.abort('rpc-timeout').catch(() => undefined);
       }
-    }, parkedReadTtlMs).unref?.();
+    }, parkedReadTtlMs);
+    (t as unknown as { unref?: () => void }).unref?.();
   });
 
   function cleanupWaiter(w: PendingReadWaiter): void {

packages/shade-files/src/server/streams-bridge.ts

@@ -168,13 +168,14 @@ export async function createServerStreamsBridge(
 
     // No waiter yet — park.
     parked.set(writeId, arrived);
-    setTimeout(() => {
+    const parkTimer = setTimeout(() => {
       const stale = parked.get(writeId);
       if (stale === arrived) {
         parked.delete(writeId);
         void handle.abort('rpc-timeout').catch(() => undefined);
       }
-    }, parkedWriteTtlMs).unref?.();
+    }, parkedWriteTtlMs);
+    (parkTimer as unknown as { unref?: () => void }).unref?.();
   });
 
   function cleanupWaiter(w: PendingWaiter): void {

packages/shade-inbox-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/inbox-server",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-inbox/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/inbox",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-key-transparency/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/key-transparency",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-keychain/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/keychain",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-observability/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/observability",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-observer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/observer",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-proto/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/proto",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-recovery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/recovery",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/sdk",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-sdk/src/background.ts

@@ -96,7 +96,7 @@ export class BackgroundTasks {
         this.hooks.onError?.(err as Error, 'prune-files');
       }
     }, this.pruneFilesIntervalMs);
-    this.pruneFilesTimer.unref?.();
+    (this.pruneFilesTimer as unknown as { unref?: () => void }).unref?.();
   }
 
   stop(): void {

packages/shade-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/server",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-storage-encrypted/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/storage-encrypted",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-storage-postgres/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/storage-postgres",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-storage-sqlite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/storage-sqlite",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-streams/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/streams",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-transfer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/transfer",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-transport-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/transport-bridge",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-transport-webrtc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/transport-webrtc",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-transport/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/transport",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-widgets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/widgets",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

scripts/typecheck-all.ts

@@ -61,6 +61,39 @@ for (const pkg of packages) {
 }
 
 console.log();
+
+// Step 2 — consumer-strict smoke. Compiles a tiny "as if I were a
+// downstream app" project against our public API surface under the
+// consumer-likely tsconfig (`lib: ["DOM"]` + `exactOptionalPropertyTypes`).
+// Catches type-bugs that ONLY surface when our internal narrower types
+// meet a consumer's standard-library types — the class of bug `tsc`
+// inside our own packages does not see (because our packages compile
+// against `lib: ["ES2022"]` only).
+if (filter.size === 0) {
+  console.log('Consumer-strict smoke (lib: DOM, exactOptional, paths→workspace) ...');
+  const consumerDir = join(ROOT, 'tests', 'consumer-strict');
+  if (existsSync(join(consumerDir, 'tsconfig.json'))) {
+    const proc = Bun.spawnSync(['bunx', 'tsc', '--noEmit', '-p', 'tsconfig.json'], {
+      cwd: consumerDir,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    const out = (proc.stdout.toString() + proc.stderr.toString())
+      .split('\n')
+      .filter((l) => !/^Resolving|^Resolved|^Saved/.test(l))
+      .join('\n')
+      .trim();
+    if (proc.exitCode === 0 && out.length === 0) {
+      console.log('  ✓ consumer-strict');
+    } else {
+      failures++;
+      failed.push({ pkg: 'consumer-strict', out });
+      console.log('  ✗ consumer-strict');
+    }
+  }
+  console.log();
+}
+
 if (failures === 0) {
   console.log(`All ${packages.length} packages type-check cleanly.`);
   process.exit(0);

tests/consumer-strict/tsconfig.json

@@ -0,0 +1,45 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["bun-types"],
+    "ignoreDeprecations": "6.0",
+    "baseUrl": ".",
+    "paths": {
+      "@shade/core": ["../../packages/shade-core/src/index.ts"],
+      "@shade/proto": ["../../packages/shade-proto/src/index.ts"],
+      "@shade/crypto-web": ["../../packages/shade-crypto-web/src/index.ts"],
+      "@shade/observability": ["../../packages/shade-observability/src/index.ts"],
+      "@shade/keychain": ["../../packages/shade-keychain/src/index.ts"],
+      "@shade/key-transparency": ["../../packages/shade-key-transparency/src/index.ts"],
+      "@shade/storage-sqlite": ["../../packages/shade-storage-sqlite/src/index.ts"],
+      "@shade/storage-postgres": ["../../packages/shade-storage-postgres/src/index.ts"],
+      "@shade/storage-encrypted": ["../../packages/shade-storage-encrypted/src/index.ts"],
+      "@shade/streams": ["../../packages/shade-streams/src/index.ts"],
+      "@shade/transport": ["../../packages/shade-transport/src/index.ts"],
+      "@shade/transport-bridge": ["../../packages/shade-transport-bridge/src/index.ts"],
+      "@shade/transport-webrtc": ["../../packages/shade-transport-webrtc/src/index.ts"],
+      "@shade/server": ["../../packages/shade-server/src/index.ts"],
+      "@shade/inbox-server": ["../../packages/shade-inbox-server/src/index.ts"],
+      "@shade/inbox": ["../../packages/shade-inbox/src/index.ts"],
+      "@shade/transfer": ["../../packages/shade-transfer/src/index.ts"],
+      "@shade/files": ["../../packages/shade-files/src/index.ts"],
+      "@shade/recovery": ["../../packages/shade-recovery/src/index.ts"],
+      "@shade/observer": ["../../packages/shade-observer/src/index.ts"],
+      "@shade/dashboard": ["../../packages/shade-dashboard/src/index.ts"],
+      "@shade/sdk": ["../../packages/shade-sdk/src/index.ts"],
+      "@shade/widgets": ["../../packages/shade-widgets/src/index.ts"]
+    }
+  },
+  "include": ["./*.ts"]
+}

tests/consumer-strict/use-files.ts

@@ -0,0 +1,43 @@
+/**
+ * Consumer-strict smoke for `@shade/files`.
+ *
+ * Compiled with `lib: ["ES2022", "DOM"]` + `exactOptionalPropertyTypes` +
+ * `skipLibCheck: false` to mimic a downstream consumer like Dispatch.
+ * Catches the class of bug where our internal narrower types (e.g. a
+ * locally-defined `MinimalReader`) reject native browser types
+ * (e.g. `ReadableStreamDefaultReader`) the consumer would naturally
+ * pass in.
+ *
+ * If this file fails to compile, the published packages will fail in
+ * any consumer's strict tsc — pre-publish gate must catch it.
+ */
+import { decideInline, type WriteSource } from '@shade/files';
+
+declare const blob: Blob;
+declare const stream: ReadableStream<Uint8Array>;
+declare const bytes: Uint8Array;
+
+async function smoke(): Promise<void> {
+  // Each branch of WriteSource must round-trip through decideInline()
+  // when given the natively-typed inputs a browser app would supply.
+  const sources: WriteSource[] = [
+    bytes,
+    blob,
+    stream,
+    { stream, size: 1024 },
+    { stream, size: 1024, contentType: 'image/png' },
+  ];
+  for (const src of sources) {
+    const decision = await decideInline(src);
+    if (decision.kind === 'streams') {
+      const reader = decision.stream.getReader();
+      const { value, done } = await reader.read();
+      if (!done && value !== undefined) {
+        void value.byteLength;
+      }
+      reader.releaseLock();
+    }
+  }
+}
+
+void smoke;

tests/consumer-strict/use-key-transparency.ts

@@ -0,0 +1,42 @@
+/**
+ * Consumer-strict smoke for `@shade/key-transparency`.
+ *
+ * The package was the source of the 4 noUnusedLocals + the IndexProofWire
+ * privacy bug in 4.0.0. This smoke imports every public type and
+ * exercises the witness-fetcher contract that the SDK plugs into.
+ */
+import {
+  LightWitness,
+  type SignedTreeHead,
+  type STHWire,
+  type WitnessFetcher,
+} from '@shade/key-transparency';
+
+declare const crypto: import('@shade/core').CryptoProvider;
+declare const logPublicKey: Uint8Array;
+
+async function smoke(): Promise<void> {
+  const fetcher: WitnessFetcher = {
+    async fetchLatestSTH(): Promise<STHWire> {
+      const res = await fetch('https://shade.example.com/v1/kt/sth');
+      return (await res.json()) as STHWire;
+    },
+    async fetchConsistencyProof(
+      from: number,
+      to: number,
+    ): Promise<{ proof: string[] }> {
+      const res = await fetch(
+        `https://shade.example.com/v1/kt/consistency?from=${from}&to=${to}`,
+      );
+      return (await res.json()) as { proof: string[] };
+    },
+  };
+  const witness = new LightWitness({ crypto, logPublicKey, fetcher });
+  void witness;
+}
+
+void smoke;
+
+// Verify the type is reachable with no `any` leak.
+declare const sth: SignedTreeHead;
+void sth.treeSize;

tests/consumer-strict/use-sdk.ts

@@ -0,0 +1,50 @@
+/**
+ * Consumer-strict smoke for `@shade/sdk`.
+ *
+ * Exercises the high-level `createShade()` flow + the V3.x opt-in
+ * surfaces (KT, WebRTC, fingerprint gates). Compiles under DOM-lib +
+ * exactOptionalPropertyTypes to flag any private-type leaks like the
+ * `Promise<unknown>` on `fetchLatestSTH` that 4.0.0 shipped.
+ */
+import {
+  createShade,
+  type Shade,
+  type ShadeConfig,
+  type ShadeWebRtcConfig,
+} from '@shade/sdk';
+
+declare const factory: ShadeWebRtcConfig['factory'];
+
+async function smoke(): Promise<void> {
+  const config: ShadeConfig = {
+    prekeyServer: 'https://shade.example.com',
+    storage: 'memory',
+    address: 'alice@example.com',
+    keyTransparency: {
+      mode: 'observe-strict',
+      logPublicKey: new Uint8Array(32),
+    },
+  };
+  const shade: Shade = await createShade(config);
+
+  const env = await shade.send('bob', 'hi');
+  void env;
+
+  shade.onMessage(async (from: string, plaintext: string) => {
+    void from;
+    void plaintext;
+  });
+
+  await shade.beforeFirstLargeFile(10 * 1024 * 1024, async (ctx) => {
+    void ctx.peerAddress;
+    void ctx.fingerprint;
+    void ctx.gate;
+    return true;
+  });
+
+  shade.configureWebRTC({ factory });
+
+  void (await shade.fingerprint);
+}
+
+void smoke;