javascript-solid-server 0.0.162 → 0.0.164

package/bin/jss.js

@@ -126,7 +126,7 @@ program
   .option('--invite-only', 'Require invite code for registration')
   .option('--no-invite-only', 'Allow open registration')
   .option('--single-user', 'Single-user mode (creates pod on startup, disables registration)')
-  .option('--single-user-name <name>', 'Username for single-user mode (default: me)')
+  .option('--single-user-name <name>', 'Mount the pod at /<name>/ instead of at the server root (default: root pod at /)')
   .option('--single-user-password <pw>', 'Initial IDP password to seed when creating the single-user pod (or set JSS_SINGLE_USER_PASSWORD)')
   .option('--webid-tls', 'Enable WebID-TLS client certificate authentication')
   .option('--no-webid-tls', 'Disable WebID-TLS authentication')

package/docs/configuration.md

@@ -258,19 +258,21 @@ Response:
 For personal pod servers where only one user needs access:
 
 ```bash
-# Basic single-user mode (creates pod at /me/)
-# On first run JSS will prompt for an initial password (TTY only).
+# Default: pod served at server root (#348). WebID is
+# /profile/card.jsonld#me; the IDP login username is "me". On first
+# run JSS will prompt for an initial password (TTY only).
 jss start --single-user --idp
 
 # Provide the initial IDP password non-interactively (systemd, containers, CI):
 jss start --single-user --idp --single-user-password 'choose-a-good-one'
 JSS_SINGLE_USER_PASSWORD='choose-a-good-one' jss start --single-user --idp
 
-# Custom username
+# Mount the pod at a named path instead of the origin. WebID becomes
+# /alice/profile/card.jsonld#me; login as "alice".
 jss start --single-user --single-user-name alice --idp
 
-# Root-level pod (pod at /, WebID at /profile/card#me)
-jss start --single-user --single-user-name '' --idp
+# Legacy /me/ pod — same as the old default before #348.
+jss start --single-user --single-user-name me --idp
 
 # Via environment
 JSS_SINGLE_USER=true jss start --idp
@@ -283,6 +285,18 @@ JSS_SINGLE_USER=true jss start --idp
 - Login works for the single user via password (`POST /idp/credentials`) or any other configured method
 - Proper ACLs generated automatically
 
+**Upgrading from a pre-#348 install:** if your existing pod was created with the old default (data lives under `<root>/me/`), JSS no longer auto-detects it — restarting plain `jss start --single-user` will start seeding a fresh empty root pod alongside your legacy `/me/` data, and your existing IDP account will keep authenticating against `/me/`. Pick one path on the next restart:
+- **Keep the legacy layout:** add `--single-user-name me` to your launch command. No data movement needed.
+- **Migrate to root pod:** move the *entire* contents of `<root>/me/` (including dotfiles like `.acl`, `.meta`, `.quota.json` — a plain `mv <root>/me/* <root>/` skips them) to `<root>/`, delete the IDP account for `me` (so the new root pod's `me` account can be seeded), then restart without the name flag. Use one of:
+
+  ```bash
+  # Option A: rsync handles dotfiles correctly with the trailing slash.
+  rsync -a <root>/me/ <root>/ && rm -rf <root>/me
+
+  # Option B: bash with dotglob enabled so * matches dotfiles too.
+  shopt -s dotglob && mv <root>/me/* <root>/ && rmdir <root>/me
+  ```
+
 **Initial password sources, in priority order:**
 1. `--single-user-password <pw>` CLI flag
 2. `JSS_SINGLE_USER_PASSWORD` env var

package/package.json

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

package/src/config.js

@@ -74,7 +74,11 @@ export const defaults = {
 
   // Single-user mode (personal pod server)
   singleUser: false,
-  singleUserName: 'me',
+  // null = root pod (mounted at server origin, WebID at
+  // /profile/card.jsonld#me). A string mounts the pod at /<name>/ —
+  // useful when more than one Solid identity coexists on the same
+  // origin, or when the operator wants the pre-#348 /me/ shape.
+  singleUserName: null,
   // Initial IDP password seeded on first single-user pod creation. If
   // unset and --idp is enabled, the server prompts on a TTY or logs a
   // warning and continues startup on non-TTY (so the pod is created but
@@ -399,20 +403,17 @@ export function printConfig(config) {
   console.log(`  SSL:           ${config.ssl ? 'enabled' : 'disabled'}`);
   console.log(`  Multi-user:    ${config.multiuser}`);
   if (config.singleUser) {
-    let details = `${config.singleUserName}`;
-    // Password seeding only runs when --idp is on AND the pod isn't the
-    // root-level case ('/'). Reflect both gates in the printed line so
-    // operators don't see a misleading "missing — login disabled" when
-    // login isn't governed by an IDP password at all.
+    const isRootPod = config.singleUserName === '/' || !config.singleUserName;
+    let details = isRootPod ? '/ (root pod)' : config.singleUserName;
+    // The "login as me" hint and password line only make sense when
+    // the built-in IdP is on. With --no-idp / external issuer there's
+    // no built-in login form, so don't imply one exists.
     if (config.idp) {
-      if (config.singleUserName === '/' || !config.singleUserName) {
-        details += ' (root pod; password not seeded)';
-      } else {
-        const pwSource = config.singleUserPassword
-          ? 'provided'
-          : (process.stdin.isTTY ? 'will prompt at startup' : 'missing — login disabled');
-        details += ` (password: ${pwSource})`;
-      }
+      if (isRootPod) details += ', login as "me"';
+      const pwSource = config.singleUserPassword
+        ? 'provided'
+        : (process.stdin.isTTY ? 'will prompt at startup' : 'missing — login disabled');
+      details += ` (password: ${pwSource})`;
     }
     console.log(`  Single-user:   ${details}`);
   }

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/src/server.js

@@ -93,7 +93,22 @@ export function createServer(options = {}) {
   const inviteOnly = options.inviteOnly ?? false;
   // Single-user mode - creates pod on startup, disables registration
   const singleUser = options.singleUser ?? false;
-  const singleUserName = options.singleUserName ?? 'me';
+  // Default null = root pod (#348). Pass an explicit singleUserName
+  // to mount the pod at /<name>/ instead. Normalize the
+  // historical `'/'` / `''` forms to null up front so downstream
+  // code (remoteStoragePlugin, decorators, etc.) doesn't have to
+  // re-check for the same three shapes.
+  //
+  // Pre-#348 installs (default 'me') that upgrade in place will see
+  // a fresh empty root pod alongside their /me/ data. The fix is to
+  // pass `--single-user-name me` on restart (or move data/me/* out
+  // to the data root). At v0.0.x we accept that one-time
+  // intervention rather than carrying detection magic in the code.
+  const rawSingleUserName = options.singleUserName ?? null;
+  const singleUserName =
+    (rawSingleUserName === '/' || rawSingleUserName === '')
+      ? null
+      : rawSingleUserName;
   const singleUserPassword = options.singleUserPassword ?? null;
   // Default storage quota per pod (50MB default, 0 = unlimited)
   const defaultQuota = options.defaultQuota ?? 50 * 1024 * 1024;
@@ -558,8 +573,10 @@ export function createServer(options = {}) {
       const baseUrl = idpIssuer?.replace(/\/$/, '') || `${protocol}://${host}:${port}`;
       const issuer = idpIssuer || `${baseUrl}/`;
 
-      // Root-level pod (empty or '/' name) vs named pod
-      const isRootPod = !singleUserName || singleUserName === '/';
+      // Root pod (no name) vs named pod. After the singleUserName
+      // normalization at the top of createServer(), null is the only
+      // root-pod shape we need to recognize here.
+      const isRootPod = !singleUserName;
       const podPath = isRootPod ? '/' : `/${singleUserName}/`;
       const podUri = isRootPod ? `${baseUrl}/` : `${baseUrl}/${singleUserName}/`;
       const displayName = isRootPod ? 'me' : singleUserName;
@@ -595,12 +612,22 @@ export function createServer(options = {}) {
       // this, single-user + --idp produces a pod but no credential, and
       // registration is intentionally disabled in single-user mode — so
       // the pod is unloggable until a password is set externally (#323).
-      if (idpEnabled && !isRootPod) {
+      //
+      // Root pods (#348) need this too: the pod has no name, but the IDP
+      // still needs *some* username for the login form. Default to 'me'
+      // — matches the WebID fragment, fits the historical convention.
+      if (idpEnabled) {
+        // The IDP also persists `podName` and surfaces it as the
+        // `name` claim under the OIDC `profile` scope (see
+        // src/idp/accounts.js). For root pods we use 'me' here too —
+        // a null podName would leak through as a null/missing
+        // profile.name on every login, which OIDC clients expect to
+        // be a non-empty human-readable string.
         await seedSingleUserIdpAccount({
           fastify,
-          username: singleUserName,
+          username: isRootPod ? 'me' : singleUserName,
           webId,
-          podName: singleUserName,
+          podName: isRootPod ? 'me' : singleUserName,
           providedPassword: singleUserPassword
         });
       }

package/test/config.test.js

@@ -158,3 +158,35 @@ describe('config — --single-user implies --idp (#331)', () => {
       '--no-idp without --single-user should not trigger the #331 warning');
   });
 });
+
+// #348: the user-visible default change — `jss start --single-user`
+// (no name flag) must produce a config where singleUserName is null,
+// so createServer() takes the root-pod path. createServer() has its
+// own tests but a future refactor of loadConfig() could silently
+// restore the old `'me'` default and only the server-level tests
+// would catch it via behaviour, not the config layer directly.
+describe('config — singleUserName default (#348)', () => {
+  it('loadConfig() returns singleUserName=null when no flag/env is set', async () => {
+    delete process.env.JSS_SINGLE_USER_NAME;
+    const cfg = await loadConfig({}, null);
+    assert.strictEqual(cfg.singleUserName, null,
+      'default must be null (= root pod), not the legacy "me"');
+  });
+
+  it('loadConfig() preserves an explicit singleUserName CLI arg', async () => {
+    delete process.env.JSS_SINGLE_USER_NAME;
+    const cfg = await loadConfig({ singleUserName: 'alice' }, null);
+    assert.strictEqual(cfg.singleUserName, 'alice');
+  });
+
+  it('loadConfig() respects JSS_SINGLE_USER_NAME from env', async () => {
+    process.env.JSS_SINGLE_USER_NAME = 'me';
+    try {
+      const cfg = await loadConfig({}, null);
+      assert.strictEqual(cfg.singleUserName, 'me',
+        'env var should restore the legacy "me" pod path on demand');
+    } finally {
+      delete process.env.JSS_SINGLE_USER_NAME;
+    }
+  });
+});

package/test/idp.test.js

@@ -458,6 +458,84 @@ describe('Identity Provider - Root pod type index ACLs', () => {
   });
 });
 
+// #348: --single-user with no name flag now defaults to a root pod
+// (was '/me/' historically). The server-side seed must land the
+// profile at /profile/card.jsonld, not /me/profile/card.jsonld.
+describe('Single-user default — root pod (#348)', () => {
+  let server;
+  let baseUrl;
+  const DEFAULT_DATA_DIR = './test-data-348-default-root';
+  const ROOT_POD_PASSWORD = 'root-pod-test-pw';
+
+  before(async () => {
+    await fs.remove(DEFAULT_DATA_DIR);
+    await fs.ensureDir(DEFAULT_DATA_DIR);
+
+    const port = await getAvailablePort();
+    baseUrl = `http://${TEST_HOST}:${port}`;
+
+    server = createServer({
+      logger: false,
+      root: DEFAULT_DATA_DIR,
+      idp: true,
+      idpIssuer: baseUrl,
+      singleUser: true,
+      // singleUserName intentionally omitted — exercises the new default.
+      // Provide a password so the seeding path runs non-interactively.
+      singleUserPassword: ROOT_POD_PASSWORD,
+      forceCloseConnections: true,
+    });
+
+    await server.listen({ port, host: TEST_HOST });
+  });
+
+  after(async () => {
+    await server.close();
+    await fs.remove(DEFAULT_DATA_DIR);
+  });
+
+  it('seeds the profile at /profile/card.jsonld (not /me/profile/...)', async () => {
+    const root = await fetch(`${baseUrl}/profile/card.jsonld`);
+    assert.strictEqual(root.status, 200,
+      '--single-user with no name should default to a root pod');
+    // Check the filesystem directly — an HTTP-only check could pass
+    // on a 401 even if /me/ data was somehow seeded, which would
+    // hide the regression we care about (root vs /me/ pod).
+    assert.strictEqual(await fs.pathExists(path.join(DEFAULT_DATA_DIR, 'me/profile/card.jsonld')), false,
+      'no /me/ pod files should be created when singleUserName is unset');
+    assert.strictEqual(await fs.pathExists(path.join(DEFAULT_DATA_DIR, 'me/profile/card')), false,
+      'no legacy /me/ pod files should be created either');
+  });
+
+  it('WebID resolves at the server origin', async () => {
+    const res = await fetch(`${baseUrl}/profile/card.jsonld`);
+    const body = await res.json();
+    const webId = `${baseUrl}/profile/card.jsonld#me`;
+    const matches = Array.isArray(body)
+      ? body.some(n => n['@id'] === webId)
+      : body['@id'] === webId || (body['@graph'] || []).some(n => n['@id'] === webId);
+    assert.ok(matches, `profile should declare WebID ${webId}, got: ${JSON.stringify(body).slice(0, 200)}`);
+  });
+
+  it('seeds an IDP account for "me" so the root pod is loggable', async () => {
+    // Round-2 review of #348: a regression here would mean a fresh
+    // `jss start --single-user --idp` produces a pod nobody can log
+    // in to (registration is disabled in single-user mode, so there
+    // would be no recovery path other than out-of-band account
+    // creation). Use the credentials endpoint as a black-box login
+    // probe — if it issues a token, the seed worked.
+    const res = await fetch(`${baseUrl}/idp/credentials`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username: 'me', password: ROOT_POD_PASSWORD }),
+    });
+    assert.strictEqual(res.status, 200,
+      `login as "me" should succeed for the default root pod (got ${res.status})`);
+    const body = await res.json();
+    assert.ok(body.access_token, 'response should carry an access token');
+  });
+});
+
 describe('Identity Provider - Accounts', () => {
   let server;
   let accountsUrl;

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');
+  });
+});

package/test/url.test.js

@@ -33,6 +33,14 @@ describe('getPodName', () => {
       assert.strictEqual(getPodName(req), '.');
     });
 
+    it("returns '.' for a root pod (singleUserName null — #348 default)", () => {
+      // server.js normalizes '/' and '' to null at the top of
+      // createServer, so most root-pod requests now reach getPodName
+      // with singleUserName === null. Pin that path explicitly.
+      const req = { singleUser: true, singleUserName: null, url: '/index.html' };
+      assert.strictEqual(getPodName(req), '.');
+    });
+
     it('returns singleUserName for a named pod, regardless of URL', () => {
       const req = { singleUser: true, singleUserName: 'me', url: '/index.html' };
       assert.strictEqual(getPodName(req), 'me');