@tinvar/renderer 0.0.0-stage → 0.4.1

package/src/head.js

@@ -0,0 +1,524 @@
+// One title, and one meta tag and one link of each key, in the document's
+// head.
+//
+// tinvar-spec.md, "Operations and tooling": "React 19 hoists <title> and
+// <meta> from components; add key-based dedupe, one title, a global title
+// template, and PHP-rendered fallback tags marked for replacement."
+//
+// React writes every hoisted tag into <head> as the shell flushes. The
+// components in @tinvar/react/head mark each with its key and its depth in
+// the route; this keeps, for each key, the deepest -- the last among equals,
+// as React rendered them -- and writes PHP's fallback tags first, marked,
+// for any of them to replace. Only the head is held to do it, never the
+// body: the shell is flushed whole, so the head is never waiting on more
+// than the rest of its own flush.
+//
+// A link <HeadLink> marked takes part by its key. One nothing marked -- a
+// raw <link> a component or the document wrote -- takes part at the
+// document's depth, as a raw <title> does, keyed as <HeadLink> would key
+// it, unless it is one of React's own resources: a stylesheet, a preload,
+// a module preload, a preconnect, a DNS prefetch or a prefetch. Those React
+// writes for itself, dedupes by href itself and finds again by href when it
+// hydrates, so they are left exactly as written.
+//
+// Only here, on the server, where a crawler reads the head. In the browser
+// a raw link is React's to hoist and to remove; one dropped here is put
+// back as the page hydrates, and a page a navigation mounts adds its own
+// beside the layout's. A link that changes with the page belongs in a
+// <HeadLink>, which agrees with the others in the browser too.
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** Mirrors @tinvar/react/head and Tinvar\Protocol\HeadTag. */
+const FALLBACK = 'data-tinvar-head="fallback"';
+const KEY_ATTRIBUTE = 'data-tinvar-key';
+const DEPTH_ATTRIBUTE = 'data-tinvar-depth';
+
+/** How much of a document is held looking for the end of its head before it is sent as it is. */
+const MAX_HEAD_BYTES = 512 * 1024;
+
+/** The most fallback tags one render writes; PHP sends a handful. */
+const MAX_FALLBACKS = 32;
+
+const END_OF_HEAD = encoder.encode('</head>');
+
+/** @param {string} value */
+function escape(value) {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/**
+ * PHP's fallback tags, as markup marked for replacement. Only a title or a
+ * meta tag, only attribute names of an attribute's shape and never a
+ * handler, every value escaped: the frame is PHP's, but what reaches the
+ * document is decided where the markup is written.
+ *
+ * @param {unknown} head the render frame's `head`
+ * @returns {string}
+ */
+export function fallbackTags(head) {
+  if (!Array.isArray(head)) return '';
+  let out = '';
+  for (const entry of head.slice(0, MAX_FALLBACKS)) {
+    if (entry === null || typeof entry !== 'object') continue;
+    if (entry.tag === 'title' && typeof entry.text === 'string') {
+      out += `<title ${FALLBACK}>${escape(entry.text)}</title>`;
+      continue;
+    }
+    if (entry.tag !== 'meta' || entry.attributes === null || typeof entry.attributes !== 'object') continue;
+    let attributes = '';
+    for (const [name, value] of Object.entries(entry.attributes)) {
+      if (!/^[a-z][a-z0-9:_.-]*$/.test(name) || name.startsWith('on') || typeof value !== 'string') continue;
+      attributes += ` ${name}="${escape(value)}"`;
+    }
+    out += `<meta${attributes} ${FALLBACK}>`;
+  }
+  return out;
+}
+
+/** @param {string} tag the opening tag @returns {Record<string, string>} */
+function attributesOf(tag) {
+  const attributes = {};
+  const pattern = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+  // Past the tag's name.
+  const body = tag.replace(/^<\s*[a-zA-Z]+/, '').replace(/\/?>$/, '');
+  for (const match of body.matchAll(pattern)) {
+    attributes[match[1].toLowerCase()] = match[2] ?? match[3] ?? match[4] ?? '';
+  }
+  return attributes;
+}
+
+/**
+ * Rels of the links React writes for its own resources, which a raw link
+ * of any of them is taken to be. Mirrors nothing in @tinvar/react/head:
+ * <HeadLink> renders a stylesheet unkeyed for the same reason.
+ */
+const RESOURCE_RELS = new Set([
+  'stylesheet',
+  'preload',
+  'modulepreload',
+  'preconnect',
+  'dns-prefetch',
+  'prefetch',
+]);
+
+/** Rels whose links are the page's icon at a size, as @tinvar/react/head's linkKey() has them. */
+const ICON_RELS = new Set([
+  'icon',
+  'shortcut icon',
+  'apple-touch-icon',
+  'apple-touch-icon-precomposed',
+  'mask-icon',
+]);
+
+/**
+ * The key a raw link is deduplicated by: @tinvar/react/head's linkKey() for
+ * the same attributes, so a raw canonical and a <HeadLink> canonical are
+ * one key. Null for a link that takes no part: one of React's resources
+ * (any rel naming one, `alternate stylesheet` too), or one with nothing to
+ * key it by.
+ *
+ * @param {Record<string, string>} attributes
+ * @returns {string | null}
+ */
+export function rawLinkKey(attributes) {
+  const rel = (attributes.rel ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+  if (rel === '' || rel.split(' ').some((token) => RESOURCE_RELS.has(token))) return null;
+  if (rel === 'canonical') return 'link:canonical';
+
+  const hrefLang = attributes.hreflang ?? '';
+  if (rel === 'alternate' && hrefLang !== '') return `link:alternate:${hrefLang.toLowerCase()}`;
+  if (ICON_RELS.has(rel)) {
+    const sizes = (attributes.sizes ?? '').trim().toLowerCase();
+    const media = (attributes.media ?? '').trim();
+    const type = (attributes.type ?? '').trim().toLowerCase();
+    return `link:${rel}:${sizes}:${media}:${type}`;
+  }
+  // The href as React wrote it, escaped as it escapes a marked link's key.
+  return attributes.href ? `link:${rel}:${attributes.href}` : null;
+}
+
+/**
+ * The key a head tag is deduplicated by, and how deep in the route it was
+ * rendered: a fallback below everything, a tag no component marked -- the
+ * document's own, a bare <title>, a raw link -- at the document's depth, 0.
+ *
+ * @returns {{ key: string, depth: number } | null}
+ */
+function identify(name, attributes) {
+  const fallback = attributes['data-tinvar-head'] === 'fallback';
+  const depth = fallback ? -Infinity : Number(attributes[DEPTH_ATTRIBUTE] ?? 0) || 0;
+  if (name === 'title') return { key: 'title', depth };
+  if (attributes[KEY_ATTRIBUTE]) return { key: attributes[KEY_ATTRIBUTE], depth };
+  if (name === 'link') {
+    const key = rawLinkKey(attributes);
+    return key === null ? null : { key, depth: 0 };
+  }
+  if (attributes.name !== undefined) return { key: `name:${attributes.name}`, depth };
+  if (attributes.property !== undefined) return { key: `property:${attributes.property}`, depth };
+  if (attributes['http-equiv'] !== undefined) {
+    return { key: `http-equiv:${attributes['http-equiv'].toLowerCase()}`, depth };
+  }
+  if (attributes.charset !== undefined) return { key: 'charset', depth };
+  return null;
+}
+
+/**
+ * Elements whose body is text, never tags: raw text and RCDATA, as a
+ * browser with scripting reads them, and plaintext, whose body is the rest
+ * of the document.
+ */
+const TEXT_BODIES = new Set([
+  'script',
+  'style',
+  'noscript',
+  'textarea',
+  'title',
+  'xmp',
+  'iframe',
+  'noembed',
+  'noframes',
+  'plaintext',
+]);
+
+/** Elements with no end tag, which leave the head's top level where it was. */
+const VOID = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'keygen',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
+
+const WHITESPACE = /[\t\n\f\r ]/;
+
+/**
+ * Lower case as HTML has it: ASCII letters only. String#toLowerCase()
+ * lowers others too -- the Kelvin sign to a `k`, `İ` to two code units --
+ * and would read as `link` a name no browser does.
+ *
+ * @param {string} value
+ */
+function asciiLower(value) {
+  return value.replace(/[A-Z]+/g, (letters) => letters.toLowerCase());
+}
+
+/**
+ * A tag from just past its name, as the HTML tokenizer reads it: to the
+ * first `>` outside a quoted attribute value. Null if the head ends first.
+ *
+ * @param {string} html
+ * @param {number} at just past the tag's name
+ * @returns {{ attributes: Record<string, string>, end: number } | null}
+ */
+function readTag(html, at) {
+  /** @type {Record<string, string>} */
+  const attributes = {};
+  let i = at;
+  for (;;) {
+    while (i < html.length && (WHITESPACE.test(html[i]) || html[i] === '/')) i++;
+    if (i >= html.length) return null;
+    if (html[i] === '>') return { attributes, end: i + 1 };
+
+    const nameStart = i++;
+    while (i < html.length && !WHITESPACE.test(html[i]) && !'/>='.includes(html[i])) i++;
+    const name = asciiLower(html.slice(nameStart, i));
+    while (i < html.length && WHITESPACE.test(html[i])) i++;
+    let value = '';
+    if (html[i] === '=') {
+      i++;
+      while (i < html.length && WHITESPACE.test(html[i])) i++;
+      const quote = html[i];
+      if (quote === '"' || quote === "'") {
+        const close = html.indexOf(quote, i + 1);
+        if (close === -1) return null;
+        value = html.slice(i + 1, close);
+        i = close + 1;
+      } else {
+        const valueStart = i;
+        while (i < html.length && !WHITESPACE.test(html[i]) && html[i] !== '>') i++;
+        value = html.slice(valueStart, i);
+      }
+    }
+    // The first of two attributes of one name is the one a browser keeps.
+    if (!Object.hasOwn(attributes, name)) attributes[name] = value;
+  }
+}
+
+/** Where a tag's name ends: at whitespace, a `/` or a `>`. */
+function endOfName(html, at) {
+  let i = at;
+  while (i < html.length && !WHITESPACE.test(html[i]) && !'/>'.includes(html[i])) i++;
+  return i;
+}
+
+/**
+ * Where the end tag that closes a text body ends: the first `</name`, in
+ * any ASCII case, followed by what can end a tag's name. Matched in the
+ * head itself, never a lowered copy, whose indices need not be the head's.
+ * -1 if the body runs to the end of the head.
+ *
+ * @param {string} html
+ * @param {string} name a name of TEXT_BODIES
+ * @param {number} from where the body starts
+ */
+function endOfTextBody(html, name, from) {
+  // No `u` flag: case-insensitive then folds no character outside ASCII
+  // into one inside it, as HTML's ASCII case-insensitivity does not.
+  const end = new RegExp(`</${name}(?=[\\t\\n\\f\\r />]|$)`, 'gi');
+  end.lastIndex = from;
+  const match = end.exec(html);
+  if (match === null) return -1;
+  return readTag(html, match.index + match[0].length)?.end ?? -1;
+}
+
+/**
+ * The titles, metas and links at the head's top level, each whole, as a
+ * browser tokenises the head: never one inside a comment, an attribute's
+ * value, the text body of a style, a script or the like, or an element
+ * still open around it.
+ *
+ * Null wherever this reading could differ from a browser's, and the head
+ * is then left exactly as it came: cutting a tag out of a head read wrongly
+ * can put the text either side of it together into markup. So a script
+ * whose body holds `<!--` (its escaped states, where `</script>` need not
+ * end it), svg or math (foreign content, whose style is no text body), a
+ * text body, comment or tag the head ends inside, plaintext, and a bare
+ * `<`, which React never writes.
+ *
+ * @param {string} html what is between <head> and </head>
+ * @returns {{ name: string, attributes: Record<string, string>, start: number, end: number }[] | null}
+ */
+function topLevelTags(html) {
+  const tags = [];
+  let depth = 0;
+  let i = 0;
+  while (i < html.length) {
+    const start = html.indexOf('<', i);
+    if (start === -1) break;
+    const next = html[start + 1] ?? '';
+
+    if (html.startsWith('<!--', start)) {
+      if (html.startsWith('>', start + 4)) i = start + 5;
+      else if (html.startsWith('->', start + 4)) i = start + 6;
+      else {
+        const close = /--!?>/g;
+        close.lastIndex = start + 4;
+        const match = close.exec(html);
+        if (match === null) return null;
+        i = match.index + match[0].length;
+      }
+      continue;
+    }
+    if (next === '!' || next === '?' || (next === '/' && !/[a-zA-Z>]/.test(html[start + 2] ?? ''))) {
+      // A bogus comment, to the first `>`.
+      const close = html.indexOf('>', start + 2);
+      if (close === -1) return null;
+      i = close + 1;
+      continue;
+    }
+    if (next === '/') {
+      if (html[start + 2] === '>') {
+        i = start + 3;
+        continue;
+      }
+      const nameEnd = endOfName(html, start + 2);
+      const tag = readTag(html, nameEnd);
+      if (tag === null) return null;
+      if (!VOID.has(asciiLower(html.slice(start + 2, nameEnd)))) depth = Math.max(0, depth - 1);
+      i = tag.end;
+      continue;
+    }
+    if (!/[a-zA-Z]/.test(next)) return null;
+
+    const nameEnd = endOfName(html, start + 1);
+    const name = asciiLower(html.slice(start + 1, nameEnd));
+    const tag = readTag(html, nameEnd);
+    if (tag === null || name === 'plaintext' || name === 'svg' || name === 'math') return null;
+
+    if (TEXT_BODIES.has(name)) {
+      const end = endOfTextBody(html, name, tag.end);
+      if (end === -1) return null;
+      if (name === 'script' && html.slice(tag.end, end).includes('<!--')) return null;
+      if (name === 'title' && depth === 0) tags.push({ name, attributes: tag.attributes, start, end });
+      i = end;
+      continue;
+    }
+    if (name === 'meta' || name === 'link') {
+      if (depth === 0) tags.push({ name, attributes: tag.attributes, start, end: tag.end });
+    } else if (!VOID.has(name)) {
+      depth++;
+    }
+    i = tag.end;
+  }
+  return tags;
+}
+
+/**
+ * The head's markup with one tag of each key: the deepest, the last among
+ * equals. A head read with any doubt (topLevelTags()) is left as it came.
+ *
+ * @param {string} head what is between <head> and </head>
+ * @returns {string}
+ */
+export function dedupeHead(head) {
+  const found = topLevelTags(head);
+  if (found === null) return head;
+  const tags = [];
+  for (const tag of found) {
+    const id = identify(tag.name, tag.attributes);
+    if (id !== null) tags.push({ ...id, start: tag.start, end: tag.end });
+  }
+
+  /** @type {Map<string, typeof tags[number]>} */
+  const winners = new Map();
+  for (const tag of tags) {
+    const best = winners.get(tag.key);
+    if (best === undefined || tag.depth >= best.depth) winners.set(tag.key, tag);
+  }
+
+  let out = '';
+  let at = 0;
+  for (const tag of tags) {
+    if (winners.get(tag.key) === tag) continue;
+    out += head.slice(at, tag.start);
+    at = tag.end;
+  }
+  return out + head.slice(at);
+}
+
+/**
+ * The document with PHP's fallbacks first in its head, and one tag of
+ * each key there.
+ *
+ * @param {string} document the document up to and including `</head>`
+ * @param {string} fallbacks from fallbackTags()
+ */
+export function resolveHead(document, fallbacks) {
+  const open = /<head(?:\s[^>]*)?>/i.exec(document);
+  const close = asciiLower(document).lastIndexOf('</head>');
+  if (open === null || close < open.index) return document;
+
+  // After the charset, when the head starts with it: a browser looks for
+  // the encoding in the document's first bytes, so nothing goes ahead of it.
+  const start = open.index + open[0].length;
+  const charset = /^<meta\s+charset\s*=[^>]*>/i.exec(document.slice(start, close));
+  const at = start + (charset ? charset[0].length : 0);
+  return document.slice(0, at) + dedupeHead(fallbacks + document.slice(at, close)) + document.slice(close);
+}
+
+/** Where `</head>` ends in `bytes`, or -1. ASCII, so found in the bytes, never cutting a character. */
+function endOfHead(bytes) {
+  outer: for (let i = 0; i + END_OF_HEAD.length <= bytes.length; i++) {
+    for (let j = 0; j < END_OF_HEAD.length; j++) {
+      const byte = bytes[i + j] >= 0x41 && bytes[i + j] <= 0x5a ? bytes[i + j] + 0x20 : bytes[i + j];
+      if (byte !== END_OF_HEAD[j]) continue outer;
+    }
+    return i + END_OF_HEAD.length;
+  }
+  return -1;
+}
+
+/**
+ * The modules a document's head preloads, in its order: the client entry,
+ * then the chunks of the client components the page renders, as React
+ * wrote them from the payload's client references.
+ *
+ * @param {string} document
+ * @returns {string[]}
+ */
+export function modulePreloads(document) {
+  const head = document.slice(0, Math.max(0, asciiLower(document).lastIndexOf('</head>')));
+  const out = [];
+  for (const match of head.matchAll(/<link\b[^>]*>/gi)) {
+    const attributes = attributesOf(match[0]);
+    if (attributes.rel?.toLowerCase() === 'modulepreload' && attributes.href) out.push(attributes.href);
+  }
+  return [...new Set(out)];
+}
+
+/**
+ * The HTML stream with its head resolved: held until `</head>` arrives,
+ * then sent with the fallbacks written and the duplicates dropped, and
+ * everything after it passed through untouched.
+ *
+ * @param {ReadableStream<Uint8Array>} html
+ * @param {unknown} head the render frame's `head`
+ * @param {(resolved: { preload: string[] }) => void} [onResolved] told, once,
+ *        what the resolved head preloads -- for PHP's Link header
+ * @returns {ReadableStream<Uint8Array>}
+ */
+export function withHead(html, head, onResolved) {
+  const fallbacks = fallbackTags(head);
+  // What is held, as it came: joined once, when `</head>` is found, and
+  // searched only where the newest chunk could finish it -- copying and
+  // rescanning the whole on every chunk made a long head quadratic.
+  /** @type {Uint8Array[]} */
+  let held = [];
+  let heldBytes = 0;
+  let tail = new Uint8Array(0);
+  let resolved = false;
+
+  const join = () => {
+    const joined = new Uint8Array(heldBytes);
+    let at = 0;
+    for (const piece of held) {
+      joined.set(piece, at);
+      at += piece.length;
+    }
+    held = [];
+    heldBytes = 0;
+    return joined;
+  };
+
+  return html.pipeThrough(
+    new TransformStream({
+      transform(chunk, controller) {
+        if (resolved) {
+          controller.enqueue(chunk);
+          return;
+        }
+        const window = new Uint8Array(tail.length + chunk.length);
+        window.set(tail, 0);
+        window.set(chunk, tail.length);
+        const windowStart = heldBytes - tail.length;
+        held.push(chunk);
+        heldBytes += chunk.length;
+
+        const found = endOfHead(window);
+        if (found === -1) {
+          tail = window.subarray(Math.max(0, window.length - (END_OF_HEAD.length - 1)));
+          // No head in what a head could be: a document of some other
+          // shape, sent as it came.
+          if (heldBytes > MAX_HEAD_BYTES) {
+            controller.enqueue(join());
+            resolved = true;
+          }
+          return;
+        }
+
+        const bytes = join();
+        const end = windowStart + found;
+        const resolvedHead = resolveHead(decoder.decode(bytes.subarray(0, end)), fallbacks);
+        onResolved?.({ preload: modulePreloads(resolvedHead) });
+        controller.enqueue(encoder.encode(resolvedHead));
+        if (end < bytes.length) controller.enqueue(bytes.subarray(end));
+        resolved = true;
+      },
+      flush(controller) {
+        if (heldBytes > 0) controller.enqueue(join());
+      },
+    }),
+  );
+}