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-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);