inertjs-vector 1.0.0-beta.6 → 1.0.0-beta.8

package/package.json

@@ -1,16 +1,16 @@
-{
-  "name": "inertjs-vector",
-  "version": "1.0.0-beta.6",
-  "type": "module",
-  "main": "src/index.js",
-  "dependencies": {
-    "inertjs-optimizer": "^1.0.0-beta.6"
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "exports": {
-    ".": "./src/index.js",
-    "./*": "./*"
-  }
-}
+{
+  "name": "inertjs-vector",
+  "version": "1.0.0-beta.8",
+  "type": "module",
+  "main": "src/index.js",
+  "dependencies": {
+    "inertjs-optimizer": "^1.0.0-beta.6"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./*": "./*"
+  }
+}

package/src/index.js

@@ -1,102 +1,155 @@
-import { analyzeTemplateStrings, escape, CONTEXT } from './escaper.js';
-import { minifyHTML } from 'inertjs-optimizer';
-export { resolveToString } from './resolve.js';
-
-const planCache = new WeakMap();
-
-export class RawString {
-  constructor(str) {
-    this.value = str;
-  }
-  toString() {
-    return this.value;
-  }
-}
-
-/**
- * Opt-out of HTML escaping. 
- * Use with extreme caution.
- * 
- * @param {string} str Unescaped HTML string
- * @returns {RawString}
- */
-export function raw(str, suppressWarning = false) {
-  if (!suppressWarning && process.env.NODE_ENV !== 'production') {
-    const stack = new Error().stack;
-    // index 1 is raw(), index 2 is the caller
-    const callSite = stack && stack.split('\n')[2] ? stack.split('\n')[2].trim() : 'unknown location';
-    console.warn(`[Lens] Warning: raw() escape hatch used at ${callSite}. Ensure this string is safe.`);
-  }
-  return new RawString(str);
-}
-
-/**
- * Tagged template literal for Vector template engine.
- * Safely escapes all interpolations based on their HTML context.
- * 
- * @param {TemplateStringsArray} strings 
- * @param  {...any} values 
- */
-export function vec(strings, ...values) {
-  let plan = planCache.get(strings);
-  if (!plan) {
-    plan = analyzeTemplateStrings(strings);
-    // Minify statics on the fly during template parse
-    plan.statics = plan.statics.map(staticStr => minifyHTML(staticStr));
-    planCache.set(strings, plan);
-  }
-
-  // Check if we need to stream (any value is a Promise or AsyncIterable)
-  const isAsync = values.some(v => v instanceof Promise || (v && typeof v[Symbol.asyncIterator] === 'function') || (v && v.type === 'VecStream'));
-  
-  if (isAsync) {
-    return {
-      type: 'VecStream',
-      plan,
-      values
-    };
-  }
-
-  let result = plan.statics[0];
-  for (let i = 0; i < values.length; i++) {
-    const val = values[i];
-    const ctx = plan.contexts[i];
-    const attrName = plan.attrNames[i];
-
-    if (val instanceof RawString) {
-      result += val.value;
-    } else if (val && val.type === 'VecStream') {
-       throw new Error('E_INERT_VECTOR_NESTED_ASYNC: Async nested vec`` found in synchronous render context.');
-    } else if (Array.isArray(val)) {
-       result += val.map(v => v instanceof RawString ? v.value : escape(v, ctx, attrName)).join('');
-    } else {
-      result += escape(val, ctx, attrName);
-    }
-    result += plan.statics[i + 1];
-  }
-  
-  // Return RawString so nested `vec` calls aren't double-escaped
-  return new RawString(result);
-}
-
-/**
- * Generates an optimized image tag that hooks into InertJS's on-the-fly optimizer.
- * 
- * @param {object} props Image properties: src, width, height, quality, class, alt
- * @returns {RawString}
- */
-export function img({ src, width, height, quality, ...rest }) {
-  const query = new URLSearchParams();
-  query.set('src', src);
-  if (width) query.set('w', width);
-  if (height) query.set('h', height);
-  if (quality) query.set('q', quality);
-
-  const url = `/_inert/image?${query.toString()}`;
-  
-  const attrs = Object.entries(rest)
-    .map(([key, val]) => `${key}="${escape(val, CONTEXT.ATTR_VALUE_DOUBLE)}"`)
-    .join(' ');
-    
-  return raw(`<img src="${url}" ${attrs} />`, true);
-}
+import { analyzeTemplateStrings, escape, CONTEXT } from './escaper.js';
+import { minifyHTML } from 'inertjs-optimizer';
+export { resolveToString } from './resolve.js';
+export { renderToStream, DeferTimeoutError } from './stream.js';
+// NOTE: index <-> stream is a cycle (stream imports RawString from here). Both
+// only touch each other's bindings at call time, by which point ESM has finished
+// initialising both modules, so the re-export above is safe.
+
+const planCache = new WeakMap();
+
+export class RawString {
+  constructor(str) {
+    this.value = str;
+  }
+  toString() {
+    return this.value;
+  }
+}
+
+/**
+ * Opt-out of HTML escaping. 
+ * Use with extreme caution.
+ * 
+ * @param {string} str Unescaped HTML string
+ * @returns {RawString}
+ */
+export function raw(str, suppressWarning = false) {
+  if (!suppressWarning && process.env.NODE_ENV !== 'production') {
+    const stack = new Error().stack;
+    // index 1 is raw(), index 2 is the caller
+    const callSite = stack && stack.split('\n')[2] ? stack.split('\n')[2].trim() : 'unknown location';
+    console.warn(`[Lens] Warning: raw() escape hatch used at ${callSite}. Ensure this string is safe.`);
+  }
+  return new RawString(str);
+}
+
+/**
+ * A slow value whose surrounding shell is allowed to flush to the browser
+ * immediately. The `fallback` is rendered into the shell as a skeleton and
+ * patched out of the DOM once `source` settles.
+ *
+ * Because the shell (and HTTP headers) are already on the wire by the time a
+ * deferred fragment settles, a rejection can no longer become a 500. Instead
+ * the slot is patched with `error` (an isolated, per-fragment error boundary)
+ * and the client is notified via the `inert:fragment:error` event. Siblings
+ * keep streaming untouched.
+ *
+ * `fallback` / `error` content is treated as trusted HTML (like `raw()`), so
+ * interpolate untrusted values through `vec\`\`` before handing them in.
+ *
+ * @param {Promise<any>|AsyncIterable<any>|object|((ctx: { signal: AbortSignal }) => any)} source
+ *   The deferred value, or a factory that produces it (called lazily with an
+ *   `{ signal }` that aborts when the response is torn down; a throw from the
+ *   factory is caught and routed to `error`).
+ * @param {object} [options]
+ * @param {string|RawString} [options.fallback] Skeleton shown while pending.
+ * @param {string|RawString|object|((err: Error) => string|RawString|object)} [options.error]
+ *   Content to patch in if `source` rejects or times out. A function receives the error.
+ * @param {number} [options.timeout]
+ *   Milliseconds to wait before failing the fragment with a `DeferTimeoutError`
+ *   (routed to `error` / `onError` like any other rejection).
+ * @returns {DeferredFragment}
+ */
+export function defer(source, options = {}) {
+  return new DeferredFragment(source, options);
+}
+
+/** Internal marker produced by {@link defer}. */
+export class DeferredFragment {
+  constructor(source, options = {}) {
+    this.type = 'VecFragment';
+    this.source = source;
+    this.fallback = options.fallback ?? null;
+    this.error = options.error ?? null;
+    this.timeout = options.timeout ?? null;
+  }
+}
+
+function isStreamable(v) {
+  return v instanceof Promise
+    || (v && typeof v[Symbol.asyncIterator] === 'function')
+    || (v && (v.type === 'VecStream' || v.type === 'VecFragment'));
+}
+
+/**
+ * Tagged template literal for Vector template engine.
+ * Safely escapes all interpolations based on their HTML context.
+ * 
+ * @param {TemplateStringsArray} strings 
+ * @param  {...any} values 
+ */
+export function vec(strings, ...values) {
+  let plan = planCache.get(strings);
+  if (!plan) {
+    plan = analyzeTemplateStrings(strings);
+    // Minify statics on the fly during template parse
+    plan.statics = plan.statics.map(staticStr => minifyHTML(staticStr));
+    planCache.set(strings, plan);
+  }
+
+  // Check if we need to stream (any value is a Promise, AsyncIterable, nested
+  // stream, or a deferred fragment).
+  const isAsync = values.some(isStreamable);
+
+  if (isAsync) {
+    return {
+      type: 'VecStream',
+      plan,
+      values
+    };
+  }
+
+  let result = plan.statics[0];
+  for (let i = 0; i < values.length; i++) {
+    const val = values[i];
+    const ctx = plan.contexts[i];
+    const attrName = plan.attrNames[i];
+
+    if (val instanceof RawString) {
+      result += val.value;
+    } else if (val && (val.type === 'VecStream' || val.type === 'VecFragment')) {
+       throw new Error('E_INERT_VECTOR_NESTED_ASYNC: Async nested vec`` found in synchronous render context.');
+    } else if (Array.isArray(val)) {
+       result += val.map(v => v instanceof RawString ? v.value : escape(v, ctx, attrName)).join('');
+    } else {
+      result += escape(val, ctx, attrName);
+    }
+    result += plan.statics[i + 1];
+  }
+  
+  // Return RawString so nested `vec` calls aren't double-escaped
+  return new RawString(result);
+}
+
+/**
+ * Generates an optimized image tag that hooks into InertJS's on-the-fly optimizer.
+ * 
+ * @param {object} props Image properties: src, width, height, quality, class, alt
+ * @returns {RawString}
+ */
+export function img({ src, width, height, quality, ...rest }) {
+  const query = new URLSearchParams();
+  query.set('src', src);
+  if (width) query.set('w', width);
+  if (height) query.set('h', height);
+  if (quality) query.set('q', quality);
+
+  const url = `/_inert/image?${query.toString()}`;
+  
+  const attrs = Object.entries(rest)
+    .map(([key, val]) => `${key}="${escape(val, CONTEXT.ATTR_VALUE_DOUBLE)}"`)
+    .join(' ');
+    
+  return raw(`<img src="${url}" ${attrs} />`, true);
+}

package/src/resolve.js

@@ -1,48 +1,66 @@
-import { escape } from './escaper.js';
-import { RawString } from './index.js';
-
-/**
- * Fully resolves a VecStream and all its asynchronous holes into a single string.
- */
-export async function resolveToString(val, ctx = 'text', attrName = '') {
-  if (val == null || val === false) return '';
-  if (typeof val === 'string' || typeof val === 'number') return escape(String(val), ctx, attrName);
-  if (val instanceof RawString) return val.value;
-  
-  if (val instanceof Promise) {
-    return resolveToString(await val, ctx, attrName);
-  }
-
-  if (Array.isArray(val)) {
-    let res = '';
-    for (const item of val) {
-      res += await resolveToString(item, ctx, attrName);
-    }
-    return res;
-  }
-
-  if (val && val.type === 'VecStream') {
-    let result = '';
-    for (let i = 0; i < val.values.length; i++) {
-      result += val.plan.statics[i];
-      
-      const part = val.values[i];
-      const nextCtx = val.plan.contexts[i];
-      const nextAttrName = val.plan.attrNames[i];
-
-      result += await resolveToString(part, nextCtx, nextAttrName);
-    }
-    result += val.plan.statics[val.plan.statics.length - 1];
-    return result;
-  }
-  
-  if (val && typeof val[Symbol.asyncIterator] === 'function') {
-    let res = '';
-    for await (const chunk of val) {
-      res += await resolveToString(chunk, ctx, attrName);
-    }
-    return res;
-  }
-
-  return escape(String(val), ctx, attrName);
-}
+import { escape } from './escaper.js';
+import { RawString } from './index.js';
+
+/**
+ * Fully resolves a VecStream and all its asynchronous holes into a single string.
+ */
+export async function resolveToString(val, ctx = 'text', attrName = '') {
+  if (val == null || val === false) return '';
+  if (typeof val === 'string' || typeof val === 'number') return escape(String(val), ctx, attrName);
+  if (val instanceof RawString) return val.value;
+  
+  if (val instanceof Promise) {
+    return resolveToString(await val, ctx, attrName);
+  }
+
+  if (val && val.type === 'VecFragment') {
+    let source = val.source;
+    try {
+      if (typeof source === 'function') source = source();
+      return await resolveToString(await source, ctx, attrName);
+    } catch (err) {
+      console.error('[InertJS] Deferred fragment rejected during buffered render:', err);
+      let content = val.error;
+      if (typeof content === 'function') {
+        try { content = content(err); } catch { content = null; }
+      }
+      if (content == null) return '';
+      if (content instanceof RawString) return content.value;
+      if (content && content.type === 'VecStream') return resolveToString(content, ctx, attrName);
+      return String(content);
+    }
+  }
+
+  if (Array.isArray(val)) {
+    let res = '';
+    for (const item of val) {
+      res += await resolveToString(item, ctx, attrName);
+    }
+    return res;
+  }
+
+  if (val && val.type === 'VecStream') {
+    let result = '';
+    for (let i = 0; i < val.values.length; i++) {
+      result += val.plan.statics[i];
+      
+      const part = val.values[i];
+      const nextCtx = val.plan.contexts[i];
+      const nextAttrName = val.plan.attrNames[i];
+
+      result += await resolveToString(part, nextCtx, nextAttrName);
+    }
+    result += val.plan.statics[val.plan.statics.length - 1];
+    return result;
+  }
+  
+  if (val && typeof val[Symbol.asyncIterator] === 'function') {
+    let res = '';
+    for await (const chunk of val) {
+      res += await resolveToString(chunk, ctx, attrName);
+    }
+    return res;
+  }
+
+  return escape(String(val), ctx, attrName);
+}

package/src/stream.js

@@ -1,142 +1,354 @@
-import { escape } from './escaper.js';
-import { RawString } from './index.js';
-
-const encoder = new TextEncoder();
-
-const PATCHER_SCRIPT = `<script nonce="[INERT_NONCE]">
-(function(){
-  const ds=document.querySelectorAll('template[data-i-fill]');
-  for(let d of ds){
-    const id=d.getAttribute('data-i-fill');
-    const target=document.getElementById('i-slot-'+id);
-    if(target){
-      target.replaceWith(d.content);
-    }
-    d.remove();
-  }
-})();
-</script>`;
-
-/**
- * Renders a VecStream (or RawString) to a WHATWG ReadableStream.
- * Handles out-of-order streaming for Promises and AsyncIterables.
- * 
- * @param {object} vecResult The result from calling vec\`\`
- * @param {string} nonce The CSP nonce for inline scripts
- * @returns {ReadableStream}
- */
-export function renderToStream(vecResult, nonce = '') {
-  if (!(vecResult && vecResult.type === 'VecStream')) {
-    const value = vecResult instanceof RawString ? vecResult.value : String(vecResult);
-    return new ReadableStream({
-      start(controller) {
-        controller.enqueue(encoder.encode(value));
-        controller.close();
-      }
-    });
-  }
-
-  const { plan, values } = vecResult;
-  let slotCounter = 0;
-  const pendingTasks = new Set();
-  
-  return new ReadableStream({
-    async start(controller) {
-      try {
-        let initialHtml = plan.statics[0];
-        
-        for (let i = 0; i < values.length; i++) {
-          const val = values[i];
-          const ctx = plan.contexts[i];
-          const attrName = plan.attrNames[i];
-
-          const isPromise = val instanceof Promise;
-          const isAsyncIter = val && typeof val[Symbol.asyncIterator] === 'function';
-          const isNestedStream = val && val.type === 'VecStream';
-
-          if (isPromise || isAsyncIter || isNestedStream) {
-            const slotId = ++slotCounter;
-            initialHtml += `<i-slot id="i-slot-${slotId}"></i-slot>`;
-            
-            const task = (async () => {
-              try {
-                if (isPromise) {
-                  const resolved = await val;
-                  let str = '';
-                  if (resolved && resolved.type === 'VecStream') {
-                    // Resolve nested stream by reading from it
-                    const nestedReadable = renderToStream(resolved, nonce);
-                    const reader = nestedReadable.getReader();
-                    let nestedHtml = '';
-                    while (true) {
-                      const { done, value } = await reader.read();
-                      if (done) break;
-                      // value is Uint8Array
-                      nestedHtml += new TextDecoder().decode(value);
-                    }
-                    str = nestedHtml;
-                  } else if (resolved instanceof RawString) {
-                    str = resolved.value;
-                  } else {
-                    str = escape(resolved, ctx, attrName);
-                  }
-                  const patch = `\n<template data-i-fill="${slotId}">${str}</template>` + 
-                                PATCHER_SCRIPT.replace('[INERT_NONCE]', nonce);
-                  controller.enqueue(encoder.encode(patch));
-                } else if (isAsyncIter) {
-                  let accumulated = '';
-                  for await (const chunk of val) {
-                    accumulated += (chunk instanceof RawString ? chunk.value : escape(chunk, ctx, attrName));
-                  }
-                  const patch = `\n<template data-i-fill="${slotId}">${accumulated}</template>` + 
-                                PATCHER_SCRIPT.replace('[INERT_NONCE]', nonce);
-                  controller.enqueue(encoder.encode(patch));
-                } else if (isNestedStream) {
-                  const nestedReadable = renderToStream(val, nonce);
-                  const reader = nestedReadable.getReader();
-                  let nestedHtml = '';
-                  while (true) {
-                    const { done, value } = await reader.read();
-                    if (done) break;
-                    nestedHtml += new TextDecoder().decode(value);
-                  }
-                  const patch = `\n<template data-i-fill="${slotId}">${nestedHtml}</template>` + 
-                                PATCHER_SCRIPT.replace('[INERT_NONCE]', nonce);
-                  controller.enqueue(encoder.encode(patch));
-                }
-              } catch (err) {
-                console.error(`[InertJS] Error streaming slot ${slotId}:`, err);
-              } finally {
-                pendingTasks.delete(task);
-                if (pendingTasks.size === 0) {
-                  controller.close();
-                }
-              }
-            })();
-            
-            pendingTasks.add(task);
-          } else {
-            // Synchronous value
-            if (val instanceof RawString) {
-              initialHtml += val.value;
-            } else if (Array.isArray(val)) {
-              initialHtml += val.map(v => v instanceof RawString ? v.value : escape(v, ctx, attrName)).join('');
-            } else {
-              initialHtml += escape(val, ctx, attrName);
-            }
-          }
-          initialHtml += plan.statics[i + 1];
-        }
-
-        // Flush the synchronous initial shell
-        controller.enqueue(encoder.encode(initialHtml));
-
-        if (pendingTasks.size === 0) {
-          controller.close();
-        }
-      } catch (err) {
-        controller.error(err);
-      }
-    }
-  });
-}
+import { escape, CONTEXT } from './escaper.js';
+import { RawString } from './index.js';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/**
+ * Error handed to the error boundary / `onError` hook when a deferred fragment
+ * exceeds its `timeout`.
+ */
+export class DeferTimeoutError extends Error {
+  constructor(slotId, ms) {
+    super(`Deferred fragment in slot ${slotId} timed out after ${ms}ms`);
+    this.name = 'DeferTimeoutError';
+    this.code = 'E_INERT_FRAGMENT_TIMEOUT';
+    this.slot = slotId;
+    this.timeout = ms;
+  }
+}
+
+function isDev() {
+  return typeof process !== 'undefined' && !!process.env && process.env.NODE_ENV !== 'production';
+}
+
+/**
+ * One inline script, emitted once into the shell. It applies every streamed
+ * `<template data-i-fill>` patch — synchronously for those already parsed, and
+ * via a MutationObserver for those that arrive later in the stream. Replaces the
+ * previous approach of re-emitting a full patcher script after every patch
+ * (which was O(n²) and multiplied inline-script surface under CSP).
+ */
+function bootstrapScript(nonce) {
+  return `<script nonce="${nonce}">
+(function(){
+  var W=window,D=document;
+  function patch(t){
+    var id=t.getAttribute('data-i-fill');
+    var slot=D.getElementById('i-slot-'+id);
+    if(slot){
+      var errored=t.hasAttribute('data-i-error');
+      slot.replaceWith(t.content);
+      if(errored){
+        var s=(W.__inert=W.__inert||{});
+        s.fragmentErrors=(s.fragmentErrors||0)+1;
+        try{W.dispatchEvent(new CustomEvent('inert:fragment:error',{detail:{slot:id}}));}catch(e){}
+      }
+    }
+    if(t.parentNode)t.remove();
+  }
+  function sweep(root){
+    var ts=(root||D).querySelectorAll('template[data-i-fill]');
+    for(var i=0;i<ts.length;i++)patch(ts[i]);
+  }
+  sweep();
+  if(W.MutationObserver){
+    var mo=new MutationObserver(function(muts){
+      for(var i=0;i<muts.length;i++){
+        var added=muts[i].addedNodes;
+        for(var j=0;j<added.length;j++){
+          var n=added[j];
+          if(n.nodeType!==1)continue;
+          if(n.tagName==='TEMPLATE'&&n.hasAttribute('data-i-fill'))patch(n);
+          else if(n.querySelector&&n.querySelector('template[data-i-fill]'))sweep(n);
+        }
+      }
+    });
+    mo.observe(D.documentElement,{childList:true,subtree:true});
+    var done=function(){sweep();mo.disconnect();};
+    if(D.readyState==='complete')done();
+    else W.addEventListener('load',done);
+  }else{
+    W.addEventListener('load',function(){sweep();});
+  }
+})();
+</script>`;
+}
+
+/** A bare patch: the bootstrap script (already in the shell) applies it. */
+function fillPatch(slotId, html, errored) {
+  return `\n<template data-i-fill="${slotId}"${errored ? ' data-i-error="1"' : ''}>${html}</template>`;
+}
+
+/**
+ * Fully drains a WHATWG ReadableStream of Uint8Array chunks into a string,
+ * always releasing the reader lock.
+ */
+async function drainStream(readable) {
+  const reader = readable.getReader();
+  let html = '';
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      html += decoder.decode(value, { stream: true });
+    }
+    html += decoder.decode();
+  } finally {
+    reader.releaseLock();
+  }
+  return html;
+}
+
+/**
+ * Resolves an already-settled value (the result of `await`ing a hole) into an
+ * HTML string, recursing through nested streams, RawStrings and arrays.
+ */
+async function valueToHtml(value, ctx, attrName, nonce, options) {
+  if (value == null || value === false) return '';
+  if (value instanceof RawString) return value.value;
+  if (value && value.type === 'VecStream') {
+    return drainStream(renderToStream(value, nonce, options));
+  }
+  if (Array.isArray(value)) {
+    let out = '';
+    for (const item of value) out += await valueToHtml(item, ctx, attrName, nonce, options);
+    return out;
+  }
+  return escape(value, ctx, attrName);
+}
+
+/** Synchronously resolves a fragment's skeleton (must be inlined into the shell). */
+function skeletonHtml(fragment) {
+  const f = fragment && fragment.fallback;
+  if (f == null) return '';
+  if (f instanceof RawString) return f.value;
+  if (typeof f === 'string') return f;
+  return '';
+}
+
+/** Resolves a fragment's error boundary content once the source has rejected. */
+async function errorBoundaryHtml(fragment, err, slotId, ctx, attrName, nonce, options) {
+  let content = fragment && fragment.error;
+  if (typeof content === 'function') {
+    try {
+      content = content(err);
+    } catch (boundaryErr) {
+      console.error('[InertJS] Fragment error boundary threw:', boundaryErr);
+      content = null;
+    }
+  }
+  if (content == null) {
+    if (isDev()) {
+      const msg = escape(err && err.message ? err.message : String(err), CONTEXT.TEXT);
+      return `<div data-inert-fragment-error style="border:1px dashed #f43f5e;background:#fff1f2;color:#9f1239;` +
+        `padding:6px 10px;font:12px/1.5 ui-monospace,monospace;border-radius:4px">` +
+        `⚠ InertJS fragment ${slotId} failed: ${msg}</div>`;
+    }
+    return '';
+  }
+  if (content instanceof RawString) return content.value;
+  if (content && content.type === 'VecStream') {
+    return drainStream(renderToStream(content, nonce, options));
+  }
+  return String(content);
+}
+
+/** Races a fragment's html production against its `timeout`, if any. */
+function withTimeout(promise, ms, slotId) {
+  if (!ms || ms <= 0) return promise;
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new DeferTimeoutError(slotId, ms)), ms);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * Renders a VecStream (or RawString) to a WHATWG ReadableStream.
+ * Handles out-of-order streaming for Promises, AsyncIterables and deferred
+ * fragments.
+ *
+ * Once the synchronous shell has been flushed, a hole that rejects can no
+ * longer surface as an HTTP error. Such a failure is isolated to its own slot:
+ * the slot is patched with the fragment's error boundary (or emptied), the
+ * client is signalled via `inert:fragment:error`, `options.onError` is invoked,
+ * and every sibling hole keeps streaming.
+ *
+ * @param {object} vecResult The result from calling vec\`\`
+ * @param {string} [nonce] The CSP nonce for inline scripts
+ * @param {object} [options]
+ * @param {(err: Error, info: { slot: number }) => void} [options.onError]
+ *   Called for every hole that rejects (or times out) after the shell flushed.
+ * @param {AbortSignal} [options.signal]
+ *   Aborting it stops the stream and is forwarded to deferred fragment
+ *   factories as `defer(({ signal }) => ...)`.
+ * @returns {ReadableStream}
+ */
+export function renderToStream(vecResult, nonce = '', options = {}) {
+  if (!(vecResult && vecResult.type === 'VecStream')) {
+    const value = vecResult instanceof RawString ? vecResult.value : String(vecResult);
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode(value));
+        controller.close();
+      }
+    });
+  }
+
+  const { plan, values } = vecResult;
+  const onError = typeof options.onError === 'function' ? options.onError : null;
+
+  // Every render has a real AbortSignal so `defer` factories can always rely on
+  // `({ signal })`. It fires when the caller's signal fires, when the consumer
+  // cancels the stream, or when a write reveals the client has gone away.
+  const abort = new AbortController();
+  const signal = abort.signal;
+  if (options.signal) {
+    if (options.signal.aborted) abort.abort();
+    else options.signal.addEventListener('abort', () => abort.abort(), { once: true });
+  }
+
+  let slotCounter = 0;
+  const pendingTasks = new Set();
+
+  return new ReadableStream({
+    async start(controller) {
+      let closed = false;
+
+      const enqueue = (str) => {
+        if (closed || signal.aborted) return;
+        try {
+          controller.enqueue(encoder.encode(str));
+        } catch {
+          // Client went away; stop trying to write and let fragments bail.
+          closed = true;
+          abort.abort();
+        }
+      };
+
+      const closeController = () => {
+        if (closed) return;
+        closed = true;
+        try {
+          controller.close();
+        } catch {
+          /* already closed / errored */
+        }
+      };
+
+      if (signal.aborted) {
+        closeController();
+        return;
+      }
+      signal.addEventListener('abort', closeController, { once: true });
+
+      try {
+        let initialHtml = plan.statics[0];
+
+        for (let i = 0; i < values.length; i++) {
+          const val = values[i];
+          const ctx = plan.contexts[i];
+          const attrName = plan.attrNames[i];
+
+          const isPromise = val instanceof Promise;
+          const isAsyncIter = val && typeof val[Symbol.asyncIterator] === 'function';
+          const isNestedStream = val && val.type === 'VecStream';
+          const isFragment = val && val.type === 'VecFragment';
+
+          if (isPromise || isAsyncIter || isNestedStream || isFragment) {
+            const slotId = ++slotCounter;
+            const fragment = isFragment ? val : null;
+            initialHtml += `<i-slot id="i-slot-${slotId}">${fragment ? skeletonHtml(fragment) : ''}</i-slot>`;
+
+            const task = (async () => {
+              try {
+                const build = (async () => {
+                  let source = fragment ? fragment.source : val;
+                  if (typeof source === 'function') source = source({ signal });
+
+                  if (source && source.type === 'VecStream') {
+                    return drainStream(renderToStream(source, nonce, options));
+                  }
+                  if (source && typeof source[Symbol.asyncIterator] === 'function') {
+                    let accumulated = '';
+                    for await (const chunk of source) {
+                      accumulated += chunk instanceof RawString
+                        ? chunk.value
+                        : escape(chunk, ctx, attrName);
+                    }
+                    return accumulated;
+                  }
+                  return valueToHtml(await source, ctx, attrName, nonce, options);
+                })();
+                build.catch(() => {}); // a lost timeout race must not warn
+
+                const html = await withTimeout(build, fragment && fragment.timeout, slotId);
+                enqueue(fillPatch(slotId, html, false));
+              } catch (err) {
+                console.error(
+                  `[InertJS] Deferred fragment in slot ${slotId} failed after the shell was flushed:`,
+                  err
+                );
+                if (onError) {
+                  try {
+                    onError(err, { slot: slotId });
+                  } catch (hookErr) {
+                    console.error('[InertJS] renderToStream onError hook threw:', hookErr);
+                  }
+                }
+                let boundary = '';
+                try {
+                  boundary = await errorBoundaryHtml(fragment, err, slotId, ctx, attrName, nonce, options);
+                } catch (boundaryErr) {
+                  console.error('[InertJS] Fragment error boundary failed:', boundaryErr);
+                }
+                enqueue(fillPatch(slotId, boundary, true));
+              } finally {
+                pendingTasks.delete(task);
+                if (pendingTasks.size === 0) closeController();
+              }
+            })();
+
+            pendingTasks.add(task);
+          } else {
+            // Synchronous value
+            if (val instanceof RawString) {
+              initialHtml += val.value;
+            } else if (Array.isArray(val)) {
+              initialHtml += val.map(v => v instanceof RawString ? v.value : escape(v, ctx, attrName)).join('');
+            } else {
+              initialHtml += escape(val, ctx, attrName);
+            }
+          }
+          initialHtml += plan.statics[i + 1];
+        }
+
+        // One patcher for the whole document, only when something actually streams.
+        if (slotCounter > 0) {
+          initialHtml += bootstrapScript(nonce);
+        }
+
+        // Flush the synchronous initial shell
+        enqueue(initialHtml);
+
+        if (pendingTasks.size === 0) {
+          closeController();
+        }
+      } catch (err) {
+        // Reached only while the shell is still being built (nothing flushed yet),
+        // so it is safe to fail the whole response here.
+        try {
+          controller.error(err);
+        } catch {
+          /* already torn down */
+        }
+      }
+    },
+    cancel() {
+      // Consumer walked away: let in-flight fragment work abort itself.
+      abort.abort();
+    }
+  });
+}

package/test/streaming-error.test.js

@@ -0,0 +1,202 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { vec, raw, defer } from '../src/index.js';
+import { renderToStream } from '../src/stream.js';
+import { resolveToString } from '../src/resolve.js';
+
+const decoder = new TextDecoder();
+
+/** Fully drains a stream to a string, failing the test rather than hanging forever. */
+async function collect(stream, ms = 2000) {
+  const reader = stream.getReader();
+  let out = '';
+  const timer = setTimeout(() => reader.cancel(new Error('stream did not close')), ms);
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      out += decoder.decode(value, { stream: true });
+    }
+    out += decoder.decode();
+  } finally {
+    clearTimeout(timer);
+  }
+  return out;
+}
+
+test('Out-of-order streaming: fragment errors after shell flush', async (t) => {
+  await t.test('a rejected bare promise does not hang the stream and resolves its slot', async () => {
+    const boom = Promise.reject(new Error('db exploded'));
+    // Attach a catch so Node does not print an unhandled rejection for the test input.
+    boom.catch(() => {});
+
+    const stream = renderToStream(vec`<main>${boom}</main>`, 'n0');
+    const html = await collect(stream);
+
+    assert.ok(html.includes('<i-slot id="i-slot-1">'), 'shell still flushes with the skeleton slot');
+    assert.ok(html.includes('data-i-fill="1" data-i-error="1"'), 'slot 1 receives an error patch');
+    assert.ok(html.includes('inert:fragment:error'), 'patcher signals the client');
+  });
+
+  await t.test('one failing fragment does not block a healthy sibling', async () => {
+    const bad = Promise.reject(new Error('nope'));
+    bad.catch(() => {});
+    const good = Promise.resolve(raw('<p>loaded</p>'));
+
+    const stream = renderToStream(vec`<div>${bad}</div><div>${good}</div>`, 'n1');
+    const html = await collect(stream);
+
+    assert.ok(html.includes('data-i-fill="1" data-i-error="1"'), 'slot 1 errored');
+    assert.match(html, /data-i-fill="2"(?!.*data-i-error)/, 'slot 2 filled normally');
+    assert.ok(html.includes('<p>loaded</p>'), 'healthy fragment content is present');
+  });
+
+  await t.test('defer() renders the fallback skeleton into the shell', async () => {
+    const slow = defer(new Promise(() => {}), { fallback: raw('<span class="skeleton"></span>') });
+    // never resolves -> read only the first chunk (the shell)
+    const reader = renderToStream(vec`<main>${slow}</main>`, 'n2').getReader();
+    const { value } = await reader.read();
+    await reader.cancel();
+    const shell = decoder.decode(value);
+
+    assert.ok(shell.includes('<i-slot id="i-slot-1"><span class="skeleton"></span></i-slot>'));
+  });
+
+  await t.test('defer().error is patched in when the source rejects', async () => {
+    const frag = defer(() => Promise.reject(new Error('timeout')), {
+      fallback: raw('<span>loading…</span>'),
+      error: (err) => vec`<p class="err">${err.message}</p>`
+    });
+
+    const stream = renderToStream(vec`<main>${frag}</main>`, 'n3');
+    const html = await collect(stream);
+
+    assert.ok(html.includes('data-i-error="1"'), 'error patch emitted');
+    assert.ok(html.includes('<p class="err">timeout</p>'), 'error boundary content rendered and escaped via vec');
+  });
+
+  await t.test('a throwing lazy factory is routed to the error boundary', async () => {
+    const frag = defer(() => { throw new Error('sync throw'); }, {
+      error: raw('<p>failed</p>')
+    });
+
+    const html = await collect(renderToStream(vec`<main>${frag}</main>`, 'n4'));
+    assert.ok(html.includes('data-i-error="1"'));
+    assert.ok(html.includes('<p>failed</p>'));
+  });
+
+  await t.test('onError hook is invoked with the slot id', async () => {
+    const seen = [];
+    const bad = Promise.reject(new Error('kaboom'));
+    bad.catch(() => {});
+
+    const stream = renderToStream(vec`<main>${bad}</main>`, 'n5', {
+      onError: (err, info) => seen.push([err.message, info.slot])
+    });
+    await collect(stream);
+
+    assert.deepStrictEqual(seen, [['kaboom', 1]]);
+  });
+
+  await t.test('resolveToString buffers a deferred fragment and its error boundary', async () => {
+    const ok = defer(Promise.resolve(raw('<b>hi</b>')));
+    assert.strictEqual(await resolveToString(vec`<p>${ok}</p>`), '<p><b>hi</b></p>');
+
+    const failed = defer(() => Promise.reject(new Error('x')), { error: raw('<i>oops</i>') });
+    assert.strictEqual(await resolveToString(vec`<p>${failed}</p>`), '<p><i>oops</i></p>');
+  });
+});
+
+test('Out-of-order streaming: hardening (beta.8)', async (t) => {
+  await t.test('one bootstrap patcher script, patches are bare templates', async () => {
+    const a = Promise.resolve(raw('<p>a</p>'));
+    const b = Promise.resolve(raw('<p>b</p>'));
+    const html = await collect(renderToStream(vec`<div>${a}</div><div>${b}</div>`, 'nn'));
+
+    const scripts = html.match(/<script nonce="nn">/g) || [];
+    assert.strictEqual(scripts.length, 1, 'exactly one inline script');
+    assert.ok(html.includes('MutationObserver'), 'bootstrap installs a MutationObserver');
+    assert.match(html, /<template data-i-fill="1"><p>a<\/p><\/template>/);
+    assert.match(html, /<template data-i-fill="2"><p>b<\/p><\/template>/);
+  });
+
+  await t.test('no patcher script when nothing streams', async () => {
+    const html = await collect(renderToStream(vec`<p>${Promise.resolve('x')}</p>`, 'z'));
+    // one slot -> one script; a fully sync template never reaches renderToStream's stream path
+    assert.ok(html.includes('<script nonce="z">'));
+    const sync = await collect(renderToStream(raw('<p>hi</p>'), 'z'));
+    assert.strictEqual(sync, '<p>hi</p>');
+  });
+
+  await t.test('defer timeout patches the error boundary and closes the stream', async () => {
+    const frag = defer(new Promise(() => {}), { timeout: 40, error: raw('<p>too slow</p>') });
+    const html = await collect(renderToStream(vec`<main>${frag}</main>`, 'n'), 2000);
+    assert.ok(html.includes('data-i-error="1"'));
+    assert.ok(html.includes('<p>too slow</p>'));
+  });
+
+  await t.test('timeout surfaces as DeferTimeoutError on the onError hook', async () => {
+    const seen = [];
+    const frag = defer(new Promise(() => {}), { timeout: 30 });
+    await collect(renderToStream(vec`<main>${frag}</main>`, 'n', {
+      onError: (err) => seen.push(err)
+    }), 2000);
+    assert.strictEqual(seen.length, 1);
+    assert.strictEqual(seen[0].code, 'E_INERT_FRAGMENT_TIMEOUT');
+    assert.strictEqual(seen[0].slot, 1);
+  });
+
+  await t.test('abort signal stops the stream', async () => {
+    const ac = new AbortController();
+    const frag = defer(new Promise(() => {}), { fallback: raw('<i>loading</i>') });
+    const reader = renderToStream(vec`<main>${frag}</main>`, 'n', { signal: ac.signal }).getReader();
+
+    const shell = decoder.decode((await reader.read()).value);
+    assert.ok(shell.includes('i-slot-1'));
+    ac.abort();
+    assert.strictEqual((await reader.read()).done, true, 'closed after abort');
+  });
+
+  await t.test('a pre-aborted signal yields an immediately-closed stream', async () => {
+    const ac = new AbortController();
+    ac.abort();
+    const reader = renderToStream(vec`<main>${Promise.resolve('x')}</main>`, 'n', { signal: ac.signal }).getReader();
+    assert.strictEqual((await reader.read()).done, true);
+  });
+
+  await t.test('fragment factory receives an abort signal', async () => {
+    let received;
+    const frag = defer(({ signal }) => { received = signal; return Promise.resolve(raw('ok')); });
+    await collect(renderToStream(vec`<main>${frag}</main>`, 'n'));
+    assert.ok(received && typeof received.aborted === 'boolean');
+  });
+
+  await t.test('dev mode: a boundary-less failure renders a visible marker', async () => {
+    const prev = process.env.NODE_ENV;
+    delete process.env.NODE_ENV;
+    try {
+      const bad = Promise.reject(new Error('kaboom <x>'));
+      bad.catch(() => {});
+      const html = await collect(renderToStream(vec`<main>${bad}</main>`, 'n'));
+      assert.ok(html.includes('data-inert-fragment-error'));
+      assert.ok(html.includes('kaboom &lt;x&gt;'), 'error message is escaped');
+    } finally {
+      if (prev !== undefined) process.env.NODE_ENV = prev;
+    }
+  });
+
+  await t.test('production mode: a boundary-less failure renders nothing visible', async () => {
+    const prev = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+    try {
+      const bad = Promise.reject(new Error('kaboom'));
+      bad.catch(() => {});
+      const html = await collect(renderToStream(vec`<main>${bad}</main>`, 'n'));
+      assert.ok(html.includes('data-i-fill="1" data-i-error="1"'));
+      assert.ok(!html.includes('data-inert-fragment-error'));
+      assert.match(html, /<template data-i-fill="1" data-i-error="1"><\/template>/);
+    } finally {
+      if (prev !== undefined) process.env.NODE_ENV = prev; else delete process.env.NODE_ENV;
+    }
+  });
+});