@bquery/bquery 1.10.0 → 1.11.0

package/src/ssr/hash.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared hashing helpers used by the SSR renderer and the client-side
+ * hydration mismatch verifier.
+ *
+ * The hash is intentionally cheap (DJB2 → base36) — its goal is to spot
+ * Server↔Client divergence in dev, not to provide cryptographic guarantees.
+ *
+ * @module bquery/ssr
+ */
+
+/**
+ * Computes a stable, very small hash for a string. Used to attach a hydration
+ * annotation that the client can compare against during dev-time hydration.
+ *
+ * Collisions are acceptable here: the goal is a mismatch *warning*, not
+ * security.
+ *
+ * @internal
+ */
+export const cheapHash = (input: string): string => {
+  let h = 5381;
+  for (let i = 0; i < input.length; i++) {
+    h = ((h << 5) + h + input.charCodeAt(i)) | 0;
+  }
+  return (h >>> 0).toString(36);
+};
+
+/**
+ * The attribute that holds the directive-signature hash on a server-rendered
+ * element. Public name so userland can read/write it deterministically.
+ */
+export const HYDRATION_HASH_ATTR = 'data-bq-h';
+
+/**
+ * Collects the directive signature for a virtual element (used by the pure
+ * renderer).
+ *
+ * @internal
+ */
+export const collectDirectiveSignatureFromAttrs = (
+  attributeOrder: readonly string[],
+  attributes: Readonly<Record<string, string | undefined>>,
+  prefix: string
+): string => {
+  const parts: string[] = [];
+  for (const name of attributeOrder) {
+    if (name === HYDRATION_HASH_ATTR) continue;
+    if (name.startsWith(`${prefix}-`) || name.startsWith(':')) {
+      parts.push(`${name}=${attributes[name] ?? ''}`);
+    }
+  }
+  return parts.join('|');
+};
+
+/**
+ * Collects the directive signature for a real DOM `Element`. Used by the
+ * client-side mismatch verifier and the DOM-backed renderer.
+ *
+ * @internal
+ */
+export const collectDirectiveSignatureFromElement = (el: Element, prefix: string): string => {
+  const parts: string[] = [];
+  // Iterate in attribute insertion order to match the pure renderer.
+  for (const attr of Array.from(el.attributes)) {
+    if (attr.name === HYDRATION_HASH_ATTR) continue;
+    if (attr.name.startsWith(`${prefix}-`) || attr.name.startsWith(':')) {
+      parts.push(`${attr.name}=${attr.value}`);
+    }
+  }
+  return parts.join('|');
+};

package/src/ssr/head.ts

@@ -0,0 +1,240 @@
+/**
+ * Head manager for SSR.
+ *
+ * Collects `<title>`, `<meta>`, `<link>` and inline `<script>` directives that
+ * a render path wants to inject into the document head, then serialises them
+ * as a single HTML string. The same descriptor shape is reused by the
+ * server-side head manager methods across SSR entry points.
+ *
+ * @module bquery/ssr
+ */
+
+import { isPrototypePollutionKey } from '../core/utils/object';
+
+const escapeAttr = (value: string): string =>
+  value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+const escapeText = (value: string): string =>
+  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+const escapeScriptBody = (value: string): string =>
+  value
+    .replace(/<\/(script)/gi, '<\\/$1')
+    .replace(/<!--/g, '<\\!--')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+
+/** A `<meta>` tag descriptor. */
+export interface SSRMeta {
+  name?: string;
+  property?: string;
+  httpEquiv?: string;
+  charset?: string;
+  content?: string;
+}
+
+/** A `<link>` tag descriptor. */
+export interface SSRLink {
+  rel: string;
+  href: string;
+  as?: string;
+  type?: string;
+  crossorigin?: string;
+  media?: string;
+  integrity?: string;
+  nonce?: string;
+}
+
+/** An inline or external `<script>` tag descriptor. */
+export interface SSRScript {
+  src?: string;
+  type?: string;
+  body?: string;
+  defer?: boolean;
+  async?: boolean;
+  nonce?: string;
+  crossorigin?: string;
+  integrity?: string;
+  module?: boolean;
+}
+
+/** Options accepted by `HeadManager.add()`. */
+export interface UseHeadOptions {
+  title?: string;
+  titleTemplate?: string;
+  meta?: SSRMeta[];
+  link?: SSRLink[];
+  script?: SSRScript[];
+}
+
+/** Aggregated head state collected during a render. */
+export interface SSRHeadState {
+  title: string | null;
+  titleTemplate: string | null;
+  meta: SSRMeta[];
+  link: SSRLink[];
+  script: SSRScript[];
+}
+
+/** Public head manager handle. */
+export interface HeadManager {
+  /** Add or replace head entries. */
+  add(options: UseHeadOptions): void;
+  /** Returns the current state snapshot. */
+  state(): SSRHeadState;
+  /** Renders the collected head into HTML. */
+  render(options?: { nonce?: string }): string;
+  /** Resets the manager to an empty state. */
+  reset(): void;
+}
+
+/**
+ * Creates an isolated head manager. Each SSR context owns one instance.
+ */
+export const createHeadManager = (): HeadManager => {
+  const state: SSRHeadState = {
+    title: null,
+    titleTemplate: null,
+    meta: [],
+    link: [],
+    script: [],
+  };
+
+  const add: HeadManager['add'] = (options) => {
+    if (typeof options.title === 'string') state.title = options.title;
+    if (typeof options.titleTemplate === 'string') state.titleTemplate = options.titleTemplate;
+    if (Array.isArray(options.meta)) state.meta.push(...options.meta);
+    if (Array.isArray(options.link)) state.link.push(...options.link);
+    if (Array.isArray(options.script)) state.script.push(...options.script);
+  };
+
+  const render: HeadManager['render'] = (renderOpts = {}) => {
+    let html = '';
+    if (state.title !== null) {
+      const formatted = state.titleTemplate
+        ? state.titleTemplate.replace(/%s/g, state.title)
+        : state.title;
+      html += `<title>${escapeText(formatted)}</title>`;
+    }
+    for (const m of state.meta) {
+      let attrs = '';
+      for (const [k, v] of Object.entries(m)) {
+        if (v === undefined || v === null) continue;
+        if (isPrototypePollutionKey(k)) continue;
+        const attrName = k === 'httpEquiv' ? 'http-equiv' : k;
+        attrs += ` ${attrName}="${escapeAttr(String(v))}"`;
+      }
+      html += `<meta${attrs}>`;
+    }
+    for (const l of state.link) {
+      let attrs = ` rel="${escapeAttr(l.rel)}" href="${escapeAttr(l.href)}"`;
+      if (l.as) attrs += ` as="${escapeAttr(l.as)}"`;
+      if (l.type) attrs += ` type="${escapeAttr(l.type)}"`;
+      if (l.crossorigin) attrs += ` crossorigin="${escapeAttr(l.crossorigin)}"`;
+      if (l.media) attrs += ` media="${escapeAttr(l.media)}"`;
+      if (l.integrity) attrs += ` integrity="${escapeAttr(l.integrity)}"`;
+      if (l.nonce ?? renderOpts.nonce) {
+        attrs += ` nonce="${escapeAttr(l.nonce ?? renderOpts.nonce!)}"`;
+      }
+      html += `<link${attrs}>`;
+    }
+    for (const sc of state.script) {
+      let attrs = '';
+      if (sc.src) attrs += ` src="${escapeAttr(sc.src)}"`;
+      if (sc.type) attrs += ` type="${escapeAttr(sc.type)}"`;
+      else if (sc.module) attrs += ' type="module"';
+      if (sc.defer) attrs += ' defer';
+      if (sc.async) attrs += ' async';
+      if (sc.crossorigin) attrs += ` crossorigin="${escapeAttr(sc.crossorigin)}"`;
+      if (sc.integrity) attrs += ` integrity="${escapeAttr(sc.integrity)}"`;
+      const nonce = sc.nonce ?? renderOpts.nonce;
+      if (nonce) attrs += ` nonce="${escapeAttr(nonce)}"`;
+      html += `<script${attrs}>${sc.body ? escapeScriptBody(sc.body) : ''}</script>`;
+    }
+    return html;
+  };
+
+  const reset: HeadManager['reset'] = () => {
+    state.title = null;
+    state.titleTemplate = null;
+    state.meta = [];
+    state.link = [];
+    state.script = [];
+  };
+
+  return {
+    add,
+    state: () =>
+      ({
+        ...state,
+        meta: [...state.meta],
+        link: [...state.link],
+        script: [...state.script],
+      }) as SSRHeadState,
+    render,
+    reset,
+  };
+};
+
+/* ---------------------------------------------------------------------------
+ * Asset manifest
+ * ------------------------------------------------------------------------- */
+
+/** Asset preload entry. */
+export interface SSRAsset {
+  href: string;
+  rel: 'preload' | 'modulepreload' | 'stylesheet';
+  as?: string;
+  type?: string;
+  crossorigin?: string;
+  integrity?: string;
+}
+
+/** Public asset manager handle. */
+export interface AssetManager {
+  /** Add a generic preload (`<link rel="preload">`). */
+  preload(href: string, opts?: Omit<SSRAsset, 'href' | 'rel'>): void;
+  /** Add a JS module preload (`<link rel="modulepreload">`). */
+  module(href: string, opts?: Omit<SSRAsset, 'href' | 'rel' | 'as'>): void;
+  /** Add a stylesheet link (`<link rel="stylesheet">`). */
+  style(href: string, opts?: Omit<SSRAsset, 'href' | 'rel' | 'as'>): void;
+  /** Returns the current asset list snapshot. */
+  list(): SSRAsset[];
+  /** Renders all assets to a series of `<link>` tags. */
+  render(options?: { nonce?: string }): string;
+  /** Resets the manifest. */
+  reset(): void;
+}
+
+export const createAssetManager = (): AssetManager => {
+  const assets: SSRAsset[] = [];
+
+  return {
+    preload(href, opts = {}) {
+      assets.push({ href, rel: 'preload', ...opts });
+    },
+    module(href, opts = {}) {
+      assets.push({ href, rel: 'modulepreload', ...opts });
+    },
+    style(href, opts = {}) {
+      assets.push({ href, rel: 'stylesheet', ...opts });
+    },
+    list: () => [...assets],
+    render(renderOpts = {}) {
+      let html = '';
+      for (const a of assets) {
+        let attrs = ` rel="${escapeAttr(a.rel)}" href="${escapeAttr(a.href)}"`;
+        if (a.as) attrs += ` as="${escapeAttr(a.as)}"`;
+        if (a.type) attrs += ` type="${escapeAttr(a.type)}"`;
+        if (a.crossorigin) attrs += ` crossorigin="${escapeAttr(a.crossorigin)}"`;
+        if (a.integrity) attrs += ` integrity="${escapeAttr(a.integrity)}"`;
+        if (renderOpts.nonce) attrs += ` nonce="${escapeAttr(renderOpts.nonce)}"`;
+        html += `<link${attrs}>`;
+      }
+      return html;
+    },
+    reset() {
+      assets.length = 0;
+    },
+  };
+};

package/src/ssr/html-parser.ts

@@ -0,0 +1,387 @@
+/**
+ * Minimal, runtime-agnostic HTML parser for the SSR renderer.
+ *
+ * This is intentionally a small, linear scanner rather than a full HTML5
+ * tokenizer. It is sufficient for templates authored against the `bQuery`
+ * directive vocabulary (HTML fragments, common void/raw elements, attributes)
+ * and lets the SSR pipeline run on Bun, Deno and Node without depending on a
+ * `DOMParser` polyfill.
+ *
+ * Output: a tiny virtual node tree (`SSRNode`) compatible with the pluggable
+ * DOM adapter API used by `renderer.ts`.
+ *
+ * @module bquery/ssr
+ * @internal
+ */
+
+const VOID_ELEMENTS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
+
+const RAW_TEXT_ELEMENTS = new Set(['script', 'style', 'textarea', 'title']);
+
+/** A DOM-free node structure produced by `parseTemplate()`. */
+export type SSRNode = SSRElement | SSRText | SSRComment | SSRDocumentFragment;
+
+export interface SSRElement {
+  type: 'element';
+  tag: string;
+  attributes: Record<string, string>;
+  /** Order-preserving attribute list (so output is deterministic). */
+  attributeOrder: string[];
+  children: SSRNode[];
+  /** Whether this element should be serialised as a void element. */
+  void: boolean;
+  /** Whether the children are raw (e.g. `<script>` content). */
+  raw: boolean;
+}
+
+export interface SSRText {
+  type: 'text';
+  value: string;
+}
+
+export interface SSRComment {
+  type: 'comment';
+  value: string;
+}
+
+export interface SSRDocumentFragment {
+  type: 'fragment';
+  children: SSRNode[];
+}
+
+const HTML_ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: '\u00a0',
+};
+
+/**
+ * Decodes the named/numeric HTML entities the SSR parser actually needs.
+ * Anything else is preserved verbatim.
+ */
+export const decodeEntities = (input: string): string => {
+  if (input.indexOf('&') === -1) return input;
+  return input.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (match, code: string) => {
+    if (code[0] === '#') {
+      const isHex = code[1] === 'x' || code[1] === 'X';
+      const num = parseInt(code.slice(isHex ? 2 : 1), isHex ? 16 : 10);
+      if (Number.isFinite(num)) {
+        try {
+          return String.fromCodePoint(num);
+        } catch {
+          return match;
+        }
+      }
+      return match;
+    }
+    const name = code.toLowerCase();
+    return HTML_ENTITIES[name] ?? match;
+  });
+};
+
+interface ParseState {
+  src: string;
+  pos: number;
+}
+
+const isWs = (ch: string): boolean =>
+  ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r' || ch === '\f';
+
+const skipWs = (s: ParseState): void => {
+  while (s.pos < s.src.length && isWs(s.src[s.pos])) s.pos++;
+};
+
+const readUntil = (s: ParseState, stop: string): string => {
+  const start = s.pos;
+  const idx = s.src.indexOf(stop, start);
+  if (idx === -1) {
+    s.pos = s.src.length;
+    return s.src.slice(start);
+  }
+  s.pos = idx;
+  return s.src.slice(start, idx);
+};
+
+const readTagName = (s: ParseState): string => {
+  const start = s.pos;
+  while (s.pos < s.src.length) {
+    const ch = s.src[s.pos];
+    if (isWs(ch) || ch === '>' || ch === '/') break;
+    s.pos++;
+  }
+  return s.src.slice(start, s.pos).toLowerCase();
+};
+
+const readAttrName = (s: ParseState): string => {
+  const start = s.pos;
+  while (s.pos < s.src.length) {
+    const ch = s.src[s.pos];
+    if (isWs(ch) || ch === '=' || ch === '>' || ch === '/') break;
+    s.pos++;
+  }
+  return s.src.slice(start, s.pos);
+};
+
+const readAttrValue = (s: ParseState): string => {
+  const ch = s.src[s.pos];
+  if (ch === '"' || ch === "'") {
+    const quote = ch;
+    s.pos++;
+    const start = s.pos;
+    while (s.pos < s.src.length && s.src[s.pos] !== quote) s.pos++;
+    const value = s.src.slice(start, s.pos);
+    if (s.pos < s.src.length) s.pos++; // consume closing quote
+    return decodeEntities(value);
+  }
+  // Unquoted
+  const start = s.pos;
+  while (s.pos < s.src.length) {
+    const c = s.src[s.pos];
+    if (isWs(c) || c === '>' || (c === '/' && s.src[s.pos + 1] === '>')) break;
+    s.pos++;
+  }
+  return decodeEntities(s.src.slice(start, s.pos));
+};
+
+const parseAttributes = (
+  s: ParseState
+): { attributes: Record<string, string>; order: string[]; selfClose: boolean } => {
+  const attributes: Record<string, string> = Object.create(null) as Record<string, string>;
+  const order: string[] = [];
+  let selfClose = false;
+
+  while (s.pos < s.src.length) {
+    skipWs(s);
+    const ch = s.src[s.pos];
+    if (ch === '>') {
+      s.pos++;
+      break;
+    }
+    if (ch === '/') {
+      s.pos++;
+      skipWs(s);
+      if (s.src[s.pos] === '>') {
+        selfClose = true;
+        s.pos++;
+        break;
+      }
+      continue;
+    }
+    if (s.pos >= s.src.length) break;
+
+    const rawName = readAttrName(s);
+    if (!rawName) {
+      // Defensive: skip ahead to the next whitespace, '/' or '>' to avoid
+      // pathological 1-char-per-iteration advancement on malformed input.
+      while (s.pos < s.src.length) {
+        const c = s.src[s.pos];
+        if (isWs(c) || c === '>' || c === '/') break;
+        s.pos++;
+      }
+      continue;
+    }
+    const name = rawName.toLowerCase();
+    skipWs(s);
+    let value = '';
+    if (s.src[s.pos] === '=') {
+      s.pos++;
+      skipWs(s);
+      value = readAttrValue(s);
+    }
+    if (!(name in attributes)) {
+      order.push(name);
+    }
+    attributes[name] = value;
+  }
+
+  return { attributes, order, selfClose };
+};
+
+/**
+ * Parses an HTML template string into a virtual node tree without depending
+ * on a DOM implementation. The parser is intentionally permissive: it does
+ * not validate nesting, but it preserves attribute order and never throws on
+ * malformed input.
+ */
+export const parseTemplate = (template: string): SSRDocumentFragment => {
+  const s: ParseState = { src: template, pos: 0 };
+  const root: SSRDocumentFragment = { type: 'fragment', children: [] };
+  // Open-element stack so children attach to the correct parent.
+  const stack: Array<SSRElement | SSRDocumentFragment> = [root];
+
+  const top = (): SSRElement | SSRDocumentFragment => stack[stack.length - 1];
+
+  while (s.pos < s.src.length) {
+    if (s.src[s.pos] === '<') {
+      // Comment
+      if (s.src.startsWith('<!--', s.pos)) {
+        s.pos += 4;
+        const end = s.src.indexOf('-->', s.pos);
+        const value = end === -1 ? s.src.slice(s.pos) : s.src.slice(s.pos, end);
+        s.pos = end === -1 ? s.src.length : end + 3;
+        top().children.push({ type: 'comment', value });
+        continue;
+      }
+      // Doctype/processing instruction — skip silently
+      if (s.src.startsWith('<!', s.pos) || s.src.startsWith('<?', s.pos)) {
+        const end = s.src.indexOf('>', s.pos);
+        s.pos = end === -1 ? s.src.length : end + 1;
+        continue;
+      }
+
+      // Closing tag
+      if (s.src[s.pos + 1] === '/') {
+        s.pos += 2;
+        const name = readTagName(s);
+        const end = s.src.indexOf('>', s.pos);
+        s.pos = end === -1 ? s.src.length : end + 1;
+        // Pop the matching element if found, otherwise ignore.
+        for (let i = stack.length - 1; i > 0; i--) {
+          const node = stack[i];
+          if (node.type === 'element' && node.tag === name) {
+            stack.length = i;
+            break;
+          }
+        }
+        continue;
+      }
+
+      // Opening tag
+      if (s.pos + 1 < s.src.length && /[a-zA-Z]/.test(s.src[s.pos + 1])) {
+        s.pos++;
+        const tag = readTagName(s);
+        const { attributes, order, selfClose } = parseAttributes(s);
+        const isVoid = VOID_ELEMENTS.has(tag);
+        const element: SSRElement = {
+          type: 'element',
+          tag,
+          attributes,
+          attributeOrder: order,
+          children: [],
+          void: isVoid,
+          raw: RAW_TEXT_ELEMENTS.has(tag),
+        };
+        top().children.push(element);
+
+        if (isVoid || selfClose) {
+          // Don't push onto stack.
+          continue;
+        }
+
+        if (element.raw) {
+          // Raw-text element: read until matching close tag.
+          const closeTag = `</${tag}`;
+          const start = s.pos;
+          const lower = s.src.toLowerCase();
+          const idx = lower.indexOf(closeTag, start);
+          const rawText = idx === -1 ? s.src.slice(start) : s.src.slice(start, idx);
+          if (rawText) {
+            element.children.push({ type: 'text', value: rawText });
+          }
+          if (idx === -1) {
+            s.pos = s.src.length;
+          } else {
+            s.pos = idx;
+            // Consume the </tag>
+            const close = s.src.indexOf('>', s.pos);
+            s.pos = close === -1 ? s.src.length : close + 1;
+          }
+          continue;
+        }
+
+        stack.push(element);
+        continue;
+      }
+
+      top().children.push({ type: 'text', value: '<' });
+      s.pos++;
+      continue;
+    }
+
+    // Plain text
+    const text = readUntil(s, '<');
+    if (text) {
+      top().children.push({ type: 'text', value: decodeEntities(text) });
+    }
+  }
+
+  return root;
+};
+
+const escapeText = (value: string): string =>
+  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+const escapeAttr = (value: string): string =>
+  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/** Serialises a virtual node tree to an HTML string. */
+export const serializeTree = (node: SSRNode): string => {
+  if (node.type === 'text') return escapeText(node.value);
+  if (node.type === 'comment') return `<!--${node.value}-->`;
+  if (node.type === 'fragment') {
+    let out = '';
+    for (const child of node.children) out += serializeTree(child);
+    return out;
+  }
+
+  const el = node;
+  let attrs = '';
+  for (const name of el.attributeOrder) {
+    const value = el.attributes[name];
+    attrs += ` ${name}="${escapeAttr(value)}"`;
+  }
+
+  if (el.void) {
+    return `<${el.tag}${attrs}>`;
+  }
+
+  let inner = '';
+  if (el.raw) {
+    // Raw-text elements: don't escape children, they're already raw text.
+    for (const child of el.children) {
+      if (child.type === 'text') inner += child.value;
+    }
+  } else {
+    for (const child of el.children) inner += serializeTree(child);
+  }
+
+  return `<${el.tag}${attrs}>${inner}</${el.tag}>`;
+};
+
+/** Recursively clones a virtual node (used by `bq-for`). */
+export const cloneNode = (node: SSRNode): SSRNode => {
+  if (node.type === 'element') {
+    return {
+      type: 'element',
+      tag: node.tag,
+      attributes: { ...node.attributes },
+      attributeOrder: [...node.attributeOrder],
+      children: node.children.map(cloneNode),
+      void: node.void,
+      raw: node.raw,
+    };
+  }
+  if (node.type === 'fragment') {
+    return { type: 'fragment', children: node.children.map(cloneNode) };
+  }
+  if (node.type === 'text') return { type: 'text', value: node.value };
+  return { type: 'comment', value: node.value };
+};