javascript-solid-server 0.0.162 → 0.0.163

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.162",
+  "version": "0.0.163",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",

package/src/mashlib/index.js

@@ -74,6 +74,177 @@ function dataIsland(resourceUrl, jsonLdString) {
   return `<script type="application/ld+json" id="dataisland" data-uri="${safeUri}">${safeBody}</script>`;
 }
 
+/**
+ * Inline round-trip optimization reader (#346).
+ *
+ * Exposes a generic `window.__dataIsland.get(uri)` accessor any client
+ * can use, plus a compatibility patch for rdflib-based clients
+ * (mashlib and friends) that intercepts `fetcher.load(uri)` and
+ * resolves from the inline JSON-LD data island instead of issuing a
+ * second HTTP request. Falls through cleanly to the original network
+ * fetch on any miss, parse error, or absent rdflib.
+ *
+ * Three detection paths to cover the timing space:
+ *   1. Synchronous check — if `$rdf` is already on the page when this
+ *      script runs (e.g. reader injected after mashlib in some custom
+ *      flow), patch immediately.
+ *   2. Setter on `window.$rdf` — catches the assignment as soon as
+ *      mashlib publishes its rdflib instance. Closes the race where
+ *      mashlib's bundle initializes and calls `panes.runDataBrowser()`
+ *      synchronously inside an `onload` handler before any setTimeout
+ *      poll could fire.
+ *   3. Polling fallback — bounded retry for environments where the
+ *      property setter is rejected (e.g. `$rdf` already defined as a
+ *      non-configurable own property).
+ *
+ * Net effect: when JSS serves an HTML wrapper with an embedded data
+ * island, the page renders with one HTTP round-trip instead of two.
+ */
+export function roundTripOptimizationScript() {
+  return `<script>
+(function () {
+  if (typeof window === 'undefined') return;
+
+  // Initialize defensively: another script may have set a truthy
+  // window.__dataIsland that lacks a .get function — or, worse,
+  // assigned a primitive (string, number, etc.) where attaching
+  // .get would silently fail in non-strict mode and throw in strict
+  // mode. Normalize to a plain object first if the existing value
+  // is not an object or function (this also handles a null value,
+  // since typeof null === 'object'). Preserve well-formed existing
+  // implementations so consumers can register custom .get hooks.
+  var di = window.__dataIsland;
+  if (di === null || di === undefined
+      || (typeof di !== 'object' && typeof di !== 'function')) {
+    di = window.__dataIsland = {};
+  }
+  if (typeof di.get !== 'function') {
+    di.get = function (uri) {
+      if (!uri) return null;
+      try {
+        // Fetch by id and compare data-uri as a string. Avoids
+        // selector construction entirely so there is no CSS.escape
+        // pitfall, no attribute-string-context injection surface,
+        // and no false misses on URIs containing characters older
+        // browsers' selector parsers handle inconsistently.
+        var el = document.getElementById('dataisland');
+        if (el && el.type === 'application/ld+json'
+            && el.getAttribute('data-uri') === String(uri)) {
+          return {
+            contentType: 'application/ld+json',
+            content: el.textContent
+          };
+        }
+      } catch (e) { /* fall through to null */ }
+      return null;
+    };
+  }
+
+  function applyPatch(rdf) {
+    if (!rdf || !rdf.fetcher || !rdf.fetcher.load) return;
+    if (rdf.fetcher.__dataIslandPatched) return;
+    rdf.fetcher.__dataIslandPatched = true;
+    var f = rdf.fetcher;
+    var orig = f.load.bind(f);
+    f.load = function (uri, options) {
+      var s = (uri && uri.uri) || (uri && uri.value) || String(uri);
+      var d = window.__dataIsland.get(s);
+      if (d) {
+        return new Promise(function (resolve, reject) {
+          rdf.parse(d.content, f.store, s, d.contentType, function (err) {
+            if (err) {
+              reject(err);
+              return;
+            }
+            // Wrap the success path so unexpected throws (e.g.
+            // f.requested missing/non-writable on some rdflib builds)
+            // surface as Promise rejections rather than hanging the
+            // resolution.
+            try {
+              if (f.requested && typeof f.requested === 'object') {
+                f.requested[s] = 'done';
+              }
+              // Return a real Response when available so consumers
+              // using "instanceof Response", ".text()", ".json()",
+              // etc. work the same as on the network path. Fall
+              // back to a Response-shaped plain object in environments
+              // where the Response constructor isn't available.
+              var resp;
+              if (typeof Response === 'function') {
+                resp = new Response(d.content, {
+                  status: 200,
+                  statusText: 'OK',
+                  headers: { 'content-type': d.contentType }
+                });
+                // Response.url is read-only and empty when
+                // constructed; consumers reading it expect the
+                // resource URL. defineProperty is supported on
+                // Response in all browsers we target.
+                try {
+                  Object.defineProperty(resp, 'url',
+                    { value: s, configurable: true });
+                } catch (urlErr) { /* leave url empty */ }
+              } else {
+                resp = {
+                  ok: true,
+                  status: 200,
+                  statusText: 'OK',
+                  url: s,
+                  headers: {
+                    // Match real Response.headers.get() behavior on
+                    // the inline-data path: case-insensitive lookup,
+                    // returns the data island's content-type for
+                    // 'content-type', null for unknown headers.
+                    get: function (name) {
+                      if (typeof name !== 'string') return null;
+                      if (name.toLowerCase() === 'content-type') {
+                        return d.contentType;
+                      }
+                      return null;
+                    }
+                  }
+                };
+              }
+              resolve(resp);
+            } catch (callbackErr) {
+              reject(callbackErr);
+            }
+          });
+        }).catch(function () { return orig(uri, options); });
+      }
+      return orig(uri, options);
+    };
+  }
+
+  // Path 1: synchronous check
+  if (typeof $rdf !== 'undefined') applyPatch($rdf);
+
+  // Path 2: setter for $rdf — catches synchronous mashlib initialization
+  try {
+    var captured = (typeof $rdf !== 'undefined') ? $rdf : undefined;
+    Object.defineProperty(window, '$rdf', {
+      configurable: true,
+      get: function () { return captured; },
+      set: function (v) { captured = v; applyPatch(v); }
+    });
+  } catch (e) {
+    /* property non-configurable or otherwise un-redefinable;
+       the polling fallback below covers this case */
+  }
+
+  // Path 3: polling fallback
+  var n = 0;
+  (function poll() {
+    if (++n > 100) return;
+    if (typeof $rdf !== 'undefined' && $rdf && $rdf.fetcher
+        && $rdf.fetcher.__dataIslandPatched) return;
+    if (typeof $rdf !== 'undefined') applyPatch($rdf);
+    setTimeout(poll, 100);
+  })();
+})();
+</script>`;
+}
+
 /**
  * Generate Mashlib databrowser HTML
  *
@@ -84,17 +255,23 @@ function dataIsland(resourceUrl, jsonLdString) {
  *   as a `<script type="application/ld+json">` data island. Accepts a
  *   UTF-8 string or a Buffer (coerced via `String()`). Honors a 256 KB
  *   size cap; oversize payloads are silently dropped. Phase 1 of #7.
+ * @param {boolean} [opts.roundTripOptimization=true] - Inline a small
+ *   reader script that lets rdflib-based clients (mashlib and friends)
+ *   resolve `fetcher.load(uri)` from the data island instead of issuing
+ *   a second HTTP request. Falls through to network fetch on any miss
+ *   or parse error. #346.
  * @returns {string} HTML content
  */
 export function generateDatabrowserHtml(resourceUrl, cdnVersion = null, opts = {}) {
   const island = dataIsland(resourceUrl, opts.embedJsonLd);
+  const reader = opts.roundTripOptimization === false ? '' : roundTripOptimizationScript();
   if (cdnVersion) {
     // CDN mode - use script.onload to ensure mashlib is fully loaded before init
     // This avoids race conditions with defer + DOMContentLoaded
     const cdnBase = `https://unpkg.com/mashlib@${cdnVersion}/dist`;
     return `<!doctype html><html><head><meta charset="utf-8"/><title>SolidOS Web App</title>
 <link href="${cdnBase}/mash.css" rel="stylesheet"></head>
-<body id="PageBody">${island}<header id="PageHeader"></header>
+<body id="PageBody">${island}${reader}<header id="PageHeader"></header>
 <div class="TabulatorOutline" id="DummyUUID" role="main"><table id="outline"></table><div id="GlobalDashboard"></div></div>
 <footer id="PageFooter"></footer>
 <script>
@@ -111,7 +288,7 @@ export function generateDatabrowserHtml(resourceUrl, cdnVersion = null, opts = {
   // Local mode - use defer (reliable when served locally)
   return `<!doctype html><html><head><meta charset="utf-8"/><title>SolidOS Web App</title><script>document.addEventListener('DOMContentLoaded', function() {
         panes.runDataBrowser()
-      })</script><script defer="defer" src="/mashlib.min.js"></script><link href="/mash.css" rel="stylesheet"></head><body id="PageBody">${island}<header id="PageHeader"></header><div class="TabulatorOutline" id="DummyUUID" role="main"><table id="outline"></table><div id="GlobalDashboard"></div></div><footer id="PageFooter"></footer></body></html>`;
+      })</script><script defer="defer" src="/mashlib.min.js"></script><link href="/mash.css" rel="stylesheet"></head><body id="PageBody">${island}${reader}<header id="PageHeader"></header><div class="TabulatorOutline" id="DummyUUID" role="main"><table id="outline"></table><div id="GlobalDashboard"></div></div><footer id="PageFooter"></footer></body></html>`;
 }
 
 /**
@@ -122,16 +299,19 @@ export function generateDatabrowserHtml(resourceUrl, cdnVersion = null, opts = {
  * @param {object} [opts]
  * @param {string|Buffer} [opts.embedJsonLd] - JSON-LD body for the
  *   data island, same contract as `generateDatabrowserHtml`. Phase 1 of #7.
+ * @param {boolean} [opts.roundTripOptimization=true] - Inline reader
+ *   script (#346); see `generateDatabrowserHtml` for details.
  * @returns {string} HTML content
  */
 export function generateModuleDatabrowserHtml(moduleUrl, resourceUrl = '', opts = {}) {
   const cssUrl = moduleUrl.replace(/\.js$/, '.css');
   const island = dataIsland(resourceUrl, opts.embedJsonLd);
+  const reader = opts.roundTripOptimization === false ? '' : roundTripOptimizationScript();
   return `<!doctype html><html lang="en"><head><meta charset="utf-8"/>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Solid Data Browser</title>
 <link rel="stylesheet" href="${cssUrl}"></head>
-<body>${island}<div id="mashlib"></div>
+<body>${island}${reader}<div id="mashlib"></div>
 <script type="module" src="${moduleUrl}"></script>
 </body></html>`;
 }

package/test/round-trip-optimization.test.js

@@ -0,0 +1,638 @@
+/**
+ * Tests for the round-trip optimization reader (#346).
+ *
+ * The reader is a small inline `<script>` that exposes
+ * `window.__dataIsland.get(uri)` and (when rdflib loads) patches
+ * `$rdf.fetcher.load()` to resolve from the inline JSON-LD data island
+ * instead of issuing a second HTTP request. These tests pin:
+ *   - presence in CDN, local, and module HTML wrappers when enabled by default
+ *   - opt-out via `roundTripOptimization: false`
+ *   - reader exposes the documented accessor
+ *   - reader contains the bounded-retry guard (no infinite polling)
+ *   - reader body is well-formed JS (no premature `</script>` close)
+ *   - runtime behavior of the accessor and the rdflib patch (via Node `vm`)
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import vm from 'node:vm';
+import {
+  generateDatabrowserHtml,
+  generateModuleDatabrowserHtml,
+  roundTripOptimizationScript
+} from '../src/mashlib/index.js';
+
+describe('round-trip optimization reader — emission (#346)', () => {
+  it('emits the reader script in CDN mode by default', () => {
+    const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0');
+    assert.match(html, /window\.__dataIsland/);
+    assert.match(html, /\$rdf\.fetcher/);
+  });
+
+  it('emits the reader script in local mode by default', () => {
+    const html = generateDatabrowserHtml('https://x.test/foo');
+    assert.match(html, /window\.__dataIsland/);
+    assert.match(html, /\$rdf\.fetcher/);
+  });
+
+  it('emits the reader script in module mode by default', () => {
+    const html = generateModuleDatabrowserHtml(
+      '/dist/databrowser.js',
+      'https://x.test/foo'
+    );
+    assert.match(html, /window\.__dataIsland/);
+    assert.match(html, /\$rdf\.fetcher/);
+  });
+
+  it('omits the reader when roundTripOptimization is explicitly false (CDN)', () => {
+    const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0', {
+      roundTripOptimization: false
+    });
+    assert.doesNotMatch(html, /window\.__dataIsland/);
+  });
+
+  it('omits the reader when roundTripOptimization is explicitly false (local)', () => {
+    const html = generateDatabrowserHtml('https://x.test/foo', null, {
+      roundTripOptimization: false
+    });
+    assert.doesNotMatch(html, /window\.__dataIsland/);
+  });
+
+  it('omits the reader when roundTripOptimization is explicitly false (module)', () => {
+    const html = generateModuleDatabrowserHtml(
+      '/dist/databrowser.js',
+      'https://x.test/foo',
+      { roundTripOptimization: false }
+    );
+    assert.doesNotMatch(html, /window\.__dataIsland/);
+  });
+
+  it('exposes the documented public surface (window.__dataIsland with .get)', () => {
+    // Public-surface assertion only — minified formatting is not pinned.
+    // Runtime behavior is exercised in the vm-based suite below.
+    const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0');
+    assert.match(html, /window\.__dataIsland/);
+    assert.match(html, /\.get\s*[:=(]/);
+  });
+
+  it('looks up the data island by id and compares data-uri', () => {
+    // Avoiding selector construction sidesteps CSS.escape pitfalls and
+    // selector-injection surface in older browsers.
+    const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0');
+    assert.match(html, /document\.getElementById\(\s*['"]dataisland['"]\s*\)/);
+    assert.match(html, /getAttribute\(\s*['"]data-uri['"]\s*\)/);
+  });
+
+  it('marks the fetcher as patched to prevent double-patching', () => {
+    const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0');
+    assert.match(html, /__dataIslandPatched/);
+  });
+
+  it('bounds the polling retry to prevent infinite loop on non-rdflib clients', () => {
+    const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0');
+    // Polling guard caps total retries (whitespace-tolerant).
+    // Actual runtime behavior is exercised in the vm-based suite below.
+    assert.match(html, /\+\+\s*n\s*>\s*\d+/);
+  });
+
+  it('captures original fetcher.load before patching', () => {
+    const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0');
+    // Public-surface assertion (whitespace-tolerant).
+    // Runtime fall-through is exercised in the vm-based suite below.
+    assert.match(html, /orig\s*=\s*f\.load\.bind\(f\)/);
+  });
+
+  it('reader contains exactly one </script> close tag (no premature close)', () => {
+    // Test the source string directly (not a slice of the emitted HTML)
+    // so a premature `</script>` cannot be silently treated as the
+    // terminator. A correct reader has exactly one `</script>`: its own
+    // closing tag.
+    const wrapped = roundTripOptimizationScript();
+    const closes = (wrapped.match(/<\/script\s*>/gi) || []).length;
+    assert.strictEqual(closes, 1,
+      'reader must have exactly one </script> close tag, got ' + closes);
+    // Sanity: the close is at the very end (modulo trailing whitespace).
+    assert.match(wrapped, /<\/script>\s*$/);
+  });
+});
+
+describe('round-trip optimization reader — interaction with data island (#346)', () => {
+  it('reader and data island both present when JSON-LD payload supplied', () => {
+    const html = generateDatabrowserHtml(
+      'https://test.solid.social/profile/card.jsonld',
+      '2.0.0',
+      { embedJsonLd: '{"@id":"#me","foaf:name":"Alice"}' }
+    );
+    assert.match(html, /id="dataisland"/);
+    assert.match(html, /window\.__dataIsland/);
+  });
+
+  it('reader still present when data island is absent (no payload)', () => {
+    const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0');
+    assert.doesNotMatch(html, /id="dataisland"/);
+    // Reader is still emitted; it just no-ops on missing islands
+    assert.match(html, /window\.__dataIsland/);
+  });
+
+  it('data island appears before reader script in document order', () => {
+    const html = generateDatabrowserHtml(
+      'https://x.test/foo',
+      '2.0.0',
+      { embedJsonLd: '{"@id":"#me"}' }
+    );
+    const islandPos = html.indexOf('id="dataisland"');
+    const readerPos = html.indexOf('window.__dataIsland');
+    assert.ok(islandPos > 0, 'data island missing');
+    assert.ok(readerPos > 0, 'reader missing');
+    assert.ok(islandPos < readerPos,
+      'data island must appear before reader so the DOM element exists when reader queries it');
+  });
+});
+
+/**
+ * Helpers for the runtime suite: extract the reader IIFE from generated
+ * HTML and evaluate it in a Node `vm` context with stubbed window /
+ * document / $rdf so we can pin actual behavior, not just emitted
+ * tokens.
+ */
+function extractReaderSource(html) {
+  // The reader IIFE begins with `(function () {` followed by the
+  // `if (typeof window` guard. Locate that signature, then walk back
+  // to the enclosing <script> open and forward to the closing </script>.
+  const sigMatch = html.match(/\(function \(\)\s*\{\s*if \(typeof window/);
+  if (!sigMatch) throw new Error('reader IIFE not found in HTML');
+  const start = sigMatch.index;
+  const scriptOpen = html.lastIndexOf('<script>', start);
+  const scriptClose = html.indexOf('</script>', start);
+  return html.slice(scriptOpen + '<script>'.length, scriptClose);
+}
+
+function makeContext({ islands = {}, $rdf = undefined } = {}) {
+  // Single data island per page (matches the real DOM contract). The
+  // accessor uses getElementById('dataisland'), so we expose at most
+  // one element regardless of how many entries the test passes in.
+  const islandEntries = Object.entries(islands);
+  const islandEl = islandEntries.length > 0
+    ? {
+        type: 'application/ld+json',
+        textContent: islandEntries[0][1],
+        getAttribute(name) {
+          return name === 'data-uri' ? islandEntries[0][0] : null;
+        }
+      }
+    : null;
+  const document = {
+    getElementById(id) {
+      return id === 'dataisland' ? islandEl : null;
+    }
+  };
+  const window = {};
+  // Stub setTimeout so the reader's polling fallback (up to ~10s of
+  // 100ms ticks when $rdf is absent) does not register real Node
+  // timers that keep the test process alive past the assertions.
+  // Tests that need to exercise polling can build a custom context.
+  return vm.createContext({
+    window, document, $rdf,
+    setTimeout: () => 0,
+    clearTimeout: () => {},
+    Promise, String, console, Response,
+    Object: globalThis.Object
+  });
+}
+
+describe('round-trip optimization reader — runtime behavior (#346)', () => {
+  const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0');
+
+  it('window.__dataIsland.get returns {contentType, content} for matching island', () => {
+    const ctx = makeContext({
+      islands: { 'https://x.test/foo': '{"@id":"#me"}' }
+    });
+    vm.runInContext(extractReaderSource(html), ctx);
+    const result = ctx.window.__dataIsland.get('https://x.test/foo');
+    // Compare by value: result is constructed in the vm realm so its
+    // prototype is not reference-equal to the host realm's Object.
+    assert.strictEqual(result.contentType, 'application/ld+json');
+    assert.strictEqual(result.content, '{"@id":"#me"}');
+  });
+
+  it('window.__dataIsland.get returns null when no matching island exists', () => {
+    const ctx = makeContext({ islands: {} });
+    vm.runInContext(extractReaderSource(html), ctx);
+    assert.strictEqual(
+      ctx.window.__dataIsland.get('https://x.test/missing'),
+      null
+    );
+  });
+
+  it('window.__dataIsland.get returns null for falsy uri input', () => {
+    const ctx = makeContext({ islands: {} });
+    vm.runInContext(extractReaderSource(html), ctx);
+    assert.strictEqual(ctx.window.__dataIsland.get(null), null);
+    assert.strictEqual(ctx.window.__dataIsland.get(undefined), null);
+    assert.strictEqual(ctx.window.__dataIsland.get(''), null);
+  });
+
+  it('patches $rdf.fetcher.load synchronously when rdflib is already present', () => {
+    const fakeFetcher = {
+      requested: {},
+      store: {},
+      load: async () => 'original'
+    };
+    const $rdf = { fetcher: fakeFetcher, parse: () => {}, sym: (u) => u };
+    const ctx = makeContext({ islands: {}, $rdf });
+    vm.runInContext(extractReaderSource(html), ctx);
+    assert.strictEqual(fakeFetcher.__dataIslandPatched, true,
+      'fetcher should be marked patched');
+  });
+
+  it('patched fetcher.load resolves from data island instead of network', async () => {
+    let networkCalls = 0;
+    const parseCalls = [];
+    const fakeFetcher = {
+      requested: {},
+      store: { kb: 'fake' },
+      load: async () => { networkCalls++; return 'network'; }
+    };
+    const $rdf = {
+      fetcher: fakeFetcher,
+      parse(content, store, uri, contentType, callback) {
+        parseCalls.push({ content, uri, contentType });
+        callback(null);
+      },
+      sym: (u) => ({ uri: u })
+    };
+    const ctx = makeContext({
+      islands: { 'https://x.test/foo': '{"@id":"#me"}' },
+      $rdf
+    });
+    vm.runInContext(extractReaderSource(html), ctx);
+
+    const result = await fakeFetcher.load('https://x.test/foo', {});
+
+    assert.strictEqual(networkCalls, 0, 'should not have hit network');
+    assert.strictEqual(parseCalls.length, 1, '$rdf.parse called once');
+    assert.strictEqual(parseCalls[0].content, '{"@id":"#me"}');
+    assert.strictEqual(parseCalls[0].uri, 'https://x.test/foo');
+    assert.strictEqual(parseCalls[0].contentType, 'application/ld+json');
+    assert.strictEqual(fakeFetcher.requested['https://x.test/foo'], 'done');
+
+    // Return value is a real Response (or Response-shaped fallback) so
+    // consumers using `instanceof Response` or `.text()` / `.json()`
+    // see the same kind of object as on the network path.
+    assert.strictEqual(result.ok, true);
+    assert.strictEqual(result.status, 200);
+    assert.strictEqual(result.url, 'https://x.test/foo');
+    assert.strictEqual(typeof result.headers.get, 'function');
+    // Content-type header round-trips through the Response init.
+    assert.strictEqual(result.headers.get('content-type'), 'application/ld+json');
+  });
+
+  it('patched fetcher.load falls through to original on data island miss', async () => {
+    let networkCalls = [];
+    const fakeFetcher = {
+      requested: {},
+      store: {},
+      load: async function (uri, options) {
+        networkCalls.push({ uri, options });
+        return { source: 'network', uri };
+      }
+    };
+    const $rdf = {
+      fetcher: fakeFetcher,
+      parse: () => {},
+      sym: (u) => u
+    };
+    const ctx = makeContext({ islands: {}, $rdf });
+    vm.runInContext(extractReaderSource(html), ctx);
+
+    const result = await fakeFetcher.load('https://x.test/foo', { force: true });
+
+    assert.strictEqual(networkCalls.length, 1);
+    assert.strictEqual(networkCalls[0].uri, 'https://x.test/foo');
+    assert.deepStrictEqual(networkCalls[0].options, { force: true });
+    assert.deepStrictEqual(result, {
+      source: 'network',
+      uri: 'https://x.test/foo'
+    });
+  });
+
+  it('patched fetcher.load falls through to original on parse error', async () => {
+    let networkCalls = 0;
+    const fakeFetcher = {
+      requested: {},
+      store: {},
+      load: async () => { networkCalls++; return 'network'; }
+    };
+    const $rdf = {
+      fetcher: fakeFetcher,
+      parse(content, store, uri, contentType, callback) {
+        callback(new Error('parse failed'));
+      },
+      sym: (u) => u
+    };
+    const ctx = makeContext({
+      islands: { 'https://x.test/foo': 'not valid json-ld' },
+      $rdf
+    });
+    vm.runInContext(extractReaderSource(html), ctx);
+
+    const result = await fakeFetcher.load('https://x.test/foo', {});
+
+    assert.strictEqual(networkCalls, 1, 'should have fallen through to network');
+    assert.strictEqual(result, 'network');
+  });
+
+  it('rdflib patch is idempotent (running reader twice does not double-wrap)', () => {
+    const fakeFetcher = {
+      requested: {},
+      store: {},
+      load: async () => 'original'
+    };
+    const $rdf = { fetcher: fakeFetcher, parse: () => {}, sym: (u) => u };
+    const ctx = makeContext({ islands: {}, $rdf });
+
+    vm.runInContext(extractReaderSource(html), ctx);
+    const firstPatchedLoad = fakeFetcher.load;
+
+    // Second run — must detect __dataIslandPatched and skip
+    vm.runInContext(extractReaderSource(html), ctx);
+
+    assert.strictEqual(fakeFetcher.load, firstPatchedLoad,
+      'second run should not re-wrap an already-patched fetcher');
+  });
+
+  it('does nothing when rdflib never loads (bounded retry exits silently)', () => {
+    const ctx = makeContext({ islands: {} /* no $rdf */ });
+    // Should not throw despite $rdf being undefined.
+    assert.doesNotThrow(() => {
+      vm.runInContext(extractReaderSource(html), ctx);
+    });
+    // Generic accessor still set up.
+    assert.strictEqual(typeof ctx.window.__dataIsland.get, 'function');
+  });
+
+  it('installs a setter on window.$rdf to catch synchronous mashlib init', () => {
+    // The setter closes the race where mashlib's bundle initializes and
+    // calls panes.runDataBrowser() (and hence fetcher.load) synchronously
+    // inside an onload handler — faster than any setTimeout poll could fire.
+    const ctx = makeContext({ islands: {} /* no $rdf yet */ });
+    vm.runInContext(extractReaderSource(html), ctx);
+    const desc = Object.getOwnPropertyDescriptor(ctx.window, '$rdf');
+    assert.ok(desc, 'setter descriptor missing on window.$rdf');
+    assert.strictEqual(typeof desc.get, 'function', 'getter should be installed');
+    assert.strictEqual(typeof desc.set, 'function', 'setter should be installed');
+  });
+
+  it('setter on window.$rdf patches fetcher immediately on assignment', () => {
+    const fakeFetcher = {
+      requested: {},
+      store: {},
+      load: async () => 'original'
+    };
+    const fakeRdf = { fetcher: fakeFetcher, parse: () => {}, sym: (u) => u };
+    const ctx = makeContext({ islands: {} /* $rdf not yet set */ });
+    vm.runInContext(extractReaderSource(html), ctx);
+    // Simulate mashlib publishing its rdflib instance.
+    ctx.window.$rdf = fakeRdf;
+    assert.strictEqual(fakeFetcher.__dataIslandPatched, true,
+      'fetcher should be patched the moment $rdf is assigned');
+  });
+
+  it('returns a real Response when the constructor is available', async () => {
+    const fakeFetcher = {
+      requested: {},
+      store: {},
+      load: async () => 'orig'
+    };
+    const $rdf = {
+      fetcher: fakeFetcher,
+      parse: (content, store, uri, ct, cb) => cb(null),
+      sym: (u) => u
+    };
+    const ctx = makeContext({
+      islands: { 'https://x.test/foo': '{"@id":"#me"}' },
+      $rdf
+    });
+    vm.runInContext(extractReaderSource(html), ctx);
+    const result = await fakeFetcher.load('https://x.test/foo', {});
+    assert.ok(result instanceof Response,
+      'should resolve to a real Response when constructor is available');
+    assert.strictEqual(await result.text(), '{"@id":"#me"}');
+    assert.strictEqual(result.url, 'https://x.test/foo');
+  });
+
+  it('falls back to Response-shaped object when Response is unavailable', async () => {
+    // Build a context without Response so the fallback path runs.
+    const islandEl = {
+      type: 'application/ld+json',
+      textContent: '{"@id":"#x"}',
+      getAttribute: (n) => n === 'data-uri' ? 'https://x.test/foo' : null
+    };
+    const document = {
+      getElementById: (id) => id === 'dataisland' ? islandEl : null
+    };
+    const window = {};
+    const fakeFetcher = {
+      requested: {},
+      store: {},
+      load: async () => 'orig'
+    };
+    const $rdf = {
+      fetcher: fakeFetcher,
+      parse: (c, s, u, ct, cb) => cb(null),
+      sym: (u) => u
+    };
+    const ctx = vm.createContext({
+      window, document, $rdf,
+      setTimeout: () => 0, clearTimeout: () => {},
+      Promise, String, console,
+      Object: globalThis.Object
+      // Note: no Response in this context.
+    });
+    vm.runInContext(extractReaderSource(html), ctx);
+    const result = await fakeFetcher.load('https://x.test/foo', {});
+    assert.strictEqual(result.ok, true);
+    assert.strictEqual(result.status, 200);
+    assert.strictEqual(result.url, 'https://x.test/foo');
+    assert.strictEqual(typeof result.headers.get, 'function');
+  });
+
+  it('fallback headers.get returns the data island content-type (case-insensitive)', async () => {
+    // Build a context without Response so the fallback headers path runs.
+    const islandEl = {
+      type: 'application/ld+json',
+      textContent: '{"@id":"#x"}',
+      getAttribute: (n) => n === 'data-uri' ? 'https://x.test/foo' : null
+    };
+    const document = {
+      getElementById: (id) => id === 'dataisland' ? islandEl : null
+    };
+    const window = {};
+    const fakeFetcher = {
+      requested: {},
+      store: {},
+      load: async () => 'orig'
+    };
+    const $rdf = {
+      fetcher: fakeFetcher,
+      parse: (c, s, u, ct, cb) => cb(null),
+      sym: (u) => u
+    };
+    const ctx = vm.createContext({
+      window, document, $rdf,
+      setTimeout: () => 0, clearTimeout: () => {},
+      Promise, String, console,
+      Object: globalThis.Object
+      // No Response — forces fallback path.
+    });
+    vm.runInContext(extractReaderSource(html), ctx);
+    const result = await fakeFetcher.load('https://x.test/foo', {});
+    assert.strictEqual(result.headers.get('content-type'), 'application/ld+json');
+    assert.strictEqual(result.headers.get('Content-Type'), 'application/ld+json');
+    assert.strictEqual(result.headers.get('CONTENT-TYPE'), 'application/ld+json');
+    assert.strictEqual(result.headers.get('etag'), null);
+    assert.strictEqual(result.headers.get(123), null,
+      'non-string name should return null without throwing');
+  });
+
+  it('preserves existing window.__dataIsland but ensures .get is callable', () => {
+    // Simulate a prior script setting a truthy __dataIsland without .get.
+    const islandEl = {
+      type: 'application/ld+json',
+      textContent: '{"@id":"#me"}',
+      getAttribute: (n) => n === 'data-uri' ? 'https://x.test/foo' : null
+    };
+    const document = {
+      getElementById: (id) => id === 'dataisland' ? islandEl : null
+    };
+    const preExisting = { someOtherProperty: 'original-value' };
+    const window = { __dataIsland: preExisting };
+    const ctx = vm.createContext({
+      window, document,
+      setTimeout: () => 0, clearTimeout: () => {},
+      Promise, String, console, Response,
+      Object: globalThis.Object
+    });
+    vm.runInContext(extractReaderSource(html), ctx);
+
+    // Existing object preserved (not overwritten):
+    assert.strictEqual(ctx.window.__dataIsland, preExisting);
+    assert.strictEqual(ctx.window.__dataIsland.someOtherProperty, 'original-value');
+    // .get added since it was missing:
+    assert.strictEqual(typeof ctx.window.__dataIsland.get, 'function');
+    // And it works:
+    const result = ctx.window.__dataIsland.get('https://x.test/foo');
+    assert.strictEqual(result.contentType, 'application/ld+json');
+    assert.strictEqual(result.content, '{"@id":"#me"}');
+  });
+
+  it('normalizes primitive window.__dataIsland to an object before attaching .get', () => {
+    // If a script accidentally assigned a primitive (string/number/etc),
+    // `|| {}` would preserve it and attaching .get would silently fail.
+    // The reader must reset to a plain object before adding .get.
+    const islandEl = {
+      type: 'application/ld+json',
+      textContent: '{"@id":"#me"}',
+      getAttribute: (n) => n === 'data-uri' ? 'https://x.test/foo' : null
+    };
+    const document = {
+      getElementById: (id) => id === 'dataisland' ? islandEl : null
+    };
+
+    for (const primitive of ['stringy', 42, true, Symbol('x')]) {
+      const window = { __dataIsland: primitive };
+      const ctx = vm.createContext({
+        window, document,
+        setTimeout: () => 0, clearTimeout: () => {},
+        Promise, String, console, Response,
+        Object: globalThis.Object
+      });
+      vm.runInContext(extractReaderSource(html), ctx);
+      assert.strictEqual(typeof ctx.window.__dataIsland, 'object',
+        'primitive should be normalized to object');
+      assert.strictEqual(typeof ctx.window.__dataIsland.get, 'function',
+        '.get should be installed after normalization');
+      // And it works:
+      const result = ctx.window.__dataIsland.get('https://x.test/foo');
+      assert.strictEqual(result.contentType, 'application/ld+json');
+    }
+  });
+
+  it('normalizes a null window.__dataIsland to an object before attaching .get', () => {
+    // typeof null === 'object', so a naive object-check would let null
+    // through. Explicit null check is required.
+    const islandEl = {
+      type: 'application/ld+json',
+      textContent: '{"@id":"#me"}',
+      getAttribute: (n) => n === 'data-uri' ? 'https://x.test/foo' : null
+    };
+    const document = {
+      getElementById: (id) => id === 'dataisland' ? islandEl : null
+    };
+    const window = { __dataIsland: null };
+    const ctx = vm.createContext({
+      window, document,
+      setTimeout: () => 0, clearTimeout: () => {},
+      Promise, String, console, Response,
+      Object: globalThis.Object
+    });
+    vm.runInContext(extractReaderSource(html), ctx);
+    assert.notStrictEqual(ctx.window.__dataIsland, null);
+    assert.strictEqual(typeof ctx.window.__dataIsland.get, 'function');
+  });
+
+  it('does not overwrite a pre-existing window.__dataIsland.get', () => {
+    const customGet = function () {
+      return { contentType: 'custom', content: 'from-custom-get' };
+    };
+    const islandEl = {
+      type: 'application/ld+json',
+      textContent: '{"@id":"#me"}',
+      getAttribute: (n) => n === 'data-uri' ? 'https://x.test/foo' : null
+    };
+    const document = {
+      getElementById: (id) => id === 'dataisland' ? islandEl : null
+    };
+    const window = { __dataIsland: { get: customGet } };
+    const ctx = vm.createContext({
+      window, document,
+      setTimeout: () => 0, clearTimeout: () => {},
+      Promise, String, console, Response,
+      Object: globalThis.Object
+    });
+    vm.runInContext(extractReaderSource(html), ctx);
+
+    assert.strictEqual(ctx.window.__dataIsland.get, customGet,
+      'pre-existing custom .get must not be replaced');
+  });
+
+  it('tolerates missing fetcher.requested without hanging the Promise', async () => {
+    // Some rdflib/mashlib builds may not initialize `requested`.
+    // The patched load must still resolve cleanly.
+    const fakeFetcher = {
+      // No `requested` property.
+      store: {},
+      load: async () => 'orig'
+    };
+    const $rdf = {
+      fetcher: fakeFetcher,
+      parse: (c, s, u, ct, cb) => cb(null),
+      sym: (u) => u
+    };
+    const ctx = makeContext({
+      islands: { 'https://x.test/foo': '{"@id":"#z"}' },
+      $rdf
+    });
+    vm.runInContext(extractReaderSource(html), ctx);
+
+    // Bound the wait so a hanging Promise fails the test rather than
+    // hanging the whole suite.
+    const result = await Promise.race([
+      fakeFetcher.load('https://x.test/foo', {}),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('load() hung')), 500))
+    ]);
+    assert.strictEqual(result.ok, true);
+    assert.strictEqual(result.url, 'https://x.test/foo');
+  });
+});