Statum/js/statum-core.js

/*!
 * Statum - client-side state library (core module).
 *
 * An HTMX-inspired state layer. The library manages signed "snapshots" of
 * application state (one per slot type), keeps them fresh via the server's
 * `transmit_after` / `invalid_after` timestamps, and binds them to the DOM
 * through `stm-*` attributes. See model.md for the full specification.
 *
 * The client ships as modules, each a plain IIFE with no dependencies and no
 * build step, loaded in this order:
 *
 *   1. statum-core.js     - this file: the slot protocol (persistence, the
 *                           X-Statum-Slot request machinery, directive
 *                           application, the realtime channel), the
 *                           alert/confirm/notify overrides, boot, and the
 *                           module seam (`statum._bridge` /
 *                           `statum.registerAttribute`). Self-sufficient;
 *                           creates `window.statum`.
 *   2. statum-document.js - the render walk and the structural/DOM bindings.
 *   3. statum-markdown.js - the CommonMark engine and `stm-markdown`.
 *
 * Targets modern evergreen browsers (uses fetch, BroadcastChannel,
 * queueMicrotask, URLSearchParams, FormData).
 */
(function () {
  'use strict';


  /** Content-Type used by every Statum directive response. */
  var STATUM_CONTENT_TYPE = 'application/vnd.statum+json';
  /** Request/response header carrying one slot's reference (or base64 frame). */
  var SLOT_HEADER = 'X-Statum-Slot';
  /** Request header carrying an action's opaque `private` blob. */
  var PRIVATE_HEADER = 'X-Statum-Private';
  /** Session-cookie marker used to detect a fresh browser session. */
  var SESSION_COOKIE = '_statum_sdc';
  /** BroadcastChannel name used to sync session/device state across tabs. */
  var CHANNEL_NAME = 'statum';
  /** localStorage / sessionStorage key prefix for persisted frames. */
  var STORAGE_PREFIX = 'statum:';

  // ---------------------------------------------------------------------------
  // Configuration
  // ---------------------------------------------------------------------------

  /**
   * Endpoint URLs. These defaults may be overridden per-page with the
   * `stm-entrypoint` and `stm-slots` attributes on the `<body>` element.
   *
   * @type {{entrypointUrl: string, slotsUrl: string}}
   */
  var config = {
    entrypointUrl: '/_statum/entrypoint',
    slotsUrl: '/_statum/slots',
    channelUrl: '/_statum/channel',
    // The realtime worker is embedded in the library as a default resource
    // (served at /_statum/resource/statum-worker.js); override with stm-worker.
    workerUrl: '/_statum/resource/statum-worker.js'
  };

  // ---------------------------------------------------------------------------
  // State store
  // ---------------------------------------------------------------------------

  /**
   * In-memory store, keyed by slot type. Each value is `{frame, snapshot}`
   * where `snapshot` is the parsed `frame.content`. This map is the single
   * source of truth for rendering; persistent backends merely hydrate it.
   *
   * @type {Map<string, {frame: object, snapshot: object}>}
   */
  var store = new Map();

  /** Listeners, keyed by type name. @type {Map<string, Set<Function>>} */
  var listeners = new Map();

  /**
   * Idempotency tracking: slot key -> last-applied frame `signature`. Held in
   * memory only (per tab), so a frame already persisted by another tab still
   * re-draws a tab whose tracking lags. Entries are dropped on clear so a
   * replayed frame re-applies.
   * @type {Map<string, string>}
   */
  var signatures = new Map();

  /** Optional UI handlers (set via `statum.on*Handler`). */
  var handlers = { onConfirm: null, onNotify: null, onError: null };

  /** @type {BroadcastChannel|null} */
  var channel = null;

  /** Whether {@link init} has already run. */
  var initialized = false;

  /** Whether the entrypoint has been fetched (guards without pre-entrypoint
   *  only evaluate after this). */
  var entrypointLoaded = false;

  /** Set when a guard has triggered a redirect, so further work is skipped. */
  var guardRedirected = false;

  // ---------------------------------------------------------------------------
  // Small utilities
  // ---------------------------------------------------------------------------

  /**
   * Parse an ISO 8601 timestamp to epoch millis, or `undefined`.
   * @param {string|undefined} s
   * @returns {number|undefined}
   */
  function parseTime(s) {
    if (!s) return undefined;
    var t = new Date(s).getTime();
    return isNaN(t) ? undefined : t;
  }

  /**
   * Base64-encode a UTF-8 string (safe for frames containing non-Latin1 data).
   * @param {string} str
   * @returns {string}
   */
  function b64encode(str) {
    var bytes = new TextEncoder().encode(str);
    var bin = '';
    var chunk = 0x8000;
    for (var i = 0; i < bytes.length; i += chunk) {
      bin += String.fromCharCode.apply(null, bytes.subarray(i, i + chunk));
    }
    return btoa(bin);
  }

  /** Read a cookie value, or `null` if absent. @param {string} name */
  function getCookie(name) {
    var escaped = name.replace(/([.$?*|{}()[\]\\/+^])/g, '\\$1');
    var match = document.cookie.match(new RegExp('(?:^|; )' + escaped + '=([^;]*)'));
    return match ? decodeURIComponent(match[1]) : null;
  }

  /** Set a session cookie (no expiry => cleared when the browser closes). */
  function setCookie(name, value) {
    document.cookie = name + '=' + encodeURIComponent(value) + '; path=/; SameSite=Lax';
  }

  // ---------------------------------------------------------------------------
  // Expression evaluation
  // ---------------------------------------------------------------------------

  /**
   * Compiled-expression cache. Expressions are evaluated as JavaScript against
   * a scope object (the page's HTML is trusted, per the model).
   * @type {Map<string, Function>}
   */
  var exprCache = new Map();

  /**
   * Wrap a scope for expression evaluation so bare identifiers resolve in a
   * controlled order: names on the scope (slot types, loop variables,
   * `stm-def-*` locals) win; names missing from the scope but present on
   * `globalThis` (`Math`, `parseInt`, `String`, …) forward to that global;
   * anything else resolves to `undefined` instead of throwing a
   * `ReferenceError` or leaking an unintended global. The `has` trap claims
   * every name so `with` never falls through around the proxy, and the inner
   * try/catch of the compiled expression still turns property access on a
   * resolved `undefined`/`null` into `undefined` for that expression alone.
   * @param {object} scope
   * @returns {Proxy<object>}
   */
  function evalScope(scope) {
    return new Proxy(scope, {
      has: function () { return true; },
      get: function (target, name) {
        if (name in target) return target[name];
        if (typeof name === 'string' && name in globalThis) return globalThis[name];
        return undefined;
      }
    });
  }

  /**
   * Compile (and cache) an expression string into a function of `scope`.
   * Uses `with` so that arbitrary type names and loop variables are resolved
   * as bare identifiers. Returns a function that yields `undefined` on any
   * runtime or compile error.
   * @param {string} expr
   * @returns {Function}
   */
  function compileExpr(expr) {
    var cached = exprCache.get(expr);
    if (cached !== undefined) return cached;
    var fn;
    try {
      // Function-constructor bodies are non-strict by default, so `with` is
      // permitted. The inner try/catch turns runtime errors (property access
      // on an unset slot's `undefined`) into `undefined` so a missing path
      // simply yields no value; missing identifiers already resolve to
      // `undefined` via the evalScope proxy.
      fn = new Function('scope', 'with(scope){try{return (' + expr + ');}catch(e){return undefined;}}');
    } catch (e) {
      fn = function () { return undefined; };
    }
    exprCache.set(expr, fn);
    return fn;
  }

  /**
   * Evaluate an expression against a scope.
   * @param {string} expr
   * @param {object} [scope]
   * @returns {*} `undefined` if the expression is empty or fails.
   */
  function evalExpr(expr, scope) {
    if (expr == null || expr === '') return undefined;
    try {
      return compileExpr(expr)(evalScope(scope || {}));
    } catch (e) {
      return undefined;
    }
  }

  /**
   * Build a child scope that inherits the parent (so type bindings remain
   * visible) and adds one own loop variable.
   * @param {object} parent
   * @param {string} name
   * @param {*} value
   * @returns {object}
   */
  function childScope(parent, name, value) {
    var scope = Object.create(parent || null);
    scope[name] = value;
    return scope;
  }

  // ---------------------------------------------------------------------------
  // StatumError
  // ---------------------------------------------------------------------------

  /**
   * Error type thrown for HTTP failures and `error` directives.
   * @param {string} [message]
   * @param {string} [code]
   * @param {object} [data]
   */
  function StatumError(message, code, data) {
    this.name = 'StatumError';
    this.message = message || '';
    this.code = code || undefined;
    this.data = data || undefined;
  }
  StatumError.prototype = Object.create(Error.prototype);

  // ---------------------------------------------------------------------------
  // UI handlers (confirm / notify / error)
  // ---------------------------------------------------------------------------

  /**
   * Run the `notify` directive's default behaviour or the custom
   * `statum.onNotifyHandler`. The default surfaces the message via `alert()`.
   * @param {string} [kind] Application-defined category (freeform).
   * @param {string} [message]
   */
  function triggerNotify(kind, message) {
    var fn = handlers.onNotify;
    try {
      if (fn) fn(kind, message);
      else if (message != null) window.alert(message);
    } catch (e) { console.error('[statum] notify handler error', e); }
  }

  /**
   * Run the `stm-confirm` gate: the custom `statum.onConfirmHandler` if set,
   * otherwise `window.confirm`. Supports async handlers (custom modals).
   * @param {string} message
   * @param {HTMLElement} element
   * @returns {Promise<boolean>} truthy if the action should proceed.
   */
  async function triggerConfirm(message, element) {
    var fn = handlers.onConfirm;
    try {
      if (fn) return !!(await fn(message, element));
      return !!window.confirm(message);
    } catch (e) {
      console.error('[statum] confirm handler error', e);
      return false;
    }
  }

  /**
   * Run the custom `statum.onErrorHandler`, if set. Returns whether the default
   * behaviour (promise rejection + `stm-on-error` classes) should proceed: the
   * handler suppresses the default by returning (or resolving) `false`.
   * @param {StatumError} error
   * @param {HTMLElement|null} element
   * @returns {Promise<boolean>}
   */
  async function triggerError(error, element) {
    var fn = handlers.onError;
    if (!fn) return true;
    try {
      var suppress = await fn(error, element);
      return suppress !== false;
    } catch (e) {
      console.error('[statum] error handler error', e);
      return true;
    }
  }

  /**
   * Surface a failure: run `triggerError`, and if the default is not
   * suppressed, apply `stm-on-error` classes (when an origin element exists)
   * and re-throw so the originating promise rejects.
   * @param {StatumError} error
   * @param {HTMLElement|null} element
   */
  async function reportFailure(error, element) {
    if (await triggerError(error, element)) {
      if (element) applyErrorClasses(element, true);
      throw error;
    }
  }

  // ---------------------------------------------------------------------------
  // Persistence
  // ---------------------------------------------------------------------------

  /**
   * Pick the storage backend for a scope.
   * @param {string} scope
   * @returns {Storage|null} `null` for in-memory scopes.
   */
  function storageFor(scope) {
    if (scope === 'device' || scope === 'session') return localStorage;
    if (scope === 'flow') return sessionStorage;
    return null; // page / transient
  }

  /**
   * Persist a slot's frame to the backend matching its scope, removing any
   * stale copy from the other backend first (in case the scope changed).
   * @param {string} type
   * @param {{frame: object, snapshot: object}} entry
   */
  function persistEntry(type, entry) {
    var scope = entry.snapshot.slot && entry.snapshot.slot.scope;
    removePersisted(type);
    var storage = storageFor(scope);
    if (!storage) return;
    try {
      storage.setItem(STORAGE_PREFIX + type, JSON.stringify(entry.frame));
    } catch (e) {
      /* storage full or unavailable; remain in-memory only */
    }
  }

  /** Remove a persisted frame from both backends. @param {string} type */
  function removePersisted(type) {
    try { localStorage.removeItem(STORAGE_PREFIX + type); } catch (e) {}
    try { sessionStorage.removeItem(STORAGE_PREFIX + type); } catch (e) {}
  }

  /** Load every persisted frame from a backend into the in-memory store. */
  function loadFrom(storage) {
    for (var i = 0; i < storage.length; i++) {
      var key = storage.key(i);
      if (!key || key.indexOf(STORAGE_PREFIX) !== 0) continue;
      try {
        var frame = JSON.parse(storage.getItem(key));
        var snapshot = JSON.parse(frame.content);
        var type = snapshot.slot && snapshot.slot.type;
        if (type && !store.has(type)) store.set(type, { frame: frame, snapshot: snapshot });
      } catch (e) {
        /* corrupt entry: ignore */
      }
    }
  }

  /** Hydrate the store from localStorage and sessionStorage. */
  function hydrate() {
    try { loadFrom(localStorage); } catch (e) {}
    try { loadFrom(sessionStorage); } catch (e) {}
  }

  // ---------------------------------------------------------------------------
  // Session-cookie initialization
  // ---------------------------------------------------------------------------

  /**
   * Detect a fresh browser session using the `_statum_sdc` session cookie.
   * On a fresh session, clear all `session`-scoped persisted frames, then set
   * the marker. Session cookies are shared across tabs, so a tab opened
   * mid-session sees the marker and leaves session data intact.
   */
  function initSession() {
    if (getCookie(SESSION_COOKIE) !== null) return;
    clearSessionSlotsFromStorage();
    setCookie(SESSION_COOKIE, '1');
  }

  /** Remove all `session`-scoped frames from localStorage. */
  function clearSessionSlotsFromStorage() {
    var toRemove = [];
    for (var i = 0; i < localStorage.length; i++) {
      var key = localStorage.key(i);
      if (!key || key.indexOf(STORAGE_PREFIX) !== 0) continue;
      try {
        var frame = JSON.parse(localStorage.getItem(key));
        var snapshot = JSON.parse(frame.content);
        if (snapshot.slot && snapshot.slot.scope === 'session') toRemove.push(key);
      } catch (e) {}
    }
    for (var j = 0; j < toRemove.length; j++) localStorage.removeItem(toRemove[j]);
  }

  // ---------------------------------------------------------------------------
  // Listeners & cross-tab broadcast
  // ---------------------------------------------------------------------------

  /**
   * Fire all listeners for a type. (Renamed from `notify` to avoid confusion
   * with the `notify` directive.)
   * @param {string} type
   * @param {object|null} frame
   * @param {object|null} snapshot
   */
  function fireListeners(type, frame, snapshot) {
    var set = listeners.get(type);
    if (!set) return;
    var event = { type: type, frame: frame, snapshot: snapshot };
    set.forEach(function (cb) {
      try { cb(event); } catch (e) { console.error('[statum] listener error', e); }
    });
  }

  /**
   * Broadcast a state change to other tabs. Only `session`/`device` scopes are
   * shared (flow/page/transient are per-tab).
   * @param {object} message
   * @param {string} [scope]
   */
  function broadcast(message, scope) {
    if (!channel) return;
    if (scope !== 'session' && scope !== 'device') return;
    try { channel.postMessage(message); } catch (e) {}
  }

  /**
   * Broadcast a message to other tabs regardless of slot scope. Used to relay
   * realtime (live) events so they reach every tab, not just session/device
   * ones.
   */
  function broadcastAlways(message) {
    if (!channel) return;
    try { channel.postMessage(message); } catch (e) {}
  }

  /** Open the BroadcastChannel and wire inbound messages. */
  function setupChannel() {
    if (typeof BroadcastChannel === 'undefined') return;
    try {
      channel = new BroadcastChannel(CHANNEL_NAME);
    } catch (e) {
      channel = null;
      return;
    }
    channel.onmessage = function (ev) {
      var msg = ev.data;
      if (!msg) return;
      if (msg.kind === 'set' && msg.frame) {
        try {
          var snapshot = JSON.parse(msg.frame.content);
          var type = snapshot.slot && snapshot.slot.type;
          if (type && commitSet(msg.frame, snapshot, type, false)) renderAll();
        } catch (e) { /* ignore malformed */ }
      } else if (msg.kind === 'clear') {
        var t = msg.type;
        if (!t && msg.key != null) {
          store.forEach(function (entry, type) {
            if (entry.snapshot.slot && entry.snapshot.slot.key === msg.key) t = type;
          });
        }
        if (t) clearType(t, { broadcast: false });
        else if (msg.key != null) signatures.delete(msg.key);
        renderAll();
      }
    };
  }

  // ---------------------------------------------------------------------------
  // State mutation
  // ---------------------------------------------------------------------------

  /**
   * Remove a type from the store, un-persist it, drop its idempotency entry,
   * fire listeners, and (optionally) broadcast the clear to other tabs.
   * @param {string} type
   * @param {{broadcast?: boolean}} [opts]
   */
  function clearType(type, opts) {
    var entry = store.get(type);
    if (!entry) return;
    var scope = entry.snapshot.slot && entry.snapshot.slot.scope;
    var key = entry.snapshot.slot && entry.snapshot.slot.key;
    store.delete(type);
    removePersisted(type);
    if (key) signatures.delete(key);
    fireListeners(type, null, null);
    if (opts && opts.broadcast) broadcast({ kind: 'clear', key: key, type: type }, scope);
  }

  /**
   * Resolve a slot key to its type and clear it. Used by the `clear` directive
   * (keyed) and by live `clear` events.
   * @param {string} key
   * @param {boolean} [broadcast]
   */
  function clearByKey(key, broadcast) {
    var typeToRemove = null;
    store.forEach(function (entry, type) {
      if (entry.snapshot.slot && entry.snapshot.slot.key === key) typeToRemove = type;
    });
    if (typeToRemove) clearType(typeToRemove, { broadcast: !!broadcast });
    else if (key) signatures.delete(key);
  }

  /**
   * Resolve a frame signature to its slot type and clear it. Used by the
   * `invalidate` directive, which references a signature (not a key) because the
   * server reports a bad signature without trusting the frame's content.
   * @param {string} signature
   * @param {boolean} [broadcast]
   */
  function clearBySignature(signature, broadcast) {
    var typeToRemove = null;
    store.forEach(function (entry, type) {
      if (entry.frame && entry.frame.signature === signature) typeToRemove = type;
    });
    if (typeToRemove) clearType(typeToRemove, { broadcast: !!broadcast });
    else if (signature) signatures.delete(signature);
  }

  /**
   * Commit a `set` to the in-memory store, persist it, and fire listeners.
   * Idempotent: if the frame's `signature` matches the last-applied signature
   * for this slot (tracked in {@link signatures}), nothing happens and `false`
   * is returned. When `doBroadcast` is true the set is forwarded to other tabs
   * via the scope-gated broadcast (session/device only).
   * @param {object} frame
   * @param {object} snapshot
   * @param {string} type
   * @param {boolean} doBroadcast
   * @returns {boolean} `true` if state changed.
   */
  function commitSet(frame, snapshot, type, doBroadcast) {
    var key = snapshot.slot && snapshot.slot.key;
    var sig = frame.signature;
    if (key && sig !== undefined && signatures.get(key) === sig) return false;
    var entry = { frame: frame, snapshot: snapshot };
    store.set(type, entry);
    persistEntry(type, entry);
    fireListeners(type, frame, snapshot);
    if (key && sig !== undefined) signatures.set(key, sig);
    if (doBroadcast) {
      var scope = snapshot.slot && snapshot.slot.scope;
      broadcast({ kind: 'set', frame: frame }, scope);
    }
    return true;
  }

  /**
   * Apply a `set` directive: store/refresh a slot's snapshot (idempotently),
   * broadcasting to other tabs.
   * @param {object} directive `{ snapshot_frame }`
   */
  function applySet(directive) {
    var frame = directive.snapshot_frame;
    if (!frame || !frame.content) return;
    var snapshot;
    try { snapshot = JSON.parse(frame.content); } catch (e) { return; }
    var type = snapshot.slot && snapshot.slot.type;
    if (!type) return;
    commitSet(frame, snapshot, type, true);
  }

  /**
   * Apply a `clear` directive. The directive carries a slot key, so the type
   * holding that key is resolved and removed.
   * @param {object} directive `{ key }`
   */
  function applyClear(directive) {
    if (directive.key == null) return;
    clearByKey(directive.key, true);
  }

  /**
   * Apply a live `set` event received over the realtime channel. The frame is
   * committed (idempotently) and, when new, broadcast to sibling tabs via the
   * scope-agnostic {@link broadcastAlways} so every tab sees it regardless of
   * which (or how many) tabs hold a subscription.
   * @param {object} frame
   */
  function applyRemoteSet(frame) {
    try {
      var snapshot = JSON.parse(frame.content);
      var type = snapshot.slot && snapshot.slot.type;
      if (!type) return;
      if (commitSet(frame, snapshot, type, false)) {
        broadcastAlways({ kind: 'set', frame: frame });
        renderAll();
      }
    } catch (e) { /* malformed frame */ }
  }

  /** Apply a live `clear` event received over the realtime channel. */
  function applyRemoteClear(key) {
    if (key == null) return;
    signatures.delete(key);
    clearByKey(key, false);
    broadcastAlways({ kind: 'clear', key: key });
    renderAll();
  }

  // ---------------------------------------------------------------------------
  // Snapshot freshness & request headers
  // ---------------------------------------------------------------------------

  /**
   * Categorize a held snapshot relative to the current time.
   * @returns {'silent'|'always'|'invalid'|'stale'|'fresh'}
   *   - `silent`: unidirectional (`transmit_after` undefined) - never sent.
   *   - `always`: `transmit_after === as_at` - send the base64 frame each time.
   *   - `invalid`: past `invalid_after` - drop and refetch.
   *   - `stale`: past `transmit_after` but not yet invalid - pre-flight first.
   *   - `fresh`: still cached server-side - send the `as_at` reference.
   */
  function entryCategory(entry) {
    var snap = entry.snapshot;
    var transmit = snap.transmit_after;
    if (transmit === undefined || transmit === null) return 'silent';
    if (transmit === snap.as_at) return 'always';
    var now = Date.now();
    var invalidAt = parseTime(snap.invalid_after);
    var transmitAt = parseTime(transmit);
    if (invalidAt !== undefined && now >= invalidAt) return 'invalid';
    if (transmitAt !== undefined && now >= transmitAt) return 'stale';
    return 'fresh';
  }

  /**
   * Drop locally-invalid snapshots and pre-flight any stale ones. Pre-flighting
   * posts the stale frames to the slot endpoint and applies the returned `set`
   * directives, refreshing their `as_at` values before the real request runs.
   *
   * Single-flight: concurrent callers share one in-flight preparation.
   * @returns {Promise<void>}
   */
  var preparePromise = null;
  function prepareSlots() {
    if (preparePromise) return preparePromise;
    preparePromise = doPrepareSlots().then(function () {
      preparePromise = null;
    }, function () {
      preparePromise = null;
    });
    return preparePromise;
  }

  async function doPrepareSlots() {
    var stale = [];
    store.forEach(function (entry, type) {
      var cat = entryCategory(entry);
      if (cat === 'invalid') {
        clearType(type, { broadcast: false });
      } else if (cat === 'stale') {
        stale.push(entry.frame);
      }
    });
    if (stale.length) {
      var directives = await postSlots(stale);
      var pfResult = applyDirectives(directives, { originElement: null });
      executeTerminal(pfResult);
    }
  }

  /**
   * Build the `X-Statum-Slot` header values for every held slot, using the
   * freshness rules. Assumes {@link prepareSlots} has just run.
   * @returns {string[]}
   */
  function buildSlotHeaders() {
    var headers = [];
    store.forEach(function (entry) {
      var snap = entry.snapshot;
      var cat = entryCategory(entry);
      if (cat === 'silent' || cat === 'invalid') return;
      if (cat === 'always') {
        headers.push(b64encode(JSON.stringify(entry.frame)));
      } else {
        headers.push('key=' + snap.slot.key + '; as_at=' + snap.as_at);
      }
    });
    return headers;
  }

  /**
   * Collect the current frames held for the given slot keys, in the order the
   * keys are first supplied. Used by the `transmit` directive (which forces a
   * slot's frame to be posted as if its `transmit_after` had elapsed). Keys the
   * client does not currently hold are skipped.
   * @param {string[]} keys
   * @returns {object[]}
   */
  function collectFramesForKeys(keys) {
    var keySet = Object.create(null);
    for (var i = 0; i < keys.length; i++) keySet[keys[i]] = true;
    var frames = [];
    store.forEach(function (entry) {
      var key = entry.snapshot.slot && entry.snapshot.slot.key;
      if (key && keySet[key]) {
        frames.push(entry.frame);
        delete keySet[key];
      }
    });
    return frames;
  }

  // ---------------------------------------------------------------------------
  // HTTP helpers
  // ---------------------------------------------------------------------------

  /** True if a response is a Statum directive response. */
  function isStatum(res) {
    return (res.headers.get('Content-Type') || '').indexOf(STATUM_CONTENT_TYPE) !== -1;
  }

  /**
   * POST an array of frames to the slot endpoint (the pre-flight target) and
   * return its directive array. This request intentionally carries no slot
   * headers (it is itself the refresh).
   * @param {object[]} frames
   * @returns {Promise<object[]>}
   */
  async function postSlots(frames) {
    var headers = new Headers();
    headers.set('Accept', STATUM_CONTENT_TYPE);
    headers.set('Content-Type', 'application/json');
    var res = await fetch(config.slotsUrl, {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(frames),
      credentials: 'same-origin'
    });
    if (!isStatum(res)) return [];
    try { return await res.json(); } catch (e) { return []; }
  }

  /**
   * Apply the non-terminal directives from a response (set/clear/subscribe/
   * unsubscribe/notify/transmit-collection), then `render`.
   *
   * Terminal directives (`navigate`, `post`, `reenter`), error directives, and
   * any transmit/retry intent are collected on the returned result rather than
   * executed here: {@link handleResponse} performs the asynchronous
   * transmission (and optional retry) and then runs terminal navigation, so
   * that a `transmit` with `retry` can re-issue the request before the page is
   * navigated away.
   * @param {object[]} directives
   * @param {{originElement?: HTMLElement}} [ctx]
   * @returns {{errors: StatumError[], transmitKeys: string[], retry: boolean, navigate: object|null, post: object|null, reenter: boolean}}
   */
  function applyDirectives(directives, ctx) {
    var result = { errors: [], transmitKeys: [], retry: false, navigate: null, post: null, reenter: false, formSubmits: [], formResets: [] };
    var list = Array.isArray(directives) ? directives : [];

    for (var i = 0; i < list.length; i++) {
      var d = list[i];
      if (!d || typeof d !== 'object') continue;
      switch (d.type) {
        case 'set': applySet(d); break;
        case 'clear': applyClear(d); break;
        case 'invalidate':
          if (d.signature != null) {
            console.warn('[statum] server could not verify slot frame ' + d.signature + '; clearing it');
            clearBySignature(d.signature, true);
          }
          break;
        case 'subscribe': channelSubscribe(d.key); break;
        case 'unsubscribe': channelUnsubscribe(d.key); break;
        case 'notify': triggerNotify(d.kind, d.message); break;
        case 'transmit':
          if (d.key != null) {
            if (result.transmitKeys.indexOf(d.key) === -1) result.transmitKeys.push(d.key);
            if (d.retry) result.retry = true;
          }
          break;
        case 'error':
          {
            var err = new StatumError(d.message, d.code, d.data);
            var detail = d.code ? (d.message + ' [' + d.code + ']') : d.message;
            console.error('[statum] error directive: ' + (detail || '(no message)'));
            result.errors.push(err);
          }
          break;
        case 'navigate': result.navigate = d; break;
        case 'reenter': result.reenter = true; break;
        case 'post': result.post = d; break;
        case 'form-submit': result.formSubmits.push(d); break;
        case 'form-reset': result.formResets.push(d); break;
      }
    }

    renderAll();
    return result;
  }

  /**
   * Execute the terminal directives collected by {@link applyDirectives}.
   *
   * Order: `form-reset`/`form-submit` first (their work is synchronous), then
   * a `reenter` (the entrypoint refresh is awaited so the action's promise
   * resolves only once the re-entered state has been applied), then
   * `navigate`/`post` — navigation wins over reenter's refresh when both are
   * present, running after it. Async because of reenter.
   */
  async function executeTerminal(result) {
    result.formResets.forEach(doFormReset);
    result.formSubmits.forEach(doFormSubmit);
    if (result.reenter) {
      try {
        await loadEntrypoint();
      } catch (err) {
        console.error('[statum] reenter: entrypoint refresh failed', err);
      }
    }
    if (result.navigate) doNavigate(result.navigate);
    if (result.post) doPost(result.post);
  }

  /** Execute a `form-submit` directive: optionally override action/method, then submit. */
  function doFormSubmit(d) {
    var form = document.getElementById(d.form);
    if (form) {
      if (d.action) form.setAttribute('action', d.action);
      if (d.method) form.setAttribute('method', d.method);
      form.submit();
    }
  }

  /** Execute a `form-reset` directive. */
  function doFormReset(d) {
    var form = document.getElementById(d.form);
    if (form) form.reset();
  }

  /** Execute a `navigate` directive as a full page load. */
  function doNavigate(d) {
    if (d.uri) window.location.href = d.uri;
  }

  /** Execute a `post` directive as a real (navigating) form POST. */
  function doPost(d) {
    if (!d.uri) return;
    var form = document.createElement('form');
    form.method = 'POST';
    form.action = d.uri;
    form.style.display = 'none';
    var data = d.data || {};
    Object.keys(data).forEach(function (name) {
      var input = document.createElement('input');
      input.type = 'hidden';
      input.name = name;
      input.value = data[name] == null ? '' : String(data[name]);
      form.appendChild(input);
    });
    document.body.appendChild(form);
    form.submit();
  }

  /**
   * Handle a fetch response: if it is a Statum response, apply its directives;
   * otherwise throw on HTTP errors and no-op on other successful responses.
   *
   * Directive ordering: non-terminal directives are applied and the page
   * rendered; then any `transmit` directives force their slot frames to be
   * posted (applying the directives the slot endpoint returns); then, if a
   * transmit requested a retry, the originating request (`ctx.retry`) is
   * re-issued and this response's terminal directives and errors are skipped.
   * Otherwise terminal directives run — form resets/submits, then an awaited
   * `reenter` entrypoint refresh (a failure is logged, never propagated), then
   * `navigate`/`post` — and finally error directives are surfaced. Because
   * the terminal phase is awaited, an action promise resolves only after a
   * `reenter` refresh has been applied.
   * @param {Response} res
   * @param {{originElement?: HTMLElement, retry?: Function}} [ctx]
   */
  async function handleResponse(res, ctx) {
    var el = ctx && ctx.originElement;
    if (!isStatum(res)) {
      if (!res.ok) await reportFailure(new StatumError('HTTP ' + res.status), el);
      return;
    }
    var directives;
    try { directives = await res.json(); } catch (e) { directives = []; }
    var result = applyDirectives(directives, ctx);

    if (result.transmitKeys && result.transmitKeys.length) {
      var frames = collectFramesForKeys(result.transmitKeys);
      if (frames.length) {
        var txDirectives = await postSlots(frames);
        applyDirectives(txDirectives, { originElement: el });
      }
    }

    if (result.retry && ctx && typeof ctx.retry === 'function') {
      await ctx.retry();
      return;
    }

    await executeTerminal(result);

    var errors = result.errors || [];
    for (var i = 0; i < errors.length; i++) {
      await reportFailure(errors[i], el);
    }
  }

  // ---------------------------------------------------------------------------
  // Entrypoint & action requests
  // ---------------------------------------------------------------------------

  /**
   * Fetch the entrypoint for the current URL, applying its directives. Carries
   * slot headers (and pre-flights) like any other request. The request is
   * wrapped in an `attempt` closure passed as the response `retry` callback, so
   * a `transmit` directive with `retry` can re-issue it after transmission.
   * @returns {Promise<void>}
   */
  function loadEntrypoint() {
    if (guardRedirected) return Promise.resolve();
    // From this point on guards are "post-entrypoint" (all of them evaluate).
    entrypointLoaded = true;
    var attempt = async function () {
      await prepareSlots();
      var headers = new Headers();
      headers.set('Accept', STATUM_CONTENT_TYPE);
      buildSlotHeaders().forEach(function (v) { headers.append(SLOT_HEADER, v); });
      var url = config.entrypointUrl + '?uri=' + encodeURIComponent(window.location.href);
      var res = await fetch(url, { headers: headers, credentials: 'same-origin' });
      await handleResponse(res, { originElement: null, retry: attempt });
    };
    return attempt();
  }

  /**
   * Perform an action request.
   *
   * The request is wrapped in an `attempt` closure passed as the response
   * `retry` callback, so a `transmit` directive with `retry` can re-issue the
   * same action after the transmission (rebuilding headers from current state).
   *
   * @param {object} action `{ uri, method, private }`
   * @param {object} [data] Key/value parameters. Encoded as query string for
   *   GET/HEAD, otherwise as `application/x-www-form-urlencoded`.
   * @param {HTMLElement} [originElement] Element that triggered the action, so
   *   that `stm-on-error` classes can be applied on an `error` directive.
   * @returns {Promise<void>} Resolves once the request completes and its
   *   directives have run; rejects on HTTP failure or an `error` directive.
   */
  function performAction(action, data, originElement) {
    var attempt = async function () {
      await prepareSlots();
      var headers = new Headers();
      headers.set('Accept', STATUM_CONTENT_TYPE);
      buildSlotHeaders().forEach(function (v) { headers.append(SLOT_HEADER, v); });
      if (action.private) headers.set(PRIVATE_HEADER, action.private);

      var method = (action.method || 'GET').toUpperCase();
      var params = data || {};
      var init = { method: method, headers: headers, credentials: 'same-origin' };
      var url = action.uri;

      if (method === 'GET' || method === 'HEAD') {
        var qs = new URLSearchParams(params).toString();
        if (qs) url += (url.indexOf('?') !== -1 ? '&' : '?') + qs;
      } else {
        init.body = new URLSearchParams(params).toString();
        headers.set('Content-Type', 'application/x-www-form-urlencoded');
      }

      var res;
      try {
        res = await fetch(url, init);
      } catch (networkErr) {
        await reportFailure(new StatumError('Network error'), originElement);
        return;
      }
      await handleResponse(res, { originElement: originElement, retry: attempt });
    };
    return attempt();
  }

  // ---------------------------------------------------------------------------
  // Realtime channel (subscribe/unsubscribe directives)
  // ---------------------------------------------------------------------------

  /**
   * Per-tab fallback engine, used when `SharedWorker` is unavailable. Owns an
   * `EventSource`, reads the channel id from the first `event: channel`,
   * reference-counts slot keys within this tab, PATCHes subscription changes,
   * applies incoming set/clear events (broadcasting them to siblings), and
   * closes the stream once it has no subscriptions.
   */
  function createFallbackEngine() {
    var es = null;
    var channelId = null;
    var refs = new Map(); // slotKey -> count
    var pending = { subscribe: [], unsubscribe: [] };
    var patchScheduled = false;

    function openStream() {
      if (es) return;
      try { es = new EventSource(config.channelUrl); }
      catch (e) { es = null; return; }
      es.addEventListener('channel', function (ev) { channelId = ev.data; flushPatch(); });
      es.addEventListener('set', function (ev) {
        try { applyRemoteSet(JSON.parse(ev.data)); } catch (e) {}
      });
      es.addEventListener('clear', function (ev) { applyRemoteClear(ev.data); });
      es.onerror = function () { /* EventSource auto-reconnects */ };
    }

    function closeStream() {
      if (es) { try { es.close(); } catch (e) {} es = null; }
      channelId = null;
    }

    function schedulePatch() {
      if (patchScheduled) return;
      patchScheduled = true;
      Promise.resolve().then(function () { patchScheduled = false; flushPatch(); });
    }

    function flushPatch() {
      if (!channelId) return;
      var sub = pending.subscribe, uns = pending.unsubscribe;
      if (!sub.length && !uns.length) return;
      pending = { subscribe: [], unsubscribe: [] };
      var body = {};
      if (sub.length) body.subscribe = sub;
      if (uns.length) body.unsubscribe = uns;
      try {
        fetch(config.channelUrl + '/' + encodeURIComponent(channelId), {
          method: 'PATCH',
          headers: { 'Content-Type': 'application/json' },
          credentials: 'same-origin',
          body: JSON.stringify(body)
        }).catch(function () {});
      } catch (e) {}
    }

    return {
      subscribe: function (key) {
        var c = refs.get(key) || 0;
        refs.set(key, c + 1);
        if (c === 0) { openStream(); pending.subscribe.push(key); schedulePatch(); }
      },
      unsubscribe: function (key) {
        var c = refs.get(key) || 0;
        if (c <= 0) return;
        if (c - 1 <= 0) {
          refs.delete(key);
          pending.unsubscribe.push(key);
          schedulePatch();
          if (refs.size === 0) setTimeout(function () { if (refs.size === 0) closeStream(); }, 0);
        } else {
          refs.set(key, c - 1);
        }
      }
    };
  }

  /**
   * Channel manager. Prefers a `SharedWorker` (which owns the single SSE
   * connection, reference-counts subscriptions across tabs, and relays events
   * through the cross-tab `BroadcastChannel`); falls back to a per-tab
   * `EventSource` engine when `SharedWorker` is unavailable or the worker
   * script fails to load. Tracks the true per-slot subscription count so it can
   * replay active subscriptions into the fallback on a mid-session switch.
   */
  function createChannelManager() {
    var port = null;
    var workerObj = null;
    var fallback = null;
    var mode = null; // 'worker' | 'fallback' | null
    var counts = new Map(); // slotKey -> count (true subscription state)

    function switchToFallback() {
      if (mode === 'fallback') return;
      mode = 'fallback';
      port = null;
      workerObj = null;
      fallback = createFallbackEngine();
      counts.forEach(function (c, key) {
        for (var i = 0; i < c; i++) fallback.subscribe(key);
      });
    }

    function ensure() {
      if (mode !== null) return;
      if (typeof SharedWorker !== 'undefined') {
        try {
          workerObj = new SharedWorker(config.workerUrl);
          port = workerObj.port;
          port.start();
          port.postMessage({ op: 'init', url: config.channelUrl });
          // The worker delivers events via the BroadcastChannel, so nothing is
          // required on this port beyond command messages.
          port.onmessage = function () {};
          workerObj.onerror = function () {
            console.warn('[statum] realtime worker failed; falling back to per-tab channel');
            switchToFallback();
          };
          window.addEventListener('pagehide', function () {
            if (mode === 'worker' && port) {
              try { port.postMessage({ op: 'disconnect' }); } catch (e) {}
            }
          });
          mode = 'worker';
          return;
        } catch (e) { workerObj = null; port = null; }
      }
      switchToFallback();
    }

    return {
      subscribe: function (key) {
        if (key == null) return;
        ensure();
        counts.set(key, (counts.get(key) || 0) + 1);
        if (mode === 'worker') { try { port.postMessage({ op: 'subscribe', key: key }); } catch (e) {} }
        else fallback.subscribe(key);
      },
      unsubscribe: function (key) {
        if (key == null) return;
        var c = (counts.get(key) || 0) - 1;
        if (c <= 0) counts.delete(key); else counts.set(key, c);
        ensure();
        if (mode === 'worker') { try { port.postMessage({ op: 'unsubscribe', key: key }); } catch (e) {} }
        else fallback.unsubscribe(key);
      }
    };
  }

  var channelManager = createChannelManager();

  function channelSubscribe(key) { channelManager.subscribe(key); }
  function channelUnsubscribe(key) { channelManager.unsubscribe(key); }

  // ---------------------------------------------------------------------------
  // Error-state classes
  // ---------------------------------------------------------------------------
  // (Moved from the render-walk section in statum-document.js so that
  // reportFailure above is self-contained without that module.)


  /** Apply or remove `stm-on-error` classes on an action element. */
  function applyErrorClasses(el, on) {
    if (!el || !el.hasAttribute || !el.hasAttribute('stm-on-error')) return;
    var classes = (el.getAttribute('stm-on-error') || '').split(/\s+/).filter(Boolean);
    classes.forEach(function (c) { on ? el.classList.add(c) : el.classList.remove(c); });
  }

  // ---------------------------------------------------------------------------
  // Module seam: attribute-handler registry + render driver
  // ---------------------------------------------------------------------------
  //
  // statum-core.js is self-sufficient: it owns the slot protocol, the UI
  // handler overrides and the boot sequence, and never references the other
  // modules. statum-document.js (the render walk) and statum-markdown.js
  // (the CommonMark engine) load AFTER core and register through this seam.
  //
  // `_bridge` (underscore = private by convention, like `_testMarkdown`) is
  // the internal cross-module surface; `statum.registerAttribute` is the
  // public entry point module authors use.

  /**
   * Resolved execution order of the per-element `stm-*` bindings: an ordered
   * list of `{name, fn, prefix}`. The render walk (statum-document.js)
   * iterates it for every element. A throwing handler aborts that render
   * cycle through renderAll's try/catch, exactly as the previous hardcoded
   * call chain did, so handlers get no per-handler try/catch here.
   * @type {Array<{name: string, fn: Function, prefix: boolean}>}
   */
  var attributeHandlers = [];

  /**
   * Register a handler for an `stm-*` attribute.
   *
   * `name` is either an exact attribute name (`'stm-disabled'`) or, when it
   * ends with a dot, a prefix matcher (`'stm-class.'` matches any
   * `stm-class.{name}`). The handler is called once per element per render
   * cycle when the element carries at least one matching attribute; it then
   * iterates the element's attributes itself (several may match a prefix).
   *
   * `opts.after` / `opts.before` name another registered attribute and the
   * handler is inserted directly after / before it. A constraint naming an
   * unregistered attribute warns and keeps plain registration order, so
   * loading a module early cannot break the page. Registering the same name
   * twice warns and ignores the second handler.
   *
   * @param {string} name
   * @param {Function} fn `fn(el, scope)`
   * @param {{after?: string, before?: string}} [opts]
   */
  function registerAttribute(name, fn, opts) {
    if (typeof name !== 'string' || !name || typeof fn !== 'function') {
      console.warn('[statum] registerAttribute: expected an attribute name and a handler function');
      return;
    }
    for (var i = 0; i < attributeHandlers.length; i++) {
      if (attributeHandlers[i].name === name) {
        console.warn('[statum] registerAttribute: "' + name + '" is already registered; ignoring');
        return;
      }
    }
    var entry = { name: name, fn: fn, prefix: name.charAt(name.length - 1) === '.' };
    var anchor = opts && (opts.after || opts.before);
    var at = anchor ? handlerIndex(anchor) : -1;
    if (anchor && at === -1) {
      console.warn('[statum] registerAttribute: "' + anchor +
        '" is not registered; keeping registration order for "' + name + '"');
    }
    if (at !== -1 && opts.after) at += 1; // insert directly after the anchor
    if (at === -1) attributeHandlers.push(entry);
    else attributeHandlers.splice(at, 0, entry);
  }

  /** Position of a registered handler by name, or -1. */
  function handlerIndex(name) {
    for (var i = 0; i < attributeHandlers.length; i++) {
      if (attributeHandlers[i].name === name) return i;
    }
    return -1;
  }

  /**
   * The render driver: installed by statum-document.js at load time, called
   * by renderAll to walk the document. When absent (core loaded alone)
   * render cycles still run the evaluate hooks and guards but skip the DOM
   * walk.
   * @type {Function|null}
   */
  var renderDriver = null;

  /** Install the render driver. @param {Function} fn `fn(scope)` */
  function installRenderDriver(fn) {
    if (typeof fn === 'function') renderDriver = fn;
  }

  /**
   * The module bridge: everything the other modules need from core (and the
   * one thing core needs from them, the render driver) crosses here. The
   * evaluate hooks stay core-private on purpose — no other module needs
   * them; modules register attribute handlers instead.
   */
  var bridge = {
    /** Expression machinery (core-owned). */
    evalExpr: evalExpr,
    childScope: childScope,
    stateScope: stateScope,
    /** Render cycle + requests. */
    renderAll: renderAll,
    loadEntrypoint: loadEntrypoint,
    performAction: performAction,
    /** UI handler overrides (runElementAction gates on confirm). */
    triggerConfirm: triggerConfirm,
    triggerNotify: triggerNotify,
    triggerError: triggerError,
    handlers: handlers,
    /** Error-state classes for action elements. */
    applyErrorClasses: applyErrorClasses,
    /** The seam itself. */
    registerAttribute: registerAttribute,
    attributeHandlers: attributeHandlers,
    installRenderDriver: installRenderDriver
  };


  /**
   * Evaluate every `<link rel="stm-guard">` in the document head. A guard whose
   * `require` predicate is false redirects the page to its `href`.
   *
   * Guards marked `pre-entrypoint` are evaluated on every cycle (including the
   * initial, pre-entrypoint render, which uses only hydrated state); guards
   * without it are evaluated only once the entrypoint has loaded. On every later
   * evaluate cycle (set/clear) all guards are re-checked, so logging out, for
   * example, can bounce the user off a guarded page.
   */
  function evaluateGuards() {
    if (guardRedirected) return;
    var scope = stateScope();
    var guards = document.querySelectorAll('link[rel~="stm-guard"]');
    for (var i = 0; i < guards.length; i++) {
      var g = guards[i];
      var preEntrypoint = g.hasAttribute('pre-entrypoint');
      if (!preEntrypoint && !entrypointLoaded) continue;
      var require = g.getAttribute('require');
      if (!require) continue;
      if (!evalExpr(require, scope)) {
        guardRedirected = true;
        var href = g.getAttribute('href') || '/';
        console.warn('[statum] guard failed (' + require + '); redirecting to ' + href);
        window.location.href = href;
        return;
      }
    }
  }

  // ---------------------------------------------------------------------------
  // Evaluation hooks (no-arg callbacks before/after each render cycle)
  // ---------------------------------------------------------------------------

  var beforeHooks = [];
  var afterHooks = [];

  /** Re-render the whole document against the current state. */
  function renderAll() {
    if (guardRedirected) return;
    beforeHooks.forEach(function (fn) { try { fn(); } catch (e) { console.error('[statum] beforeEvaluate hook error', e); } });
    try {
      // The DOM walk lives in statum-document.js and is installed through
      // the seam; without it the cycle still runs hooks and guards.
      if (renderDriver) renderDriver(stateScope());
    }
    catch (e) { console.error('[statum] render error', e); }
    afterHooks.forEach(function (fn) { try { fn(); } catch (e) { console.error('[statum] afterEvaluate hook error', e); } });
    evaluateGuards();
  }


  // ---------------------------------------------------------------------------
  // Boot visibility (stm-preloader / stm-content)
  // ---------------------------------------------------------------------------

  /**
   * Toggle pre/post-entrypoint visibility with the `hidden` attribute. While
   * loading, `stm-preloader` elements are shown and `stm-content` elements
   * hidden; once ready, the reverse.
   *
   * To avoid a flash of un-bound template before the script runs, authors may
   * pre-set `hidden` directly on `stm-content` in the HTML (e.g.
   * `<div stm-content hidden>`); the library removes it once ready. The library
   * also sets `hidden` itself during loading as a fallback for authors who do
   * not pre-set it.
   * @param {boolean} ready
   */
  function setBootState(ready) {
    var preloaders = document.querySelectorAll('[stm-preloader]');
    var contents = document.querySelectorAll('[stm-content]');
    for (var i = 0; i < preloaders.length; i++) {
      ready ? preloaders[i].setAttribute('hidden', '') : preloaders[i].removeAttribute('hidden');
    }
    for (var j = 0; j < contents.length; j++) {
      ready ? contents[j].removeAttribute('hidden') : contents[j].setAttribute('hidden', '');
    }
  }

  // ---------------------------------------------------------------------------
  // Public state accessors
  // ---------------------------------------------------------------------------

  /** Build the scope used for expression evaluation: `{ typeName: public }`. */
  function stateScope() {
    var scope = {};
    store.forEach(function (entry, type) { scope[type] = entry.snapshot.public; });
    return scope;
  }

  /** Read a type's `public` data (what the attributes bind to). */
  function read(type) {
    var entry = store.get(type);
    return entry ? entry.snapshot.public : undefined;
  }

  /** Read a type's full snapshot object. */
  function getSnapshot(type) {
    var entry = store.get(type);
    return entry ? entry.snapshot : undefined;
  }

  /** Read the frame wrapping a type's snapshot. */
  function getFrame(type) {
    var entry = store.get(type);
    return entry ? entry.frame : undefined;
  }

  /** Build an object of `{ typeName: public }` for every held type. */
  function state() {
    var result = {};
    store.forEach(function (entry, type) { result[type] = entry.snapshot.public; });
    return result;
  }

  /**
   * Clear state. With a type argument, clears that type only; without, clears
   * all held state.
   * @param {string} [type]
   */
  function clear(type) {
    if (type === undefined) {
      Array.from(store.keys()).forEach(function (t) { clearType(t, { broadcast: true }); });
    } else {
      clearType(type, { broadcast: true });
    }
    renderAll();
  }

  /**
   * Perform an action. `action` may be an action object or a string path that
   * resolves to an action object within the current state.
   * @param {object|string} action
   * @param {object} [data]
   * @returns {Promise<void>}
   */
  function act(action, data) {
    var resolved = action;
    if (typeof action === 'string') resolved = evalExpr(action, stateScope());
    if (!resolved || typeof resolved.uri !== 'string') {
      return Promise.reject(new StatumError('Invalid action'));
    }
    return performAction(resolved, data, null);
  }

  /** Attach a state listener for a type. */
  function addStateListener(type, callback) {
    if (typeof callback !== 'function') return;
    if (!listeners.has(type)) listeners.set(type, new Set());
    listeners.get(type).add(callback);
  }

  /** Remove a previously-attached state listener. */
  function removeStateListener(type, callback) {
    var set = listeners.get(type);
    if (!set) return;
    set.delete(callback);
    if (set.size === 0) listeners.delete(type);
  }

  // ---------------------------------------------------------------------------
  // Initialization
  // ---------------------------------------------------------------------------

  /**
   * Inject the stylesheet that makes the `hidden` attribute authoritative.
   * Statum toggles `stm-if`/`stm-else` branches and loop holders via
   * `hidden`, whose user-agent rule loses specificity battles to ordinary
   * author CSS (a rule like `li { display: flex }` let hidden loop holders
   * leak as phantom rows). Idempotent: skipped when the stylesheet is
   * already present.
   */
  function injectHiddenStyle() {
    var id = 'statum-hidden-style';
    if (document.getElementById(id)) return;
    var head = document.head;
    if (!head) return;
    var style = document.createElement('style');
    style.id = id;
    style.textContent = '[hidden]{display:none !important}';
    head.appendChild(style);
  }

  /**
   * Scan the document for `pstm-*` attributes and `<pstm-*>` elements, which
   * are intended for server-side pre-rendering and should never reach the
   * browser. Emits a single `console.warn` summarizing them.
   */
  function warnServerSideMarkup() {
    var found = [];
    var els = document.querySelectorAll('*');
    for (var i = 0; i < els.length; i++) {
      var el = els[i];
      var tag = el.tagName.toLowerCase();
      if (tag.indexOf('pstm-') === 0) found.push('<' + tag + '>');
      var attrs = el.attributes;
      for (var j = 0; j < attrs.length; j++) {
        var name = attrs[j].name;
        if (name.indexOf('pstm-') === 0) found.push('<' + tag + '> ' + name);
      }
    }
    if (found.length) {
      console.warn('[statum] ' + found.length + ' server-side pstm-* attribute/element(s) ' +
        'found in the DOM; they should have been resolved during pre-rendering: ' +
        found.slice(0, 10).join(', ') + (found.length > 10 ? ' …' : ''));
    }
  }

  /**
   * Initialize Statum: read URL overrides, run the session-cookie check,
   * hydrate persisted state, open the cross-tab channel, fetch the entrypoint,
   * and render. Safe to call multiple times.
   * @returns {Promise<void>}
   */
  async function init() {
    if (initialized) return;
    initialized = true;

    // Before the first render and the boot visibility toggling, so `hidden`
    // wins over author CSS from the very first paint.
    injectHiddenStyle();

    var body = document.body;
    if (body) {
      if (body.hasAttribute('stm-entrypoint')) config.entrypointUrl = body.getAttribute('stm-entrypoint');
      if (body.hasAttribute('stm-slots')) config.slotsUrl = body.getAttribute('stm-slots');
      if (body.hasAttribute('stm-channel')) config.channelUrl = body.getAttribute('stm-channel');
      if (body.hasAttribute('stm-worker')) config.workerUrl = body.getAttribute('stm-worker');
    }

    try { warnServerSideMarkup(); } catch (e) {}

    try { initSession(); } catch (e) {}
    try { hydrate(); } catch (e) {}
    setupChannel();

    setBootState(false);
    renderAll(); // bind against any persisted/hydrated state immediately

    try {
      await loadEntrypoint();
    } catch (err) {
      console.error('[statum] entrypoint load failed', err);
    } finally {
      setBootState(true);
    }
  }

  function autoInit() {
    if (document.readyState === 'loading') {
      document.addEventListener('DOMContentLoaded', init);
    } else {
      init();
    }
  }

  // ---------------------------------------------------------------------------
  // Public API
  // ---------------------------------------------------------------------------

  /** @namespace statum */
  window.statum = {
    /** Library version. */
    version: '0.1.0',
    /** Mutable endpoint configuration. */
    config: config,
    /** (Re)initialize the library. Usually runs automatically on load. */
    init: init,
    /** Read a type's `public` data. */
    read: read,
    /** Read a type's full snapshot object. */
    getSnapshot: getSnapshot,
    /** Read the frame wrapping a type's snapshot. */
    getFrame: getFrame,
    /** Build `{ typeName: public }` for every held type. */
    state: state,
    /** Clear one type (`clear("x")`) or all state (`clear()`). */
    clear: clear,
    /** Perform an action object or named action. */
    act: act,
    /** Attach a state-changed listener for a type. */
    addStateListener: addStateListener,
    /** Remove a previously-attached listener. */
    removeStateListener: removeStateListener,
    /**
     * Register a handler for an `stm-*` attribute (module seam — see the
     * registry in statum-core.js). `name` is an exact attribute name, or a
     * prefix matcher when it ends with `.`; `opts.after` / `opts.before`
     * order the handler against another registered attribute.
     */
    registerAttribute: registerAttribute,
    /** Register a callback that runs before each render cycle (no arguments). */
    beforeEvaluate: function (fn) { if (typeof fn === 'function') beforeHooks.push(fn); },
    /** Register a callback that runs after each render cycle (no arguments). */
    afterEvaluate: function (fn) { if (typeof fn === 'function') afterHooks.push(fn); },
    /** The Statum error type (thrown by `act` and surfaced to handlers). */
    Error: StatumError,
    get onConfirmHandler() { return handlers.onConfirm; },
    set onConfirmHandler(v) { handlers.onConfirm = typeof v === 'function' ? v : null; },
    get onNotifyHandler() { return handlers.onNotify; },
    set onNotifyHandler(v) { handlers.onNotify = typeof v === 'function' ? v : null; },
    get onErrorHandler() { return handlers.onError; },
    set onErrorHandler(v) { handlers.onError = typeof v === 'function' ? v : null; }
  };

  // The seam must be exposed before any other module loads. autoInit only
  // ever runs on DOMContentLoaded (or immediately at load); both happen
  // outside this script tag, so the later module tags always see the bridge.
  window.statum._bridge = bridge;

  autoInit();
})();