Round-trip optimization for HTML resource views via inline data island reader #346

Summary

When JSS serves a resource as HTML, it currently embeds the resource's data inline as a JSON-LD data island (shipped in v0.0.161 / PRs #343 + #345). However, RDF clients viewing the page typically issue a second HTTP request to fetch the same data via content negotiation, ignoring the inline data.

This issue proposes adding a small inline reader script that exposes the data island to the page's RDF client, halving network round-trips for browser views.

Current Behavior

Browser → GET /resource (Accept: text/html)
Server  → Returns HTML wrapper + inline JSON-LD data island
Browser → RDF client loads, calls fetcher.load(uri)
Browser → GET /resource (Accept: text/turtle)
Server  → Returns RDF data
Browser → Client renders

Two round trips for a single logical resource view.

Proposed Behavior

Browser → GET /resource (Accept: text/html)
Server  → Returns HTML wrapper + inline JSON-LD data island + inline reader
Browser → Client loads, fetcher.load(uri) intercepted, reads inline data
Browser → Client renders

Single round trip. Identical result.

Implementation Scope

src/mashlib/index.js, in generateDatabrowserHtml() (and generateModuleDatabrowserHtml()):

Add a small inline <script> block exposing:

1. Generic accessor — window.__dataIsland.get(uri) returns the inline data for a URI with a matching data island, or null
2. rdflib.js compatibility patch — if $rdf.fetcher is present, patches fetcher.load() to check the accessor first, falling through to network fetch on miss or parse error
3. Bounded retry — gives up gracefully after ~10 seconds if rdflib never loads (e.g., a non-rdflib client)

Patch is additive and falls through cleanly. Approximate size:

• Generic accessor: ~10 lines
• rdflib patch: ~20 lines
• Total: ~30 lines inline JavaScript

Out of Scope

• New npm dependency (stays inline)
• Modifications to mashlib or any other client library
• Patches for non-rdflib RDF clients (the generic accessor lets others build their own)

Configuration

Default-on. Optional compat: false config flag for opt-out.

Acceptance Criteria

• HTML view of a JSON-LD-storable resource is rendered with one HTTP request, not two
• rdflib-based clients (including mashlib v2.2.0 and earlier) read the data island via the inline reader
• If the data island is missing, malformed, or fails to parse, the reader falls through to original fetch behavior with no broken state
• If rdflib never loads (e.g., a different client), the patch silently times out after ~10 seconds without effect
• Existing tests stay green; new tests cover: data-island hit, parse-failure fallback, rdflib-absent timeout

Side Benefits

• Offline support: saved HTML continues to render
• Static export viability: HTML pages are self-contained
• Reduced server load: ~half the requests for browser views
• Better Core Web Vitals: faster initial render, less network dependency
• Aligns with modern web-perf practices: inlining critical resources, eliminating waterfall round-trips