@lat-murmeldjur/weeb_3 0.0.321001 → 0.0.323001

package/README.md

@@ -3,7 +3,7 @@
 `weeb-3` is a browser-side Swarm client built in Rust and compiled to WebAssembly.
 The main `weeb-3` project is the full released browser client, published at [lat-murmeldjur.github.io/weeb-3](https://lat-murmeldjur.github.io/weeb-3), where the client is used together with its own interface.
 
-This npm package is the library edition of that same client. Projects can use the API directly or mount the bundled browser interface with `renderInterface(container)`.
+This npm package is the library edition of that same client. Projects can use the API directly, attach Swarm HLS playback to their own media element, or mount the bundled browser interface with `renderInterface(container)`.
 
 Project repository: [github.com/lat-murmeldjur/weeb-3](https://github.com/lat-murmeldjur/weeb-3)
 
@@ -22,43 +22,29 @@ This package contains the browser-targeted WebAssembly build of the `weeb-3` cli
 The main exports are:
 
 - `Weeb3No103` as the higher-level client interface
-- `BootstrapNode` for defining bootstrap peers
-- `Weeb3` for lower-level direct access to the underlying client
 
 The higher-level `Weeb3No103` interface provides the main methods used by the embedding example:
 
 - `start(options?)`
-- `connect()`
 - `networkState()`
-- `switchMainnet()` / `switch_mainnet()`
-- `switchTestnet()` / `switch_testnet()`
-- `switchNetwork(mode)` / `switch_network(mode)`
-- `connectProfile(mode)` / `connect_profile(mode)`
+- `switchNetwork(mode)`
 - `retrieve(address)`
 - `upload(file, encryption, index_string, add_to_feed, feed_topic)`
 - `uploadWithRedundancy(file, encryption, redundancy_level, index_string, add_to_feed, feed_topic)`
 - `postUploadBytesWithRedundancy(bytes, mime, filename, encryption, redundancy_level, add_to_feed, feed_topic)`
-- `openStreamFeed(owner, topic)`
-- `playHlsStream(owner, topic, media_type, index?)`
-- `attachHlsStream(media, owner, topic, options)`
-- `detachHlsStream()`
-- `configureStreamingRoutes(service_worker_url, route_base)`
+- `attachStream(media, owner, topic, start)`
 - `renderInterface(container)`
 - `resetStamp()`
 - `postPushChunk(data, soc, chunk_address, stamp)`
 
 Sequence-feed indexes use Bee's fixed-width eight-byte big-endian encoding.
 
-## HLS streaming
-
-HLS playback is an optional dapp integration, not a Bee/Swarm standard. `playHlsStream(...)` displays a stream in the bundled interface after `renderInterface(container)`. For an application-owned `<video>` or `<audio>` element, call `attachHlsStream(media, owner, topic, { start: "beginning" })`; use `"current-window"` for a rolling/live presentation. Call `detachHlsStream()` before removing or replacing that element. The Service Worker must be copied from the package to a same-origin URL whose scope contains the page, then configured with `configureStreamingRoutes(...)`. Canonical mainnet links use `/stream/{owner}/{topic}[/{index}]`; testnet inserts `/testnet` before `/stream`.
-
 ## Basic usage
 
 Call `init()` once before creating a client instance so the WebAssembly module is loaded.
 
 ```js
-import init, { Weeb3No103, BootstrapNode } from "@lat-murmeldjur/weeb_3";
+import init, { Weeb3No103 } from "@lat-murmeldjur/weeb_3";
 
 await init();
 
@@ -69,17 +55,12 @@ weeb3node.start();
 console.log(await weeb3node.networkState());
 
 // Switch explicitly between built-in profiles.
-await weeb3node.switchTestnet();
-await weeb3node.switchMainnet();
-
-// Or use the generic form. Accepted values include:
-// "mainnet", "gnosis", "1", "testnet", "sepolia", and "10".
 await weeb3node.switchNetwork("testnet");
 await weeb3node.switchNetwork("mainnet");
 
 // You can still start with explicit browser-dialable bootnodes and network id.
 const BOOTSTRAP_NODES = [
-  new BootstrapNode("/ip4/example/tcp/443/wss/p2p/examplePeerId", true),
+  { multiaddr: "/ip4/example/tcp/443/wss/p2p/examplePeerId", usable: true },
 ];
 
 weeb3node.start({
@@ -91,41 +72,59 @@ weeb3node.start({
 weeb3node.start({ testnet: true });
 ```
 
+## Stream playback
+
+The application creates and owns the media element. `"beginning"` reconstructs the earliest available feed timeline, while `"live"` opens the current authenticated feed head and starts at the player's safe live-sync position. Calling `attachStream` again switches the same element between them.
+
+```js
+import init, { Weeb3No103 } from "@lat-murmeldjur/weeb_3";
+
+await init();
+
+const node = new Weeb3No103();
+const video = document.querySelector("video");
+const owner = "6F2728386F8a47ef5EBe323721188e630Ff0FdE9";
+const topic = "b347b89b-933c-424f-a3d1-403bdd270b25";
+
+node.start();
+await node.attachStream(video, owner, topic, "beginning");
+
+// Later, for example from the application's own Live button:
+await node.attachStream(video, owner, topic, "live");
+```
+
+Public HLS feeds use mainnet. The embedding page must be below the `/weeb-3/` scope and serve the packaged worker at `/weeb-3/service.js`, or already be controlled by a worker implementing the same forwarding protocol.
+
 ## Example corresponding to `example.html`
 
 This is a compact npm-import form of the same usage pattern shown in the project's `example.html`:
 
 ```js
-import init, { Weeb3No103, BootstrapNode } from "@lat-murmeldjur/weeb_3";
+import init, { Weeb3No103 } from "@lat-murmeldjur/weeb_3";
 
 await init();
 
 const weeb3node = new Weeb3No103();
 
-await weeb3node.switchMainnet();
+await weeb3node.switchNetwork("mainnet");
 
 const entries = await weeb3node.retrieve(
   "695fceb3a8c212cd123e2e40d86ec08b52fe4fe6ca46687ce9ea69b8f05471f6aa25b5d4d41bf78b1db3479c048fd5fd8137ba844604821b71786196306b68e7"
 );
 ```
 
-## Erasure-coding selector
+## Upload API
 
 Legacy upload methods use Bee's Medium level. Explicit upload levels are `0` None, `1` Medium, `2` Strong, `3` Insane, and `4` Paranoid. The generated TypeScript declaration exposes this as `UploadRedundancyLevel = 0 | 1 | 2 | 3 | 4`.
 
-`renderInterface(container)` includes a Medium-default erasure-coding dropdown. A custom interface can populate its own dropdown from the same canonical metadata:
+`renderInterface(container)` includes a Medium-default erasure-coding dropdown. A custom interface can pass the selected numeric level directly:
 
 ```js
-import init, {
-  Weeb3No103,
-  defaultUploadRedundancyLevel,
-  uploadRedundancyOptions,
-} from "@lat-murmeldjur/weeb_3";
+import init, { Weeb3No103 } from "@lat-murmeldjur/weeb_3";
 
 await init();
 const node = new Weeb3No103();
-const choices = uploadRedundancyOptions();
-const level = defaultUploadRedundancyLevel();
+const level = 1;
 
 const result = await node.uploadWithRedundancy(
   file,
@@ -142,6 +141,6 @@ Retrieval reads the level encoded in the Swarm tree and uses parity when data sh
 ## Notes
 
 - This package is meant for browser applications, not a plain Node.js runtime.
-- Use one active `Weeb3No103` node and HLS session per loaded Wasm module.
+- `attachStream` uses the same runtime, connection buildup, retrieval, prefetch, accounting, hls.js or native-HLS player, and recovery logic as the built-in interface.
 - The package does not publish the standalone site HTML, but `renderInterface(container)` embeds the same interface shell—including its erasure-coding selector—from the Wasm bundle.
 - The full released browser client remains available in the main project repository and on the project site.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@lat-murmeldjur/weeb_3",
   "type": "module",
   "description": "A Swarm client for browsers",
-  "version": "0.0.321001",
+  "version": "0.0.323001",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -42,9 +42,6 @@
       "types": "./weeb_3.d.ts",
       "import": "./weeb_3.js",
       "default": "./weeb_3.js"
-    },
-    "./service.js": {
-      "default": "./service.js"
     }
   },
   "dependencies": {

package/service.js

@@ -6,13 +6,11 @@ const NETWORK_ROUTE_PREFIXES = ["", "mainnet/", "testnet/"];
 const RAW_ROUTE_KINDS = [
   ["hls/bytes", "hls-bytes"],
   ["bytes", "bytes"],
-  ["chunks", "chunk"],
-  ["chunk", "chunk"]
+  ["chunks", "chunk"]
 ];
 const FETCH_TIMEOUT_MS = 240000;
 const SERVICE_WORKER_MARKER = "forwarder-default20";
 const SERVICE_WORKER_PROTOCOL = 5;
-const DEBUG_SERVICE_WORKER = false;
 const MIB_BYTES = 1024 * 1024;
 const STREAM_STORAGE_WINDOW_BYTES = MIB_BYTES / 2;
 const STREAM_LOOKAHEAD_CHUNKS = 8;
@@ -22,12 +20,6 @@ const CLIENT_RUNTIME_PROBE_TIMEOUT_MS = 1_500;
 
 console.log(`weeb-3 service worker start ${SERVICE_WORKER_MARKER}`);
 
-function debugLog(...args) {
-  if (DEBUG_SERVICE_WORKER) {
-    console.log(...args);
-  }
-}
-
 function logServiceWorkerVersion(reason) {
   console.log(`weeb-3 service worker ${reason} ${SERVICE_WORKER_MARKER}`);
 }
@@ -79,32 +71,17 @@ function isCanonicalStreamTopic(value) {
   }
 }
 
-function isCanonicalStreamIndex(value) {
-  if (value === undefined) {
-    return true;
-  }
-  return /^[0-9]+$/.test(value) && BigInt(value) <= 18446744073709551615n;
-}
-
 function isDirectShareShellPath(pathname) {
   if (!pathname.startsWith(SCOPE_PATH)) {
     return false;
   }
 
   const parts = pathname.substring(SCOPE_PATH.length).split("/");
-  if (parts[0] === "testnet") {
-    parts.shift();
-  }
-
-  const kind = parts.shift();
-  if (kind !== "stream") {
-    return false;
-  }
-
-  return (parts.length === 2 || parts.length === 3) &&
-    /^(?:0[xX])?[a-fA-F0-9]{40}$/.test(parts[0] || "") &&
-    isCanonicalStreamTopic(parts[1]) &&
-    isCanonicalStreamIndex(parts[2]);
+  const streamOffset = parts[0] === "live" ? 1 : 0;
+  return parts.length === streamOffset + 3 &&
+    parts[streamOffset] === "stream" &&
+    /^[a-fA-F0-9]{40}$/.test(parts[streamOffset + 1]) &&
+    isCanonicalStreamTopic(parts[streamOffset + 2]);
 }
 
 function isBzzUploadPath(pathname) {
@@ -138,21 +115,26 @@ function canonicalBzzResource(url) {
 }
 
 function canonicalRawResource(url) {
-  for (const [marker] of rawRouteMarkers()) {
+  for (const [marker, rawType] of rawRouteMarkers()) {
     if (!url.pathname.startsWith(marker)) {
       continue;
     }
 
-    const resource = url.pathname.substring(marker.length);
-    if (!resource) {
+    const encodedResource = url.pathname.substring(marker.length);
+    if (!encodedResource) {
       return null;
     }
 
+    let resource;
     try {
-      return decodeURIComponent(resource);
+      resource = decodeURIComponent(encodedResource);
     } catch (_) {
-      return resource;
+      resource = encodedResource;
     }
+    if (rawType === "hls-bytes" && !isSwarmReference(resource)) {
+      return null;
+    }
+    return resource;
   }
 
   return null;
@@ -180,15 +162,6 @@ function canonicalFeedResource(url) {
   return null;
 }
 
-function isCanonicalRequest(request) {
-  try {
-    const url = new URL(request.url);
-    return canonicalBzzResource(url) !== null || canonicalRawResource(url) !== null;
-  } catch (_) {
-    return false;
-  }
-}
-
 function isAppShellNavigation(request) {
   const headerDestination = request.headers.get("Sec-Fetch-Dest") || "";
   return request.method === "GET" &&
@@ -295,9 +268,6 @@ self.addEventListener("fetch", (event) => {
     return;
   }
 
-  // This worker is safe to mount in an npm application: requests outside the
-  // explicit weeb-3 routes remain entirely under the host app/browser's
-  // normal fetch and caching policy.
 });
 
 function clientInScope(client) {
@@ -382,10 +352,7 @@ async function firstReadyClient(candidates, requiredNetworkId) {
     return [];
   }
 
-  // Start the cheap liveness/network probes together so stale tabs add at
-  // most one probe timeout. Preserve the originating client's fast path and
-  // candidate priority; the accounting-sensitive operation itself is still
-  // sent exactly once by messageFirstClient.
+  // Probe candidates concurrently without redispatching work.
   const probes = candidates.map((candidate) => clientWeeb3NetworkId(candidate));
   if (await probes[0] === requiredNetworkId) {
     return [candidates[0]];
@@ -413,12 +380,7 @@ async function requestClients(event, requestUrl, requiredNetworkId) {
     )
   );
 
-  // HLS fetches originate in the top-level page that attached the shared Rust
-  // player, whether that page is the bundled shell or an arbitrary npm host.
-  // Dispatch those directly: the Rust bridge validates networkId before
-  // retrieval, while a redundant liveness round-trip here can false-timeout
-  // when a large WASM retrieval wave briefly occupies the browser thread.
-  // Nested clients retain the probed fallback below.
+  // Direct top-level HLS requests skip the redundant liveness probe.
   if (
     directHlsRequest &&
     eventClient &&
@@ -436,9 +398,6 @@ async function requestClients(event, requestUrl, requiredNetworkId) {
   const seen = new Set();
   const requestReference = requestUrlObject ? bzzReferenceFromUrl(requestUrlObject) : "";
 
-  // Prefer the top-level context that originated the request. A nested BZZ
-  // site frame does not host the Rust runtime and must fall through to its
-  // active app-shell tab below.
   if (eventClient && isTopLevelClient(eventClient) && clientInScope(eventClient)) {
     pushUniqueClient(candidates, seen, eventClient);
   }
@@ -532,10 +491,7 @@ function messageFirstClient(clients, message, timeoutMs = FETCH_TIMEOUT_MS) {
     });
   }
 
-  // Uploads and canonical retrievals can enter postage/accounting state. Send
-  // each request exactly once. A timeout merely detaches this response port;
-  // already-dispatched work is deliberately left to drain and is never replayed
-  // through another tab.
+  // Timeouts detach the port; dispatched accounting work is never replayed.
   return messageClient(clients[0], message, timeoutMs);
 }
 
@@ -638,16 +594,6 @@ function toUint8Array(body) {
   return new Uint8Array();
 }
 
-function oneChunkResponseBody(body) {
-  const bytes = toUint8Array(body);
-  return new ReadableStream({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
-    }
-  });
-}
-
 function responseHeaders(headerRows) {
   const headers = new Headers();
   for (const row of headerRows || []) {
@@ -774,7 +720,7 @@ async function forwardRequestToRust(request, event) {
     return new Response(
       request.method === "HEAD" || status === 304
         ? null
-        : oneChunkResponseBody(response.body),
+        : toUint8Array(response.body),
       {
         status,
         headers
@@ -788,12 +734,9 @@ async function forwardRequestToRust(request, event) {
 }
 
 function parseUploadRedundancyHeader(value) {
-  // Bee marks this header `omitempty`, so a present empty value has the same
-  // Medium default as an omitted header.
   if (value === null || value === "") {
     return 1;
   }
-  // Bee parses an unsigned base-10 header, so reject Number()-only forms such as hex or exponents.
   if (!/^[0-9]+$/.test(value)) {
     return null;
   }

package/snippets/weeb_3-03f860286800ffdb/static/hls_loader.js

@@ -1,5 +1,3 @@
-// Dynamic `import()` has no CSP-safe Web API callable directly from Wasm.
-// Keep this irreducible bridge tiny; player policy and lifecycle live in Rust.
 export async function loadHls() {
   const module = await import("hls.js");
   return module.default ?? module.Hls;