release(v4.0.1): strict-TS publishability fixes

4.0.0 shipped TypeScript source as published main/types, but several
files only compiled inside the monorepo. Consumer projects (Dispatch,
etc.) running their own strict tsc against our published source hit:

- @shade/key-transparency: 4 noUnusedLocals violations
  (IndexAbsenceProof, IndexInclusionProof, IndexProofWire, nodeHash)
- @shade/sdk: KT verifier callbacks returned Promise<unknown> instead
  of Promise<STHWire> / Promise<{ proof: string[] }>
- @shade/sdk: thumbnail.ts globalThis cast collided with consumer's
  lib.dom-supplied createImageBitmap signature
- @shade/files: cycle with @shade/sdk produced "this is not assignable
  to type 'Shade'" because hoisted node_modules layouts duplicated the
  Shade class. Broken by replacing `import type { Shade }` with a
  local structural ShadeBridge interface.
- @shade/storage-encrypted: KeyUsage (lib.dom) used under
  lib: ["ES2022"]
- @shade/transport-bridge: ReadableStreamDefaultReader<any> ↔
  <Uint8Array> mismatch
- @shade/keychain / @shade/dashboard / @shade/storage-encrypted
  tsconfig rootDir / include hygiene

Tooling: scripts/typecheck-all.ts runs `bunx tsc --noEmit` against
every workspace package's tsconfig and fails on any error. Wired into
publish:dry / publish:all and publish-shade.sh as a hard gate so this
class of bug cannot recur.

All 24 packages bumped to 4.0.1 in lockstep.

Migration: <ShadeFilesProvider> now requires an explicit `files` prop
(pass `shade.files`). Wire format unchanged.

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

packages/shade-cli/package.json

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

packages/shade-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/core",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "type": "module",
   "scripts": {
     "dev": "vite",

packages/shade-dashboard/tsconfig.json

@@ -8,5 +8,5 @@
     "module": "ESNext",
     "moduleResolution": "bundler"
   },
-  "include": ["src", "vite.config.ts"]
+  "include": ["src"]
 }

packages/shade-files/package.json

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

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

@@ -1,4 +1,4 @@
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
 import {
   KIND_CUSTOM_V1,
   KIND_DELETE_V1,
@@ -184,7 +184,7 @@ export interface CreateFileClientOptions {
  * transfers that carry the actual bytes.
  */
 export function createFileClient(
-  shade: Shade,
+  shade: ShadeBridge,
   channel: ShadeFileRpcChannel,
   pending: PendingRpcRegistry,
   peerAddress: string,

packages/shade-files/src/integration/files-namespace.ts

@@ -4,7 +4,7 @@
  * so a single Shade can simultaneously serve files AND consume them from
  * peers without paying the setup cost twice.
  */
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from './shade-bridge.js';
 import {
   attachClientRouting,
   attachFileHandler,
@@ -54,7 +54,7 @@ interface NamespaceState {
  * Construct a `FilesNamespace` bound to a Shade instance. The SDK's
  * `Shade.files` getter calls this lazily and memoizes the result.
  */
-export function createFilesNamespace(shade: Shade): FilesNamespace {
+export function createFilesNamespace(shade: ShadeBridge): FilesNamespace {
   const state: NamespaceState = {
     channel: new ShadeFileRpcChannel(shade),
     pending: new PendingRpcRegistry(),

packages/shade-files/src/integration/shade-bridge.ts

@@ -0,0 +1,67 @@
+/**
+ * Structural surface @shade/files needs from a Shade instance.
+ *
+ * Defining this locally — instead of `import type { Shade } from '@shade/sdk'`
+ * — breaks the @shade/sdk ↔ @shade/files dependency cycle. Without this
+ * break, a consumer that installs @shade/sdk from a registry ends up with
+ * two distinct `Shade` classes in `node_modules` (one from
+ * `@shade/sdk/node_modules/@shade/files/.../Shade`, one from
+ * `@shade/sdk/Shade`). TypeScript treats them as nominally different types,
+ * raising `this is not assignable to Shade` from inside SDK methods that
+ * pass `this` into `createFilesNamespace`.
+ *
+ * The Shade class structurally implements every member listed below, so
+ * `createFilesNamespace(this)` from the SDK side compiles regardless of
+ * how many copies of @shade/sdk a consumer's package manager installs.
+ *
+ * Member signatures match Shade's exactly so this is a structural
+ * subtype, not a parallel API.
+ */
+import type { ShadeEnvelope } from '@shade/core';
+import type {
+  IncomingTransfer,
+  TransferHandle,
+  TransferOptions,
+} from '@shade/transfer';
+import type { ObservabilityHook } from '@shade/observability';
+
+export interface ShadeBridge {
+  /** Address that names this Shade instance to peers. */
+  readonly myAddress: string;
+
+  /** Encrypt + send `plaintext` to `peer`; returns the wire envelope. */
+  send(peer: string, plaintext: string): Promise<ShadeEnvelope>;
+
+  /**
+   * Subscribe to incoming ratchet plaintext. Returns an unsubscribe.
+   * Handlers may be sync or async; async handlers are awaited in
+   * registration order.
+   */
+  onMessage(
+    handler: (from: string, plaintext: string) => void | Promise<void>,
+  ): () => void;
+
+  /**
+   * Upload bytes via the SDK's transfer engine. Required when the bridge
+   * is used with `streams` content I/O (read/write > 256 KiB).
+   */
+  upload(opts: TransferOptions): Promise<TransferHandle>;
+
+  /** Subscribe to incoming transfers initiated by a peer. */
+  onIncomingTransfer(
+    handler: (incoming: IncomingTransfer) => void | Promise<void>,
+  ): Promise<() => void>;
+
+  /** Fingerprint accessor for the trust-gate hooks. */
+  getFingerprintFor(peer: string): Promise<string>;
+
+  /**
+   * Optional inheritable observability bus. Files inherits the bus when
+   * the SDK passes one in via the namespace; otherwise files runs without
+   * observability hooks.
+   */
+  getObservability?(): ObservabilityHook | undefined;
+
+  /** Optional control-envelope passthrough used by the WebRTC bridge. */
+  deliverControlEnvelope?(peer: string, envelope: ShadeEnvelope): Promise<void>;
+}

packages/shade-files/src/react/ShadeFilesProvider.tsx

@@ -1,17 +1,23 @@
 import React, { createContext, useContext, useMemo } from 'react';
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
 import type { FilesNamespace } from '../integration/files-namespace.js';
 
 export interface ShadeFilesContextValue {
-  shade: Shade;
+  shade: ShadeBridge;
   files: FilesNamespace;
 }
 
 const ShadeFilesContext = createContext<ShadeFilesContextValue | null>(null);
 
 export interface ShadeFilesProviderProps {
-  /** Initialized `Shade` instance. `files` namespace is read off it lazily. */
-  shade: Shade;
+  /** Initialized `Shade` instance (or any `ShadeBridge`-shaped object). */
+  shade: ShadeBridge;
+  /**
+   * The `FilesNamespace` to expose to children. Pass `shade.files` from
+   * `@shade/sdk`, or a `createFilesNamespace(...)` result for tests /
+   * custom bridges.
+   */
+  files: FilesNamespace;
   children: React.ReactNode;
 }
 
@@ -20,8 +26,8 @@ export interface ShadeFilesProviderProps {
  * `<ShadeRuntimeProvider>` in `@shade/widgets` so file-RPC consumers
  * don't pull in the widget tree.
  */
-export function ShadeFilesProvider({ shade, children }: ShadeFilesProviderProps): React.ReactElement {
-  const value = useMemo<ShadeFilesContextValue>(() => ({ shade, files: shade.files }), [shade]);
+export function ShadeFilesProvider({ shade, files, children }: ShadeFilesProviderProps): React.ReactElement {
+  const value = useMemo<ShadeFilesContextValue>(() => ({ shade, files }), [shade, files]);
   return React.createElement(ShadeFilesContext.Provider, { value }, children);
 }
 

packages/shade-files/src/rpc/channel.ts

@@ -1,4 +1,4 @@
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
 import {
   encodeEnvelope,
   looksLikeFileEnvelope,
@@ -35,7 +35,7 @@ export class ShadeFileRpcChannel {
   private readonly unsubscribe: () => void;
   private destroyed = false;
 
-  constructor(private readonly shade: Shade) {
+  constructor(private readonly shade: ShadeBridge) {
     this.unsubscribe = shade.onMessage(async (from, plaintext) => {
       if (!looksLikeFileEnvelope(plaintext)) return;
       const classified = tryParseEnvelope(plaintext);
@@ -72,6 +72,11 @@ export class ShadeFileRpcChannel {
     if (this.destroyed) throw new Error('ShadeFileRpcChannel: destroyed');
     const plaintext = encodeEnvelope(envelope);
     const ratchetEnvelope = await this.shade.send(peerAddress, plaintext);
+    if (this.shade.deliverControlEnvelope === undefined) {
+      throw new Error(
+        'ShadeFileRpcChannel: shade.deliverControlEnvelope is required — call shade.configureTransfers({ resolveBaseUrl }) before using the files namespace.',
+      );
+    }
     await this.shade.deliverControlEnvelope(peerAddress, ratchetEnvelope);
   }
 

packages/shade-files/src/server/handler-context.ts

@@ -1,4 +1,4 @@
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
 import type { StandardOp } from '../protocol/kinds.js';
 
 export type OpKind = StandardOp | `custom:${string}`;
@@ -42,7 +42,7 @@ export function buildOpContext<TArgs>(args: {
   signal: AbortSignal;
   idempotencyKey: string | undefined;
   attemptNumber: number;
-  shade: Shade;
+  shade: ShadeBridge;
 }): OpContext<TArgs> {
   return {
     op: args.op,

packages/shade-files/src/server/handler.ts

@@ -1,4 +1,4 @@
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
 import type { ZodTypeAny } from 'zod';
 import {
   MUTATION_OPS,
@@ -215,7 +215,7 @@ const OP_SCHEMAS: Record<StandardOp, OpSchemaPair> = {
  * via `Shade.files.serve(...)` in the SDK).
  */
 export function createFileHandler(
-  shade: Shade,
+  shade: ShadeBridge,
   config: FileHandlerConfig,
 ): FileHandler {
   const idempotency = new IdempotencyCache(config.idempotency);

packages/shade-inbox-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/inbox-server",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-key-transparency/src/index-tree.ts

@@ -21,7 +21,7 @@
  * the dataset grows enough that flat re-hash becomes a bottleneck.
  */
 
-import { leafHash, nodeHash, emptyRootHash } from './hashes.js';
+import { leafHash, emptyRootHash } from './hashes.js';
 import { sha256Sync } from './sha256.js';
 import { constantTimeEqual } from './util.js';
 import { mth, auditPath, recomputeRootFromAuditPath } from './log.js';

packages/shade-key-transparency/src/manager.ts

@@ -24,8 +24,6 @@ import { MerkleLog, auditPath } from './log.js';
 import {
   AddressIndex,
   type AddressIndexEntry,
-  type IndexAbsenceProof,
-  type IndexInclusionProof,
 } from './index-tree.js';
 import {
   type SignedTreeHead,

packages/shade-key-transparency/src/proof.ts

@@ -111,7 +111,7 @@ interface IndexAbsenceWire {
   } | null;
 }
 
-type IndexProofWire = IndexInclusionWire | IndexAbsenceWire;
+export type IndexProofWire = IndexInclusionWire | IndexAbsenceWire;
 
 interface BundleInclusionWire {
   kind: 'inclusion' | 'tombstone';

packages/shade-key-transparency/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}

packages/shade-keychain/package.json

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

packages/shade-keychain/tsconfig.json

@@ -1,4 +1,5 @@
 {
   "extends": "../../tsconfig.json",
-  "include": ["src/**/*", "tests/**/*"]
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
 }

packages/shade-observability/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/observability",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-sdk/src/shade.ts

@@ -21,7 +21,7 @@ import {
 import { encodeEnvelope, decodeEnvelope, inspectEnvelopeType } from '@shade/proto';
 import { ShadeFetchTransport, type KTVerifierOptions } from '@shade/transport';
 import { LightWitness } from '@shade/key-transparency';
-import type { SignedTreeHead } from '@shade/key-transparency';
+import type { SignedTreeHead, STHWire } from '@shade/key-transparency';
 import {
   TransferEngine,
   ShadeTransferHttpTransport,
@@ -217,15 +217,15 @@ export class Shade {
         maxStaleMs: this.config.keyTransparency.maxStaleMs,
         maxStored: this.config.keyTransparency.witnessMaxStored,
         fetcher: {
-          async fetchLatestSTH() {
+          async fetchLatestSTH(): Promise<STHWire> {
             const res = await fetch(`${baseUrl}/v1/kt/sth`);
             if (!res.ok) throw new Error(`KT /sth: ${res.status}`);
-            return res.json();
+            return (await res.json()) as STHWire;
           },
-          async fetchConsistencyProof(from, to) {
+          async fetchConsistencyProof(from, to): Promise<{ proof: string[] }> {
             const res = await fetch(`${baseUrl}/v1/kt/consistency?from=${from}&to=${to}`);
             if (!res.ok) throw new Error(`KT /consistency: ${res.status}`);
-            return res.json();
+            return (await res.json()) as { proof: string[] };
           },
         },
       });

packages/shade-sdk/src/thumbnail.ts

@@ -59,12 +59,16 @@ interface CreateImageBitmapFn {
 }
 
 function getOffscreenCanvasCtor(): OffscreenCanvasCtor | null {
-  const g = globalThis as { OffscreenCanvas?: OffscreenCanvasCtor };
+  const g = globalThis as unknown as { OffscreenCanvas?: OffscreenCanvasCtor };
   return g.OffscreenCanvas ?? null;
 }
 
 function getCreateImageBitmap(): CreateImageBitmapFn | null {
-  const g = globalThis as { createImageBitmap?: CreateImageBitmapFn };
+  // `globalThis.createImageBitmap` (when DOM lib is loaded) has a wider
+  // signature than our minimal `CreateImageBitmapFn`. Cast through
+  // `unknown` so consumer tsconfigs that include "DOM" don't reject the
+  // narrower local type as "insufficiently overlapping".
+  const g = globalThis as unknown as { createImageBitmap?: CreateImageBitmapFn };
   return g.createImageBitmap ?? null;
 }
 

packages/shade-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/server",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-storage-encrypted/src/crypto/aead.ts

@@ -11,11 +11,23 @@
 
 const NONCE_LEN = 12;
 
+// Local mirror of the WebCrypto KeyUsage union — avoids depending on
+// `lib.dom` (we run on Bun + plain ES2022) while keeping API parity.
+type WebCryptoKeyUsage =
+  | 'encrypt'
+  | 'decrypt'
+  | 'sign'
+  | 'verify'
+  | 'deriveKey'
+  | 'deriveBits'
+  | 'wrapKey'
+  | 'unwrapKey';
+
 function bs(u: Uint8Array): ArrayBuffer {
   return u as unknown as ArrayBuffer;
 }
 
-async function importKey(key: Uint8Array, usages: KeyUsage[]): Promise<CryptoKey> {
+async function importKey(key: Uint8Array, usages: WebCryptoKeyUsage[]): Promise<CryptoKey> {
   if (key.length !== 32) throw new Error(`AES-256-GCM key must be 32 bytes, got ${key.length}`);
   return globalThis.crypto.subtle.importKey('raw', bs(key), 'AES-GCM', false, usages);
 }

packages/shade-storage-encrypted/tsconfig.json

@@ -1,4 +1,5 @@
 {
   "extends": "../../tsconfig.json",
-  "include": ["src/**/*", "tests/**/*"]
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
 }

packages/shade-storage-postgres/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/storage-postgres",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-transport-bridge/src/sse-bridge.ts

@@ -127,7 +127,7 @@ export class SseBridge implements BridgeTransport {
     if (!res.body) {
       throw new BridgeError('SSE response has no body');
     }
-    this.currentReader = res.body.getReader();
+    this.currentReader = res.body.getReader() as ReadableStreamDefaultReader<Uint8Array>;
     this.connected = true;
   }
 

packages/shade-transport-webrtc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/transport-webrtc",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "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.0",
+  "version": "4.0.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-widgets/src/components/transfer/ThumbnailPreview.tsx

@@ -2,7 +2,6 @@ import React, { useEffect, useRef, useState } from 'react';
 import {
   isAllowedThumbnailMime,
   THUMBNAIL_MAX_BYTES,
-  type ThumbnailMime,
 } from '@shade/sdk';
 import { useShadeRuntimeTheme } from '../../ShadeRuntimeProvider.js';