@siafoundation/sia-storage 0.1.2 → 0.1.4

package/README.md

@@ -96,6 +96,36 @@ button.onclick = () => streams.download(object, { name: 'clip.mp4' })
 streams.close()
 ```
 
+### Status and progress
+
+`url()` and `download()` take three optional callbacks, for a loading state, a progress readout or a map of the hosts serving the file. They work the same whether the worker streams the file or the page reads it itself.
+
+```ts
+const video = await streams.url(object, {
+  name: 'clip.mp4',
+  type: 'video/mp4',
+  onStatus: (status) => setStatus(status),
+  onProgress: (bytes) => setReceived(bytes),
+  onShard: (shard) => markHost(shard.hostKey, shard.slabIndex),
+})
+```
+
+- **`onStatus`** goes `connecting`, `downloading`, `idle`, and around again for each new read, such as a seek. `connecting` lasts until the first bytes arrive, and on the URL's first read it covers the worker connecting to the indexer. `idle` means no read is in flight, after the last one finished, was cancelled or failed.
+- **`onProgress`** is the total bytes the URL has received. It counts transfer, not coverage: a range read again after a seek counts again, so it can pass the file size, and a new URL for the same file starts from zero. For how much of a video is buffered, use the media element's `buffered`. A `download()` reads the file once, so its total ends at the file size.
+- **`onShard`** is called for each piece the SDK reads from a host: the host key, slab, shard index, bytes read and time taken. A slab is read in chunks, so the same shard comes up once per chunk.
+
+A URL without these callbacks costs nothing, and one with only some of them gets only those reports. The worker sends bytes and shards in batches, at most every 100 ms and just before each status change, and stops when the URL is released. A callback that throws is reported to the console and does not stop the stream or the other callbacks.
+
+### Start sooner
+
+A stream connects to the hosts that hold the file when the video asks for its first bytes, which takes a few seconds. `warm()` does it ahead of time, by reading one byte, which asks each host of the file's first part for a single 64-byte segment. Call it when a play is likely, such as when the pointer reaches a Play button. It reports no status or progress and never rejects.
+
+```ts
+const video = await streams.url(object, { name: 'clip.mp4', type: 'video/mp4' })
+videoElement.src = video.url
+playButton.onpointerenter = () => void video.warm()
+```
+
 ### Serve the worker
 
 The worker is one file, `sia-storage-sw.js`, served from your site's root. Use the line for your setup.
@@ -188,6 +218,7 @@ Near-identical surfaces. Real differences:
 - App identifier: `appMeta.appId: string (hex)` on browser, `appMeta.id: Buffer(32)` on Node.
 - Numeric sizes are `number` on browser, `bigint` on Node. Byte arrays are `Uint8Array` on browser, `Buffer` on Node (`Buffer` is a `Uint8Array` subclass; both accept either as input).
 - Sharing key seeds are hex `string` on browser, `Buffer` on Node. This covers `SharingKey.seed()`, `SharingKey.fromSeed(seed)`, and `SharedSdk.connect(indexerUrl, seed)`.
+- `sharedSdk.objectSummaries(offset, limit)` resolves `ObjectSummary` class instances on browser, which own WASM memory and are disposable like `PinnedObject`. On Node it resolves plain objects.
 - `sdk.unshareObject(key, object)` takes a `PinnedObject` on browser and an object id `string` on Node.
 - `sdk.hosts(query?)` and `sharedSdk.hosts(query?)` accept a `HostQuery` on browser; on Node they take no arguments.
 - `openStreams` gives a browser page URLs that a service worker serves. Node reads objects with `sdk.download(object, { offset, length })`, which already streams a range, so it needs no worker. On Node, `enableStreaming()` resolves false, and `url` and `download` on an `openStreams` handle reject.
@@ -219,7 +250,7 @@ Returned from `Builder.register()`, `Builder.connected()`, or `Builder.connectPr
 | `updateObjectMetadata(object)` | Push local metadata changes to the indexer. |
 | `objectShareUrl(object, validUntil)` / `objectFromShareUrl(url)` | Create / consume share URLs. |
 | `objectEvents(cursor?, limit)` | Paginated change feed. |
-| `hosts(query?)` / `slab(id)` / `account()` / `pruneSlabs()` | Indexer reads. |
+| `hosts(query?)` / `account()` / `pruneSlabs(before?)` | Indexer reads. `pruneSlabs` unpins slabs no object uses; `before` limits it to slabs pinned before that date, and omitting it leaves the cutoff to the indexer. |
 | `createSharingKey(description, expiresAt?)` | Create a `SharingKey` for read-only sharing. |
 | `sharingKeys(offset, limit)` / `sharingKey(key)` | List keys / fetch one key's `KeyRecord`. |
 | `shareObject(key, object)` / `unshareObject(key, object)` | Attach / detach an object on a sharing key. |
@@ -280,20 +311,27 @@ sharing key's seed. Downloads are paid for by the key's owner.
 |---|---|
 | `stats()` | The key's `KeyStats` snapshot. |
 | `object(id)` / `objects(offset, limit)` | Read the objects the key grants access to. |
+| `objectSummaries(offset, limit)` | Lists the key's objects without their slabs, which is much smaller and faster than `objects`. Summaries describe an object but cannot be downloaded. Fetch the full object with `object(id)` for that. |
 | `download(object, options?)` | Returns a `ReadableStream`. |
 | `hosts(query?)` | Hosts serving this key's objects. |
 
+### `ObjectSummary`
+
+From `sharedSdk.objectSummaries()`.
+
+`id` · `size` · `metadata` · `createdAt` · `updatedAt`
+
 ### Streaming
 
 | | |
 |---|---|
 | `openStreams(sdk, credentials)` | `Streams` for one SDK's objects. An `Sdk` takes `{ indexerUrl, appMeta }` and a `SharedSdk` takes `{ indexerUrl, seed }`, typed by which one you pass. |
-| `streams.url(object, options)` | `{ url, blob?, release() }`. Streams where it can, else reads the whole object into `blob`. |
+| `streams.url(object, options)` | `{ url, blob?, warm(), release() }`. Streams where it can, else reads the whole object into `blob`. |
 | `streams.download(object, options)` | Saves the object. Resolves `'streaming'`, `'saved'` or `'cancelled'`. Call it from a click handler. |
 | `streams.close()` | Cancels this handle's streams. Other handles on the same SDK keep theirs. |
 | `enableStreaming(options?)` | Registers the worker and resolves whether streaming is on. `openStreams` calls it for you, so call it only to pass `workerUrl`, `scope` or `type`. |
 
-`options` for `url` and `download`: `name`, `type` (MIME), `onError(message)` for failures after streaming starts (logged when omitted), `onProgress(bytes)` when the page reads the object itself, and `signal` for `url`.
+`options` for `url` and `download`: `name`, `type` (MIME), `onError(message)` for failures after streaming starts (logged when omitted), `onStatus`, `onProgress` and `onShard` (see [Status and progress](#status-and-progress)), and `signal` for `url`.
 
 ### `@siafoundation/sia-storage/stream-worker`
 

package/dist/{chunk-QYQQIWFH.js → chunk-YOMDUMYW.js}

@@ -14,6 +14,7 @@ function reportStreamError(error, name, range) {
 }
 
 // src/stream/protocol.ts
+var STREAM_EVENTS = ["status", "progress", "shards"];
 var STREAM_PATH = /\/__sia_stream__\/([^/]+)\/([^/]+)\/[^/]+$/;
 function streamPath(scope, clientId, token) {
   return `${scope}__sia_stream__/${clientId}/${token}/file`;
@@ -26,14 +27,17 @@ var strings = (data, fields) => fields.every((field) => typeof data?.[field] ===
 function isAppMetadata(value) {
   return strings(value, ["appId", "name", "description", "serviceUrl"]);
 }
+var isKeyHex = (value) => typeof value === "string" && /^[0-9a-f]{64}$/i.test(value);
 function isConnection(value) {
   const data = value;
-  if (data?.kind === "shared") return strings(data, ["indexerUrl", "seed"]);
+  if (data?.kind === "shared") {
+    return strings(data, ["indexerUrl", "seed"]) && (data.sealKey === void 0 || isKeyHex(data.sealKey));
+  }
   return data?.kind === "app" && strings(data, ["indexerUrl", "appKey"]) && isAppMetadata(data.appMeta);
 }
 function isSourceReply(reply) {
   const data = reply;
-  return data?.type === "source" && strings(data, ["session", "objectId", "name", "mime"]) && isConnection(data.connection) && (data.connection.kind === "shared" || typeof data.sealed === "object" && data.sealed !== null) && Number.isSafeInteger(data.size) && data.size >= 0;
+  return data?.type === "source" && strings(data, ["session", "objectId", "name", "mime"]) && isConnection(data.connection) && (data.connection.kind === "shared" || typeof data.sealed === "object" && data.sealed !== null) && Number.isSafeInteger(data.size) && data.size >= 0 && (data.events === void 0 || Array.isArray(data.events) && data.events.every((event) => STREAM_EVENTS.includes(event)));
 }
 function requestReply(target, message, { timeout, signal }) {
   return new Promise((resolve, reject) => {
@@ -71,4 +75,4 @@ export {
   isSourceReply,
   requestReply
 };
-//# sourceMappingURL=chunk-QYQQIWFH.js.map
+//# sourceMappingURL=chunk-YOMDUMYW.js.map

package/dist/chunk-YOMDUMYW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stream/errors.ts","../src/stream/protocol.ts"],"sourcesContent":["/** Only sanitized strings cross the diagnostic boundary, never raw SDK objects. */\nexport function streamErrorMessage(error: unknown): string {\n  const message =\n    error instanceof Error\n      ? error.message\n      : typeof error === 'string'\n        ? error\n        : 'Unknown streaming failure'\n  return message\n    .replace(/\\b(?:https?|wss?|sia):\\/\\/[^\\s\"'<>]+/gi, '[URL redacted]')\n    .replace(/(?:bearer\\s+)[^\\s,;]+/gi, 'Bearer [redacted]')\n    .replace(\n      /((?:seed|share|token|key|authorization)\\s*[=:]\\s*)[^\\s,;]+/gi,\n      '$1[redacted]',\n    )\n    .replace(/[a-f0-9]{64,}/gi, '[redacted]')\n    .replace(/[\\r\\n\\t]/g, ' ')\n    .slice(0, 1000)\n}\n\nexport function reportStreamError(\n  error: unknown,\n  name: string,\n  range: { offset: number; length: number } | undefined,\n) {\n  const message = streamErrorMessage(error)\n  // One string rather than an object, so it reads the same in every console.\n  const bytes = range\n    ? ` bytes ${range.offset}-${range.offset + range.length - 1}`\n    : ''\n  console.error(`[Sia stream] ${streamErrorMessage(name)}${bytes}: ${message}`)\n  return message\n}\n","/**\n * Messages between a page and its streaming service worker.\n *\n * Stream URLs carry only the page's client id and a random token. When the\n * worker meets a token it does not know, it asks the page that made it for the\n * file and the share's credentials. The page and a worker can come from\n * different deployed versions, so the worker checks the page's reply before\n * using it.\n */\nimport type {\n  AppMetadata,\n  SealedObject,\n  ShardProgress,\n} from '../../wasm/sia_storage_wasm.js'\n\n/**\n * What a stream URL is doing. `connecting` is a request waiting for its first\n * bytes, which on the URL's first request includes the worker connecting its\n * SDK and finding the object. `downloading` means bytes are arriving. `idle`\n * means no request for the URL is in flight, after the last one finished, was\n * cancelled or failed.\n */\nexport type StreamStatus = 'connecting' | 'downloading' | 'idle'\n\n/** The reports a page can ask for, one per callback it was given. */\nexport type StreamEvent = 'status' | 'progress' | 'shards'\nconst STREAM_EVENTS: readonly unknown[] = ['status', 'progress', 'shards']\n\n/**\n * What the worker connects its own SDK with. A `SharedSdk` reconnects from its\n * sharing key's seed, and an `Sdk` from its app key, as hex, and app metadata.\n * A `SharedSdk`'s `sealKey` is the hex of the random key the page seals its\n * objects with. A page from before it existed sends none.\n */\nexport type Connection =\n  | { kind: 'shared'; indexerUrl: string; seed: string; sealKey?: string }\n  | { kind: 'app'; indexerUrl: string; appKey: string; appMeta: AppMetadata }\n\nexport type SourceDetails = {\n  // One per opened SDK, so the worker can release it as a whole.\n  session: string\n  connection: Connection\n  objectId: string\n  // The object, sealed with its app key or the share's `sealKey`, so the\n  // worker can open it without a lookup. Without it the worker looks the\n  // object up by `objectId`.\n  sealed?: SealedObject\n  name: string\n  mime: string\n  size: number\n  // The reports the page wants for this URL. The worker sends no others, and\n  // asks the SDK for shard reports only when `shards` is here.\n  events?: StreamEvent[]\n}\n\n/** Page to worker. */\nexport type PageMessage =\n  | { type: 'sia-client' }\n  | { type: 'sia-release'; token: string }\n  | { type: 'sia-release-share'; session: string }\n\n/** Worker to page. */\nexport type WorkerMessage =\n  | { type: 'sia-source'; token: string }\n  | {\n      type: 'sia-stream-error'\n      token: string\n      message: string\n      offset?: number\n      length?: number\n    }\n  | { type: 'sia-stream-status'; token: string; status: StreamStatus }\n  | {\n      type: 'sia-stream-progress'\n      token: string\n      // Bytes served since the previous progress message.\n      bytes: number\n      shards: ShardProgress[]\n    }\n\n/** The worker's answer to `sia-client`. */\nexport type ClientReply = { clientId: string; supported: boolean }\n\n/** The page's answer to `sia-source`. */\nexport type SourceReply =\n  | ({ type: 'source' } & SourceDetails)\n  | { type: 'error' }\n\n// Stream URLs sit under the worker's scope, so a download's navigation, which\n// only a worker whose scope covers the URL can answer, reaches it on sites\n// served from a sub-path too.\nconst STREAM_PATH = /\\/__sia_stream__\\/([^/]+)\\/([^/]+)\\/[^/]+$/\n\n/** `scope` is the worker registration's scope URL, which ends in a slash. */\nexport function streamPath(scope: string, clientId: string, token: string) {\n  return `${scope}__sia_stream__/${clientId}/${token}/file`\n}\n\nexport function parseStreamPath(pathname: string) {\n  const match = STREAM_PATH.exec(pathname)\n  return match ? { clientId: match[1]!, token: match[2]! } : undefined\n}\n\ntype Fields = Record<string, unknown> | null | undefined\n\nconst strings = (data: Fields, fields: string[]) =>\n  fields.every((field) => typeof data?.[field] === 'string')\n\n/** Checked on both sides, so bad metadata fails in `openStreams`, not per request. */\nexport function isAppMetadata(value: unknown): value is AppMetadata {\n  return strings(value as Fields, ['appId', 'name', 'description', 'serviceUrl'])\n}\n\n// 32 bytes as hex, which is what the worker builds an AppKey from.\nconst isKeyHex = (value: unknown) =>\n  typeof value === 'string' && /^[0-9a-f]{64}$/i.test(value)\n\nfunction isConnection(value: unknown): value is Connection {\n  const data = value as Fields\n  if (data?.kind === 'shared') {\n    return (\n      strings(data, ['indexerUrl', 'seed']) &&\n      (data.sealKey === undefined || isKeyHex(data.sealKey))\n    )\n  }\n  return (\n    data?.kind === 'app' &&\n    strings(data, ['indexerUrl', 'appKey']) &&\n    isAppMetadata(data.appMeta)\n  )\n}\n\nexport function isSourceReply(\n  reply: unknown,\n): reply is { type: 'source' } & SourceDetails {\n  const data = reply as Fields\n  return (\n    data?.type === 'source' &&\n    strings(data, ['session', 'objectId', 'name', 'mime']) &&\n    isConnection(data.connection) &&\n    (data.connection.kind === 'shared' ||\n      (typeof data.sealed === 'object' && data.sealed !== null)) &&\n    Number.isSafeInteger(data.size) &&\n    (data.size as number) >= 0 &&\n    (data.events === undefined ||\n      (Array.isArray(data.events) &&\n        data.events.every((event) => STREAM_EVENTS.includes(event))))\n  )\n}\n\n/**\n * Posts `message` with a reply port and resolves with the first reply. Rejects\n * after `timeout` ms, or when `signal` aborts.\n */\nexport function requestReply(\n  target: { postMessage(message: unknown, transfer: Transferable[]): void },\n  message: unknown,\n  { timeout, signal }: { timeout?: number; signal?: AbortSignal },\n): Promise<unknown> {\n  return new Promise((resolve, reject) => {\n    const { port1, port2 } = new MessageChannel()\n    const timer =\n      timeout === undefined\n        ? undefined\n        : setTimeout(\n            () => settle(() => reject(new Error('No reply in time.'))),\n            timeout,\n          )\n    const abort = () => settle(() => reject(signal?.reason))\n    function settle(outcome: () => void) {\n      clearTimeout(timer)\n      signal?.removeEventListener('abort', abort)\n      port1.close()\n      port2.close()\n      outcome()\n    }\n    if (signal?.aborted) return abort()\n    signal?.addEventListener('abort', abort, { once: true })\n    port1.onmessage = ({ data }) => settle(() => resolve(data))\n    port1.onmessageerror = () =>\n      settle(() => reject(new Error('Unreadable reply.')))\n    try {\n      target.postMessage(message, [port2])\n    } catch (error) {\n      settle(() => reject(error))\n    }\n  })\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1,8 +1,53 @@
-import { AppMetadata, Sdk, SharedSdk, PinnedObject } from '../wasm/sia_storage_wasm.js';
-export { Account, AppKey, AppMetadata, Builder, DownloadOptions, Host, HostQuery, KeyRecord, KeyStats, ObjectEvent, PackedUpload, PinnedObject, PinnedSlab, Sdk, SealedObject, Sector, ShardProgress, SharedSdk, SharingKey, Slab, UploadOptions, encodedSize, generateRecoveryPhrase, setLogger, validateRecoveryPhrase } from '../wasm/sia_storage_wasm.js';
+import { ShardProgress, AppMetadata, Sdk, SharedSdk, PinnedObject } from '../wasm/sia_storage_wasm.js';
+export { Account, AppKey, AppMetadata, Builder, DownloadOptions, Host, HostQuery, KeyRecord, KeyStats, ObjectEvent, ObjectSummary, PackedUpload, PinnedObject, Sdk, SealedObject, Sector, ShardProgress, SharedSdk, SharingKey, Slab, UploadOptions, encodedSize, generateRecoveryPhrase, setLogger, validateRecoveryPhrase } from '../wasm/sia_storage_wasm.js';
 
 declare function detectPrivateRelay(): Promise<boolean>;
 
+/**
+ * Messages between a page and its streaming service worker.
+ *
+ * Stream URLs carry only the page's client id and a random token. When the
+ * worker meets a token it does not know, it asks the page that made it for the
+ * file and the share's credentials. The page and a worker can come from
+ * different deployed versions, so the worker checks the page's reply before
+ * using it.
+ */
+
+/**
+ * What a stream URL is doing. `connecting` is a request waiting for its first
+ * bytes, which on the URL's first request includes the worker connecting its
+ * SDK and finding the object. `downloading` means bytes are arriving. `idle`
+ * means no request for the URL is in flight, after the last one finished, was
+ * cancelled or failed.
+ */
+type StreamStatus = 'connecting' | 'downloading' | 'idle';
+
+/**
+ * Previews and downloads for pages that cannot stream through the service
+ * worker, where the page reads the object itself. A preview holds the whole
+ * file in memory as a Blob. A download writes straight to disk through the
+ * save picker where the browser has one, and buffers a Blob where it does not.
+ */
+
+/** What a file reports while it downloads, on the worker or in the page. */
+type FileEvents = {
+    /**
+     * Total bytes this URL has received. It is a transfer count, not how much of
+     * the file is held: a range read again after a seek counts again, so it can
+     * pass the file size, and a new URL for the same file starts from zero. For
+     * how much of a video is buffered, read the media element's `buffered`.
+     */
+    onProgress?: (bytesDownloaded: number) => void;
+    /**
+     * One call per piece the SDK read from a host. A download reads each slab in
+     * chunks, so the same slab and shard come again for every chunk, and only
+     * the first `minShards` hosts to answer for a chunk are reported.
+     */
+    onShard?: (progress: ShardProgress) => void;
+    /** Each change of what the URL is doing. See `StreamStatus`. */
+    onStatus?: (status: StreamStatus) => void;
+};
+
 /**
  * The page side of streaming.
  *
@@ -34,21 +79,29 @@ type AppCredentials = {
 };
 /** The credentials `openStreams` takes for each kind of SDK. */
 type CredentialsFor<S extends Sdk | SharedSdk> = S extends SharedSdk ? SharedCredentials : AppCredentials;
-type FileOptions = {
+type FileOptions = FileEvents & {
     /** Used for downloads and for the browser's media handling. */
     name: string;
     /** The MIME type. Defaults to `application/octet-stream`. */
     type?: string;
     /** A failure after streaming started. Without it, failures are logged. */
     onError?: (message: string) => void;
-    /** Bytes read so far, when the page reads the object itself. */
-    onProgress?: (bytesDownloaded: number) => void;
 };
 /** A URL for an `<img>`, `<video>`, `<audio>`, `<iframe>` or `fetch`. */
 type StreamedFile = {
     url: string;
     /** The whole file, when the page read it itself instead of streaming. */
     blob?: Blob;
+    /**
+     * Opens connections to the hosts holding the start of the file, so a play
+     * that follows gets its first bytes sooner. It reads one byte, which asks
+     * each host of the first slab for a single 64-byte segment, and reports no
+     * status or progress. Resolves when the byte arrives, or at once for a file
+     * the page read itself. Never rejects, since a play still works without it.
+     * Call it when a play is likely, such as when the pointer reaches a Play
+     * button. The earlier before the play, the more it saves.
+     */
+    warm(): Promise<void>;
     /** Frees the URL. Call it when the element showing it goes away. */
     release(): void;
 };
@@ -91,4 +144,4 @@ declare function openStreams<S extends Sdk | SharedSdk>(sdk: S, credentials: Cre
 /** Initialize the WASM module. Safe to call multiple times. */
 declare function initSia(): Promise<void>;
 
-export { type AppCredentials, type CredentialsFor, type FileOptions, type SharedCredentials, type StreamedFile, type StreamingOptions, type Streams, detectPrivateRelay, enableStreaming, initSia, openStreams };
+export { type AppCredentials, type CredentialsFor, type FileEvents, type FileOptions, type SharedCredentials, type StreamStatus, type StreamedFile, type StreamingOptions, type Streams, detectPrivateRelay, enableStreaming, initSia, openStreams };

package/dist/index.js

@@ -4,7 +4,7 @@ import {
   requestReply,
   streamErrorMessage,
   streamPath
-} from "./chunk-QYQQIWFH.js";
+} from "./chunk-YOMDUMYW.js";
 
 // src/index.ts
 import wasmInit from "../wasm/sia_storage_wasm.js";
@@ -31,26 +31,61 @@ async function checkPrivateRelay(userAgent, request) {
   }
 }
 
+// src/wasm.ts
+import { AppKey } from "../wasm/sia_storage_wasm.js";
+
 // src/stream/fallback.ts
 function chunks(stream) {
   return stream.getReader();
 }
-async function readBlob(sdk, object, type, onProgress, signal) {
-  const reader = chunks(sdk.download(object));
-  const onAbort = () => void reader.cancel();
+function notify(callback, value) {
+  if (!callback) return;
+  try {
+    callback(value);
+  } catch (error) {
+    reportError(error);
+  }
+}
+function download(sdk, object, events) {
+  const { onShard } = events;
+  return sdk.download(
+    object,
+    onShard ? { onShardDownloaded: (shard) => notify(onShard, shard) } : {}
+  );
+}
+function track({ onProgress, onStatus }) {
+  let received = 0;
+  let started = false;
+  notify(onStatus, "connecting");
+  return {
+    chunk(length) {
+      if (!started) notify(onStatus, "downloading");
+      started = true;
+      received += length;
+      notify(onProgress, received);
+    },
+    end() {
+      notify(onStatus, "idle");
+    }
+  };
+}
+async function readBlob(sdk, object, type, events, signal) {
+  const progress = track(events);
+  let reader;
+  const onAbort = () => void reader?.cancel();
   signal.addEventListener("abort", onAbort);
   const parts = [];
-  let bytesDownloaded = 0;
   try {
+    reader = chunks(download(sdk, object, events));
     while (true) {
       const { done, value } = await reader.read();
       if (done) break;
       parts.push(value);
-      bytesDownloaded += value.length;
-      onProgress(bytesDownloaded);
+      progress.chunk(value.length);
     }
   } finally {
     signal.removeEventListener("abort", onAbort);
+    progress.end();
   }
   signal.throwIfAborted();
   return new Blob(parts, type ? { type } : {});
@@ -63,14 +98,14 @@ function saveBlob(blob, name) {
   a.click();
   setTimeout(() => URL.revokeObjectURL(url), 0);
 }
-async function saveToDisk(sdk, object, name, type, onProgress) {
+async function saveToDisk(sdk, object, name, type, events) {
   const picker = window.showSaveFilePicker;
   if (!picker) {
     const blob = await readBlob(
       sdk,
       object,
       type,
-      onProgress,
+      events,
       new AbortController().signal
     );
     saveBlob(blob, name);
@@ -83,16 +118,19 @@ async function saveToDisk(sdk, object, name, type, onProgress) {
     if (e instanceof DOMException && e.name === "AbortError") return false;
     throw e;
   }
-  let bytesDownloaded = 0;
-  const progress = new TransformStream({
+  const file = await handle.createWritable();
+  const progress = track(events);
+  const counter = new TransformStream({
     transform(chunk, controller) {
-      bytesDownloaded += chunk.length;
-      onProgress(bytesDownloaded);
+      progress.chunk(chunk.length);
       controller.enqueue(chunk);
     }
   });
-  const file = await handle.createWritable();
-  await sdk.download(object).pipeThrough(progress).pipeTo(file);
+  try {
+    await download(sdk, object, events).pipeThrough(counter).pipeTo(file);
+  } finally {
+    progress.end();
+  }
   return true;
 }
 
@@ -181,12 +219,17 @@ function openStreams(sdk, credentials) {
         sdk,
         object,
         options.type,
-        options.onProgress ?? (() => {
-        }),
+        options,
         options.signal ?? new AbortController().signal
       );
       const url = URL.createObjectURL(blob);
-      return { url, blob, release: () => URL.revokeObjectURL(url) };
+      return {
+        url,
+        blob,
+        warm: async () => {
+        },
+        release: () => URL.revokeObjectURL(url)
+      };
     },
     async download(object, options) {
       const stream = streamUrl(handle, object, options);
@@ -202,8 +245,7 @@ function openStreams(sdk, credentials) {
         object,
         options.name,
         options.type,
-        options.onProgress ?? (() => {
-        })
+        options
       );
       return saved ? "saved" : "cancelled";
     },
@@ -226,17 +268,35 @@ function openedFor(sdk, credentials) {
       appKey: toHex(appKey.export()),
       appMeta
     };
-    return { session, connection, appKey };
+    return { session, connection, sealKey: appKey };
   }
   if (typeof indexerUrl !== "string" || typeof seed !== "string") {
     throw new TypeError("openStreams(SharedSdk) needs { indexerUrl, seed }.");
   }
-  return { session, connection: { kind: "shared", indexerUrl, seed } };
+  const sealing = randomSealKey();
+  return {
+    session,
+    connection: {
+      kind: "shared",
+      indexerUrl,
+      seed,
+      ...sealing && { sealKey: sealing.hex }
+    },
+    ...sealing && { sealKey: sealing.key }
+  };
+}
+function randomSealKey() {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  try {
+    return { key: new AppKey(bytes), hex: toHex(bytes) };
+  } catch {
+    return void 0;
+  }
 }
 function toHex(bytes) {
   return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
-function streamUrl(handle, object, { name, type, onError }) {
+function streamUrl(handle, object, { name, type, onError, onProgress, onShard, onStatus }) {
   if (!worker || !navigator.serviceWorker.controller || !opened.has(handle)) {
     return void 0;
   }
@@ -244,14 +304,26 @@ function streamUrl(handle, object, { name, type, onError }) {
   entries.set(token, {
     handle,
     objectId: object.id(),
-    sealed: handle.appKey && object.seal(handle.appKey),
+    sealed: handle.sealKey && object.seal(handle.sealKey),
     size: object.size(),
     name,
     mime: type || "application/octet-stream",
-    onError
+    onError,
+    events: { onProgress, onShard, onStatus },
+    received: 0
   });
+  const url = streamPath(worker.scope, worker.clientId, token);
   return {
-    url: streamPath(worker.scope, worker.clientId, token),
+    url,
+    async warm() {
+      try {
+        const response = await fetch(`${url}?warm=1`, {
+          headers: { Range: "bytes=0-0" }
+        });
+        await response.arrayBuffer();
+      } catch {
+      }
+    },
     release() {
       entries.delete(token);
       const message = { type: "sia-release", token };
@@ -264,6 +336,7 @@ function releaseStreams(handle) {
     if (entry.handle === handle) entries.delete(token);
   }
   if (!opened.delete(handle)) return;
+  handle.sealKey?.free();
   const message = {
     type: "sia-release-share",
     session: handle.session
@@ -280,10 +353,25 @@ function onWorkerMessage(event) {
     const range = offset !== void 0 && length !== void 0 ? { offset, length } : void 0;
     if (entry.onError) entry.onError(streamErrorMessage(data.message));
     else reportStreamError(data.message, entry.name, range);
+  } else if (data?.type === "sia-stream-status") {
+    notify(entries.get(data.token)?.events.onStatus, data.status);
+  } else if (data?.type === "sia-stream-progress") {
+    const entry = entries.get(data.token);
+    if (!entry || !Array.isArray(data.shards)) return;
+    const { onProgress, onShard } = entry.events;
+    for (const shard of data.shards) notify(onShard, shard);
+    if (Number.isSafeInteger(data.bytes) && data.bytes > 0) {
+      entry.received += data.bytes;
+      notify(onProgress, entry.received);
+    }
   } else if (data?.type === "sia-source") {
     const port = event.ports[0];
     if (!port) return;
     const entry = entries.get(data.token);
+    const events = [];
+    if (entry?.events.onStatus) events.push("status");
+    if (entry?.events.onProgress) events.push("progress");
+    if (entry?.events.onShard) events.push("shards");
     const reply = entry ? {
       type: "source",
       session: entry.handle.session,
@@ -292,7 +380,8 @@ function onWorkerMessage(event) {
       ...entry.sealed && { sealed: entry.sealed },
       size: entry.size,
       mime: entry.mime,
-      name: entry.name
+      name: entry.name,
+      ...events.length > 0 && { events }
     } : { type: "error" };
     port.postMessage(reply);
     port.close();
@@ -301,10 +390,11 @@ function onWorkerMessage(event) {
 
 // src/index.ts
 import {
-  AppKey,
+  AppKey as AppKey2,
   Builder,
   KeyRecord,
   ObjectEvent,
+  ObjectSummary,
   PackedUpload,
   PinnedObject,
   Sdk,
@@ -321,10 +411,11 @@ async function initSia() {
   await initPromise;
 }
 export {
-  AppKey,
+  AppKey2 as AppKey,
   Builder,
   KeyRecord,
   ObjectEvent,
+  ObjectSummary,
   PackedUpload,
   PinnedObject,
   Sdk,