javascript-solid-server 0.0.159 → 0.0.161

package/.claude/settings.local.json

@@ -358,7 +358,10 @@
       "Bash(rm LICENSE.full)",
       "Bash(awk -F: '{print $1,$2}')",
       "Bash(awk -F: '{print $1}')",
-      "WebFetch(domain:www.gitfork.app)"
+      "WebFetch(domain:www.gitfork.app)",
+      "Bash(JSS_SINGLE_USER_PASSWORD=hunter2 timeout 3 node bin/jss.js start --port 4581 --root /tmp/jss-103 --single-user --single-user-name alice --idp)",
+      "Bash(JSS_SINGLE_USER_PASSWORD=hunter2 timeout 2 node bin/jss.js start --port 4581 --root /tmp/jss-103 --single-user-name alice --idp)",
+      "Bash(JSS_SINGLE_USER_PASSWORD=hunter2 timeout 3 node bin/jss.js start --port 4581 --root /tmp/jss-103-sanity --single-user-name alice --single-user --idp)"
     ]
   }
 }

package/bin/jss.js

@@ -32,6 +32,49 @@ program
   .description('JavaScript Solid Server - A minimal, fast, JSON-LD native Solid server')
   .version(pkg.version);
 
+/**
+ * Convert a camelCase option name back to its kebab-case CLI form for
+ * error messages (`singleUserName` → `single-user-name`).
+ */
+function camelToKebab (name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+/**
+ * Reject any option value that looks like another flag (#103).
+ *
+ * Commander happily consumes the next argv as a value, so
+ *   `jss start --single-user-name --idp`
+ * silently sets `singleUserName="--idp"` and the IdP flag is lost.
+ * This validator runs as a `preAction` hook for every subcommand, so
+ * any option with a missing value gets a clear error instead of a
+ * confusing downstream failure ("issuer has no registration endpoint",
+ * "Single-user: --idp" in the banner, etc.).
+ */
+program.hook('preAction', (_thisCommand, actionCommand) => {
+  const opts = actionCommand.opts();
+  for (const [key, value] of Object.entries(opts)) {
+    const flag = camelToKebab(key);
+    if (typeof value === 'string' && value.startsWith('--')) {
+      console.error(
+        `Error: --${flag} value "${value}" looks like a flag, not a value.\n` +
+        `Hint: did you forget to provide a value? e.g. --${flag} someValue`
+      );
+      process.exit(1);
+    }
+    // Numeric options (parseInt-coerced like --port) silently produce
+    // NaN when given a flag like `--idp`. Catch that too — same root
+    // cause, different surface.
+    if (typeof value === 'number' && Number.isNaN(value)) {
+      console.error(
+        `Error: --${flag} got a non-numeric value (parsed as NaN).\n` +
+        `Hint: did you forget to provide a number? e.g. --${flag} 8080`
+      );
+      process.exit(1);
+    }
+  }
+});
+
 /**
  * Start command
  */

package/package.json

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

package/src/handlers/resource.js

@@ -14,7 +14,7 @@ import {
 } from '../rdf/conneg.js';
 import { emitChange } from '../notifications/events.js';
 import { checkIfMatch, checkIfNoneMatchForGet, checkIfNoneMatchForWrite } from '../utils/conditional.js';
-import { generateDatabrowserHtml, generateModuleDatabrowserHtml, shouldServeMashlib } from '../mashlib/index.js';
+import { generateDatabrowserHtml, generateModuleDatabrowserHtml, shouldServeMashlib, DATA_ISLAND_MAX_BYTES } from '../mashlib/index.js';
 
 /**
  * Live reload script - injected into HTML when --live-reload is enabled
@@ -238,9 +238,21 @@ export async function handleGet(request, reply) {
 
     // Check if we should serve Mashlib data browser for containers
     if (shouldServeMashlib(request, request.mashlibEnabled, 'application/ld+json')) {
+      // Phase 1 of #7: also embed the container's JSON-LD listing as a
+      // data island so consumers that look for `<script
+      // type="application/ld+json">` (search-engine rich-results,
+      // archival crawlers, future mashlib zero-fetch path) get the data
+      // without a second request. Use compact (no-whitespace) form for
+      // the embed so we don't burn bytes against DATA_ISLAND_MAX_BYTES
+      // on indentation that nothing will ever read.
+      const embedJsonLd = JSON.stringify(jsonLd);
       const html = request.mashlibModule
-        ? generateModuleDatabrowserHtml(request.mashlibModule)
-        : generateDatabrowserHtml(resourceUrl, request.mashlibCdn ? request.mashlibVersion : null);
+        ? generateModuleDatabrowserHtml(request.mashlibModule, resourceUrl, { embedJsonLd })
+        : generateDatabrowserHtml(
+          resourceUrl,
+          request.mashlibCdn ? request.mashlibVersion : null,
+          { embedJsonLd }
+        );
       const headers = getAllHeaders({
         isContainer: true,
         etag: stats.etag,
@@ -318,9 +330,31 @@ export async function handleGet(request, reply) {
   // Check if we should serve Mashlib data browser
   // Only for RDF resources when Accept: text/html is requested
   if (shouldServeMashlib(request, request.mashlibEnabled, storedContentType)) {
+    // Phase 1 of #7: embed the resource's JSON-LD bytes as a data
+    // island when it's already JSON-LD (the JSS-native format). Other
+    // formats are out of Phase-1 scope; the wrapper still loads
+    // correctly and mashlib XHR-fetches as before.
+    //
+    // Cap-aware short-circuit: skip the read entirely when the file is
+    // already over the embed cap. The island would be dropped anyway,
+    // and large JSON-LD resources would otherwise load into memory on
+    // every HTML navigation.
+    let embedJsonLd;
+    if (storedContentType === 'application/ld+json' &&
+        stats.size <= DATA_ISLAND_MAX_BYTES) {
+      // dataIsland() in mashlib/index.js coerces Buffer → string itself,
+      // so we hand it the Buffer directly instead of allocating a UTF-8
+      // string copy on every navigation.
+      const buf = await storage.read(storagePath);
+      if (buf) embedJsonLd = buf;
+    }
     const html = request.mashlibModule
-      ? generateModuleDatabrowserHtml(request.mashlibModule)
-      : generateDatabrowserHtml(resourceUrl, request.mashlibCdn ? request.mashlibVersion : null);
+      ? generateModuleDatabrowserHtml(request.mashlibModule, resourceUrl, { embedJsonLd })
+      : generateDatabrowserHtml(
+        resourceUrl,
+        request.mashlibCdn ? request.mashlibVersion : null,
+        { embedJsonLd }
+      );
     const headers = getAllHeaders({
       isContainer: false,
       etag: stats.etag,

package/src/mashlib/index.js

@@ -4,23 +4,97 @@
  * Generates HTML wrapper that loads SolidOS Mashlib from CDN.
  * When a browser requests an RDF resource with Accept: text/html,
  * we return this wrapper which then fetches and renders the data.
+ *
+ * Phase 1 of #7: when the originating resource is reasonably small
+ * RDF, the JSON-LD bytes are embedded in the wrapper as a `<script
+ * type="application/ld+json" id="dataisland" data-uri="…">` block.
+ * Browsers ignore non-JS script bodies, so this is harmless to all
+ * existing clients (mashlib still XHR-fetches today). It immediately
+ * benefits anything that knows to look for `application/ld+json`
+ * islands — search engine rich-results, archival crawlers, scrapers,
+ * static-site exporters — and gives Phase 2 a zero-network fast path.
+ */
+
+/**
+ * Cap on how much JSON-LD we'll inline. A 256 KB resource fits any
+ * realistic profile, type index, or container listing. Above that we
+ * drop the island and let the existing XHR path handle it so we don't
+ * make every navigation re-download a multi-megabyte resource.
+ */
+export const DATA_ISLAND_MAX_BYTES = 256 * 1024;
+
+/**
+ * Escape a JSON-LD body for safe inclusion inside `<script
+ * type="application/ld+json">…</script>`.
+ *
+ * Browsers don't execute the script (wrong MIME), but the HTML parser
+ * still scans the body for an end-of-script tag. The relevant rule:
+ * any `</` followed by `script` (case-insensitive) terminates the
+ * element regardless of what follows — `</script>`, `</script >`,
+ * `</script\n>`, `</SCRIPT>` and friends all close it. Escaping just
+ * the literal `</script>` token is too narrow.
+ *
+ * The robust fix is to replace every literal `<` byte in the body with
+ * the JSON string-escape for U+003C — the six characters
+ * backslash-u-0-0-3-c (the same form the implementation emits below).
+ * JSON-LD is JSON, and a JSON parser decodes that escape back to a
+ * literal `<` natively, so document semantics are preserved. After
+ * this transform the body literally cannot contain a `<` byte — so no
+ * end-tag (or comment, CDATA, etc.) can possibly start.
+ */
+function escapeForScriptBlock(jsonLdString) {
+  return String(jsonLdString).replace(/</g, '\\u003c');
+}
+
+/**
+ * Build the data-island `<script>` block for the given JSON-LD payload.
+ * Returns an empty string if the payload is missing or over the size
+ * cap so callers can unconditionally interpolate `dataIsland(...)`.
+ *
+ * The cap applies to the *escaped* body — i.e. the bytes that will
+ * actually appear in the HTTP response. `escapeForScriptBlock` can
+ * expand input up to 6x (each literal `<` becomes the 6-byte JSON
+ * escape sequence backslash-u-0-0-3-c), so checking the raw input
+ * size alone could let an HTML response balloon past the cap.
+ *
+ * Two-stage check:
+ *   1. Cheap raw-byte pre-check — escape can only grow the body,
+ *      so a raw payload already over the cap is guaranteed to be
+ *      over after escaping; drop without doing the work.
+ *   2. Post-escape check — catches the rare case where input was
+ *      under the cap but expanded above it (`<`-heavy bodies).
  */
+function dataIsland(resourceUrl, jsonLdString) {
+  if (!jsonLdString) return '';
+  const raw = String(jsonLdString);
+  if (Buffer.byteLength(raw, 'utf8') > DATA_ISLAND_MAX_BYTES) return '';
+  const safeBody = escapeForScriptBlock(raw);
+  if (Buffer.byteLength(safeBody, 'utf8') > DATA_ISLAND_MAX_BYTES) return '';
+  const safeUri = escapeHtml(String(resourceUrl));
+  return `<script type="application/ld+json" id="dataisland" data-uri="${safeUri}">${safeBody}</script>`;
+}
 
 /**
  * Generate Mashlib databrowser HTML
  *
- * @param {string} resourceUrl - The URL of the resource being viewed (unused, kept for API compatibility)
+ * @param {string} resourceUrl - The URL of the resource being viewed
  * @param {string} cdnVersion - If provided, load mashlib from unpkg CDN (e.g., "2.0.0")
+ * @param {object} [opts]
+ * @param {string|Buffer} [opts.embedJsonLd] - JSON-LD body to inline
+ *   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.
  * @returns {string} HTML content
  */
-export function generateDatabrowserHtml(resourceUrl, cdnVersion = null) {
+export function generateDatabrowserHtml(resourceUrl, cdnVersion = null, opts = {}) {
+  const island = dataIsland(resourceUrl, opts.embedJsonLd);
   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"><header id="PageHeader"></header>
+<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>
 <script>
@@ -37,22 +111,27 @@ export function generateDatabrowserHtml(resourceUrl, cdnVersion = null) {
   // 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"><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}<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>`;
 }
 
 /**
  * Generate ES module-based databrowser HTML
  *
  * @param {string} moduleUrl - URL to the ES module entry point
+ * @param {string} resourceUrl - The URL of the resource being viewed
+ * @param {object} [opts]
+ * @param {string|Buffer} [opts.embedJsonLd] - JSON-LD body for the
+ *   data island, same contract as `generateDatabrowserHtml`. Phase 1 of #7.
  * @returns {string} HTML content
  */
-export function generateModuleDatabrowserHtml(moduleUrl) {
+export function generateModuleDatabrowserHtml(moduleUrl, resourceUrl = '', opts = {}) {
   const cssUrl = moduleUrl.replace(/\.js$/, '.css');
+  const island = dataIsland(resourceUrl, opts.embedJsonLd);
   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><div id="mashlib"></div>
+<body>${island}<div id="mashlib"></div>
 <script type="module" src="${moduleUrl}"></script>
 </body></html>`;
 }

package/test/cli-flag-like-values.test.js

@@ -0,0 +1,88 @@
+/**
+ * Regression tests for #103 — `bin/jss.js` must reject option values
+ * that look like flags (e.g. `--single-user-name --idp`) instead of
+ * silently using `--idp` as the username and breaking IdP setup.
+ *
+ * These spawn the CLI as a subprocess and assert exit-code + stderr.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.join(__dirname, '..', 'bin', 'jss.js');
+
+// Timeout cap so the suite can never hang if the validator regresses
+// and `start` actually tries to bind a port instead of exiting early.
+const RUN_TIMEOUT_MS = 10_000;
+
+function runCli(args) {
+  const r = spawnSync(process.execPath, [BIN, ...args], {
+    encoding: 'utf8',
+    timeout: RUN_TIMEOUT_MS,
+    killSignal: 'SIGKILL'
+  });
+  // spawnSync sets `signal` to the kill signal when timeout fires. Treat
+  // that as a hard test failure rather than letting downstream
+  // assertions on stderr accidentally pass.
+  assert.strictEqual(
+    r.signal, null,
+    `CLI did not exit within ${RUN_TIMEOUT_MS}ms — likely the preAction ` +
+    `validator regressed and \`start\` is actually trying to listen. ` +
+    `args: ${JSON.stringify(args)}; partial stderr: ${r.stderr}`
+  );
+  return r;
+}
+
+describe('bin/jss.js — flag-like option values (#103)', () => {
+  it('rejects `--single-user-name --idp` with a clear error', () => {
+    const r = runCli(['start', '--single-user-name', '--idp']);
+    assert.notStrictEqual(r.status, 0, 'exit code should be non-zero');
+    assert.match(r.stderr, /--single-user-name value "--idp" looks like a flag/);
+    assert.match(r.stderr, /Hint: did you forget to provide a value\?/);
+  });
+
+  it('rejects another option swallowing a flag (covers --idp-issuer too)', () => {
+    // Commander's behaviour: it greedily consumes the next argv as the
+    // value, which is the whole reason the bug exists. We use a flag
+    // commander doesn't know about so commander doesn't reroute it
+    // through its own argument-count error. The dummy name is
+    // collision-proof — if anyone ever adds a real `--bogus-...` flag
+    // matching this pattern, the duplication is the bigger problem.
+    const FAKE_FLAG = '--__jss103_unlikely_cli_option__';
+    const r = runCli(['start', '--idp-issuer', FAKE_FLAG]);
+    assert.notStrictEqual(r.status, 0);
+    assert.match(
+      r.stderr,
+      new RegExp(`--idp-issuer value "${FAKE_FLAG}" looks like a flag`)
+    );
+  });
+
+  it('rejects `--port --idp` (numeric option → NaN) with helpful error', () => {
+    const r = runCli(['start', '--port', '--idp']);
+    assert.notStrictEqual(r.status, 0);
+    assert.match(r.stderr, /--port got a non-numeric value/);
+    assert.match(r.stderr, /Hint: did you forget to provide a number\?/);
+  });
+
+  it('accepts a real value and reaches normal config processing', () => {
+    // --print-config exits 0 cleanly after dumping config; this proves
+    // the validator doesn't false-positive on legitimate values.
+    // Use os.tmpdir() rather than a hard-coded /tmp/... so the test is
+    // portable across platforms (and matches the rest of the suite).
+    const tmpRoot = path.join(os.tmpdir(), 'jss-103-sanity-doesnotneedtoexist');
+    const r = runCli(['start',
+      '--port', '4582',
+      '--root', tmpRoot,
+      '--single-user-name', 'alice',
+      '--print-config'
+    ]);
+    assert.strictEqual(r.status, 0,
+      `expected clean exit, got ${r.status}; stderr: ${r.stderr}`);
+    assert.match(r.stdout, /Configuration:/);
+  });
+});

package/test/data-island.test.js

@@ -0,0 +1,209 @@
+/**
+ * Phase-1 tests for the JSON-LD data island (#7).
+ *
+ * The mashlib HTML wrapper now carries the resource's JSON-LD bytes
+ * inside a `<script type="application/ld+json" id="dataisland"
+ * data-uri="...">` block. Phase 1 doesn't change mashlib's runtime behaviour — the
+ * island is purely additive — so these tests pin:
+ *   - emission shape (script tag, id, MIME, data-uri)
+ *   - escape: any `</script>` substring inside the body must not
+ *     prematurely close the script tag
+ *   - size cap: oversized payloads silently drop the island so we
+ *     don't make every navigation re-download a multi-megabyte file
+ *   - presence in the live HTTP response (resource and container)
+ *   - safe URI attribute against quote / angle-bracket injection
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import {
+  startTestServer,
+  stopTestServer,
+  request,
+  createTestPod,
+  assertStatus,
+  assertHeaderContains
+} from './helpers.js';
+import {
+  generateDatabrowserHtml,
+  generateModuleDatabrowserHtml,
+  DATA_ISLAND_MAX_BYTES
+} from '../src/mashlib/index.js';
+
+describe('mashlib data island — emission (unit, #7)', () => {
+  it('emits <script type="application/ld+json" id="dataisland" data-uri="..."> when payload supplied', () => {
+    const html = generateDatabrowserHtml(
+      'https://test.solid.social/profile/card.jsonld',
+      '2.0.0',
+      { embedJsonLd: '{"@id":"#me","foaf:name":"Alice"}' }
+    );
+    assert.match(html, /<script type="application\/ld\+json" id="dataisland" data-uri="https:\/\/test\.solid\.social\/profile\/card\.jsonld">/);
+    assert.match(html, /"@id":"#me"/);
+    assert.match(html, /<\/script>/);
+  });
+
+  it('omits the data island when no payload is supplied (back-compat)', () => {
+    const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0');
+    assert.doesNotMatch(html, /id="dataisland"/);
+  });
+
+  it('omits the data island for oversized payloads (size cap)', () => {
+    // Construct a JSON-LD body just over the cap.
+    const filler = 'x'.repeat(DATA_ISLAND_MAX_BYTES + 1024);
+    const oversized = `{"content":"${filler}"}`;
+    const html = generateDatabrowserHtml(
+      'https://x.test/big',
+      '2.0.0',
+      { embedJsonLd: oversized }
+    );
+    assert.doesNotMatch(html, /id="dataisland"/,
+      'island must drop silently above DATA_ISLAND_MAX_BYTES');
+  });
+
+  it('cap applies post-escape (defends against `<`-heavy expansion)', () => {
+    // A pathological body that's well under the cap as raw bytes but
+    // explodes 6x after escaping — every literal `<` byte becomes the
+    // 6-byte JSON escape sequence backslash-u-0-0-3-c. Without the
+    // post-escape check, this would emit a multi-megabyte island.
+    const halfCap = Math.floor(DATA_ISLAND_MAX_BYTES / 2);
+    const payload = '<'.repeat(halfCap); // 128 KB raw, ~768 KB escaped
+    const html = generateDatabrowserHtml(
+      'https://x.test/expand',
+      '2.0.0',
+      { embedJsonLd: payload }
+    );
+    assert.doesNotMatch(html, /id="dataisland"/,
+      'island must drop when the escaped body exceeds the cap');
+  });
+
+  // The escape strategy is "encode every `<` byte as the six-character
+  // JSON escape `\\u003c`". Test the wide variety of strings that an
+  // HTML parser would otherwise treat as a closing tag — `</script>`,
+  // `</script >`, `</script\n>`, `</SCRIPT>`, `</scRIPT>` — plus
+  // `<!--`, all of which require a literal `<` to start the dangerous
+  // sequence. After escaping, no literal `<` exists in the body and
+  // every transformed location appears as `\\u003c`.
+  const escapeTrojans = [
+    ['exact </script>',      '{"x":"a</script>b"}'],
+    ['with space </script >', '{"x":"a</script >b"}'],
+    ['with newline </script\\n>', '{"x":"a</script\n>b"}'],
+    ['uppercase </SCRIPT>',  '{"x":"a</SCRIPT>b"}'],
+    ['mixed </ScRiPt>',      '{"x":"a</ScRiPt>b"}'],
+    ['<!-- comment',         '{"x":"<!-- hidden -->"}']
+  ];
+  for (const [label, body] of escapeTrojans) {
+    it(`escape blocks ${label} from prematurely terminating the tag`, () => {
+      const html = generateDatabrowserHtml(
+        'https://x.test/r',
+        '2.0.0',
+        { embedJsonLd: body }
+      );
+      const start = html.indexOf('id="dataisland"');
+      assert.ok(start > 0, 'data island should be present');
+      // Slice from the island's `>` (end of opening tag) forward.
+      const open = html.indexOf('>', start) + 1;
+      const close = html.indexOf('</script>', open);
+      const inner = html.slice(open, close);
+      // After our escape, the body must contain NO literal `<`.
+      assert.doesNotMatch(inner, /</,
+        `script body must not contain a literal "<" — got: ${JSON.stringify(inner)}`);
+      // The escaped form (the six characters backslash-u-0-0-3-c)
+      // should be present.
+      assert.match(inner, /\\u003c/,
+        'escaped form `\\u003c` must appear');
+    });
+  }
+
+  it('accepts a Buffer payload (handler may pass storage.read() result directly)', () => {
+    // The src/handlers/resource.js path used to convert with .toString()
+    // before passing in; tightening that contract risks regressions, so
+    // the helper accepts a Buffer transparently.
+    const buf = Buffer.from('{"@id":"#me","foaf:name":"BufferAlice"}', 'utf8');
+    const html = generateDatabrowserHtml(
+      'https://x.test/r',
+      '2.0.0',
+      { embedJsonLd: buf }
+    );
+    assert.match(html, /id="dataisland"/);
+    assert.match(html, /"foaf:name":"BufferAlice"/);
+  });
+
+  it('the module-mode wrapper also emits the data island', () => {
+    const html = generateModuleDatabrowserHtml(
+      'https://example.test/mashlib.js',
+      'https://test.solid.social/profile/card.jsonld',
+      { embedJsonLd: '{"@id":"#me"}' }
+    );
+    assert.match(html, /<script type="application\/ld\+json" id="dataisland" data-uri="https:\/\/test\.solid\.social\/profile\/card\.jsonld">/);
+    assert.match(html, /"@id":"#me"/);
+  });
+
+  it('escapes the data-uri attribute against quote / angle-bracket injection', () => {
+    const html = generateDatabrowserHtml(
+      'https://x.test/r"><img src=x onerror=alert(1)>',
+      '2.0.0',
+      { embedJsonLd: '{}' }
+    );
+    // The dangerous characters must be HTML-entity encoded inside the
+    // attribute, so the attribute can't be broken open.
+    assert.match(html, /data-uri="https:\/\/x\.test\/r&quot;&gt;&lt;img/);
+    assert.doesNotMatch(html, /data-uri="https:\/\/x\.test\/r"><img/);
+  });
+});
+
+// Integration coverage — the data island must actually appear in the
+// HTTP response when a browser asks for the wrapper.
+describe('mashlib data island — integration (#7)', () => {
+  before(async () => {
+    await startTestServer({ mashlibCdn: true });
+    await createTestPod('islandtest');
+    // Put a small JSON-LD resource we can fetch back as HTML.
+    await request('/islandtest/public/note.jsonld', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/ld+json' },
+      body: JSON.stringify({
+        '@context': { foaf: 'http://xmlns.com/foaf/0.1/' },
+        '@id': '#note',
+        'foaf:name': 'island test'
+      }),
+      auth: 'islandtest'
+    });
+  });
+
+  after(async () => { await stopTestServer(); });
+
+  it('a browser GET to a JSON-LD resource carries the data island', async () => {
+    const res = await request('/islandtest/public/note.jsonld', {
+      headers: { Accept: 'text/html,application/xhtml+xml,*/*;q=0.8' }
+    });
+    assertStatus(res, 200);
+    assertHeaderContains(res, 'Content-Type', 'text/html');
+    const body = await res.text();
+    assert.match(body, /id="dataisland"/);
+    assert.match(body, /<script type="application\/ld\+json"/);
+    assert.match(body, /"foaf:name":"island test"/);
+  });
+
+  it('a browser GET to a container carries the listing as a data island', async () => {
+    const res = await request('/islandtest/public/', {
+      headers: { Accept: 'text/html,application/xhtml+xml,*/*;q=0.8' }
+    });
+    assertStatus(res, 200);
+    assertHeaderContains(res, 'Content-Type', 'text/html');
+    const body = await res.text();
+    assert.match(body, /id="dataisland"/);
+    assert.match(body, /<script type="application\/ld\+json"/);
+    // Contains an ldp:contains pointing at the resource we just PUT.
+    assert.match(body, /note\.jsonld/);
+  });
+
+  it('non-HTML Accept (mashlib XHR) does NOT trigger the wrapper', async () => {
+    const res = await request('/islandtest/public/note.jsonld', {
+      headers: { Accept: 'application/ld+json' }
+    });
+    assertHeaderContains(res, 'Content-Type', 'application/ld+json');
+    const body = await res.text();
+    assert.doesNotMatch(body, /id="dataisland"/);
+    assert.doesNotMatch(body, /<!doctype html>/i);
+  });
+});