ltcai 2.2.7 → 3.1.0

package/static/v3/js/core/components.js

@@ -0,0 +1,222 @@
+/* ============================================================================
+ * Lattice AI v3 — Component factories
+ * Build the shared vocabulary (cards, panels, stats, tables, states, the
+ * retrieval-lattice pillars …) on top of dom.js + the component CSS. Views
+ * compose these to stay visually consistent.
+ * ========================================================================== */
+
+import { h, icon, fmtNum } from "./dom.js";
+
+/* ── View + section headers ─────────────────────────────────────────────── */
+export function viewHeader({ eyebrow, title, sub, actions } = {}) {
+  return h("header.lt3-vhead",
+    h("div",
+      eyebrow && h("div.lt3-eyebrow", eyebrow),
+      h("h1.lt3-vhead__title", title),
+      sub && h("p.lt3-vhead__sub", sub),
+    ),
+    actions && actions.length && h("div.lt3-vhead__actions", actions),
+  );
+}
+
+export function sectionHead(title, ...actions) {
+  return h("div.lt3-section__head",
+    h("h2.lt3-section__title", title),
+    actions.length && h("div.lt3-row-2", actions),
+  );
+}
+
+/* ── Panel / card ───────────────────────────────────────────────────────── */
+export function panel({ title, sub, actions, head, children, eyebrow, className } = {}) {
+  return h(`section.lt3-panel${className ? "." + className : ""}`,
+    (title || head || actions) && h("div.lt3-panel__head",
+      head || h("div",
+        eyebrow && h("div.lt3-eyebrow", eyebrow),
+        title && h("h3.lt3-panel__title", title),
+        sub && h("p.lt3-panel__sub", sub),
+      ),
+      actions && h("div.lt3-row-2", actions),
+    ),
+    children,
+  );
+}
+
+export function card(children, opts = {}) {
+  const cls = ["lt3-card"];
+  if (opts.interactive) cls.push("lt3-card--interactive");
+  if (opts.flat) cls.push("lt3-card--flat");
+  if (opts.ghost) cls.push("lt3-card--ghost");
+  return h(`div.${cls.join(".")}`, opts.attrs || {}, children);
+}
+
+/* ── Stat tile ──────────────────────────────────────────────────────────── */
+export function stat({ label, value, icon: ic, delta, deltaDir }) {
+  return h("div.lt3-stat",
+    h("div.lt3-stat__label", ic && icon(ic), label),
+    h("div.lt3-stat__value", value == null ? "—" : value),
+    delta && h(`div.lt3-stat__delta${deltaDir ? ".lt3-stat__delta--" + deltaDir : ""}`, delta),
+  );
+}
+
+/* ── Pills / badges ─────────────────────────────────────────────────────── */
+export function pill(text, variant = "", { dot } = {}) {
+  const cls = ["lt3-pill"];
+  if (variant) cls.push("lt3-pill--" + variant);
+  if (dot) cls.push("lt3-pill--dot");
+  return h(`span.${cls.join(".")}`, text);
+}
+
+const STATE_VARIANT = {
+  ready: "ok", active: "ok", indexed: "ok", loaded: "ok", ok: "ok", available: "info",
+  idle: "", standby: "", pending: "warn", indexing: "warn", building: "warn",
+  failed: "err", error: "err", disabled: "err", not_configured: "",
+};
+export function statePill(state) {
+  return pill(String(state || "unknown"), STATE_VARIANT[String(state).toLowerCase()] ?? "", { dot: true });
+}
+
+/** Provenance badge — makes live vs unavailable data explicit. */
+export function sourceBadge(source) {
+  if (source === "live") return h("span.lt3-source.lt3-source--live", icon("circle-filled"), "Live");
+  if (source === "unavailable") return h("span.lt3-source.lt3-source--unavailable", icon("alert-circle"), "Unavailable");
+  return h("span.lt3-source.lt3-source--pending", "—");
+}
+
+/* ── States ─────────────────────────────────────────────────────────────── */
+export function emptyState({ icon: ic = "inbox", title, body, action } = {}) {
+  return h("div.lt3-empty",
+    h("div.lt3-empty__icon", icon(ic)),
+    title && h("div.lt3-empty__title", title),
+    body && h("div.lt3-empty__body", body),
+    action,
+  );
+}
+
+export function loading({ lines = 3, block = false } = {}) {
+  const kids = [];
+  if (block) kids.push(h("div.lt3-skel.lt3-skel--block"));
+  for (let i = 0; i < lines; i++) {
+    kids.push(h("div.lt3-skel.lt3-skel--line", { style: { width: 100 - i * 14 + "%" } }));
+  }
+  return h("div", { "aria-busy": "true", "aria-label": "Loading" }, kids);
+}
+
+export function errorState(message, onRetry) {
+  return h("div.lt3-banner.lt3-banner--err",
+    icon("alert-triangle"),
+    h("div", h("div", { style: { fontWeight: 600 } }, "Couldn't load"), h("div.lt3-faint", message || "Request failed")),
+    onRetry && h("button.lt3-btn.lt3-btn--subtle.lt3-btn--sm", { style: { "margin-left": "auto" }, on: { click: onRetry } }, icon("refresh"), "Retry"),
+  );
+}
+
+export function banner(text, variant = "info", ic = "info-circle") {
+  return h(`div.lt3-banner.lt3-banner--${variant}`, icon(ic), h("div", text));
+}
+
+/* ── Table ──────────────────────────────────────────────────────────────── */
+export function table(columns, rows, { empty } = {}) {
+  if (!rows || !rows.length) {
+    return empty || emptyState({ title: "Nothing here yet", body: "Data will appear once connected." });
+  }
+  return h("div.lt3-table--clip", { style: { overflow: "auto" } },
+    h("table.lt3-table",
+      h("thead", h("tr", columns.map((c) => h("th", { style: c.width ? { width: c.width } : {} }, c.label)))),
+      h("tbody", rows.map((row) => h("tr", columns.map((c) => h("td", c.render ? c.render(row) : row[c.key]))))),
+    ),
+  );
+}
+
+/* ── Tabs / segmented ───────────────────────────────────────────────────── */
+export function tabs(items, active, onChange) {
+  return h("div.lt3-tabs", { role: "tablist" },
+    items.map((it) => h("button.lt3-tab", {
+      role: "tab", type: "button",
+      dataset: { active: String(it.key === active) },
+      "aria-selected": String(it.key === active),
+      on: { click: () => onChange(it.key) },
+    }, it.label)),
+  );
+}
+
+export function segmented(items, active, onChange) {
+  return h("div.lt3-seg", { role: "tablist" },
+    items.map((it) => h("button", {
+      type: "button", role: "tab",
+      dataset: { active: String(it.key === active) },
+      "aria-selected": String(it.key === active),
+      on: { click: () => onChange(it.key) },
+    }, it.label)),
+  );
+}
+
+/* ── Meter ──────────────────────────────────────────────────────────────── */
+export function meter(value, variant = "") {
+  const pct = Math.max(0, Math.min(1, Number(value) || 0)) * 100;
+  return h("div.lt3-meter",
+    h(`div.lt3-meter__fill${variant ? ".lt3-meter__fill--" + variant : ""}`, { style: { width: pct + "%" } }),
+  );
+}
+
+/* ── Retrieval lattice (signature) ──────────────────────────────────────── */
+const PILLAR_DEFS = [
+  { key: "knowledge_graph", kind: "graph", name: "Knowledge Graph", desc: "Entities & relations", icon: "chart-dots-3", unit: "entities", read: (p) => p?.entities },
+  { key: "vector_index", kind: "vector", name: "Vector Index", desc: "Local embedding vectors", icon: "grid-dots", unit: "vectors", read: (p) => p?.vectors },
+  { key: "hybrid", kind: "hybrid", name: "Hybrid Search", desc: "Fused graph + vector", icon: "arrows-join", unit: "fusion", read: (p) => p?.strategy },
+];
+
+export function pillars(indexStatus) {
+  const pipes = indexStatus?.pipelines || {};
+  if (!Object.keys(pipes).length) {
+    return emptyState({
+      icon: "database-off",
+      title: "Retrieval status unavailable",
+      body: "Start the backend with Knowledge Graph enabled to see live index state.",
+    });
+  }
+  return h("div.lt3-pillars",
+    PILLAR_DEFS.map((def) => {
+      const p = pipes[def.key] || {};
+      const raw = def.read(p);
+      const num = typeof raw === "number" ? fmtNum(raw) : (raw || "ready");
+      return h(`article.lt3-pillar.lt3-pillar--${def.kind}`,
+        h("div.lt3-pillar__icon", icon(def.icon)),
+        h("div.lt3-row", { style: { "justify-content": "space-between" } },
+          h("div",
+            h("div.lt3-pillar__name", def.name),
+            h("div.lt3-pillar__desc", def.desc),
+          ),
+          statePill(p.state || "ready"),
+        ),
+        h("div.lt3-pillar__stat",
+          h("span.lt3-pillar__num", num),
+          h("span.lt3-pillar__unit", def.unit),
+        ),
+      );
+    }),
+  );
+}
+
+/** Compact 3-dot index chip for the topbar. */
+export function indexChip(indexStatus) {
+  const pipes = indexStatus?.pipelines || {};
+  const dot = (kind, key) => h("span.lt3-idxchip__dot", {
+    dataset: { kind, on: String((pipes[key]?.state || "ready") === "ready") },
+    title: `${kind}: ${pipes[key]?.state || "—"}`,
+  });
+  return h("div.lt3-idxchip", { title: "Retrieval index status" },
+    h("span.lt3-idxchip__dots", dot("graph", "knowledge_graph"), dot("vector", "vector_index"), dot("hybrid", "hybrid")),
+    h("span", "Index"),
+  );
+}
+
+/* ── Toast ──────────────────────────────────────────────────────────────── */
+export function toast(message, variant = "info") {
+  let host = document.querySelector(".lt3-toasts");
+  if (!host) { host = h("div.lt3-toasts"); document.body.append(host); }
+  const ic = variant === "ok" ? "circle-check" : variant === "err" ? "alert-circle" : "info-circle";
+  const node = h(`div.lt3-toast.lt3-toast--${variant}`, icon(ic), h("div", message));
+  host.append(node);
+  setTimeout(() => { node.style.opacity = "0"; node.style.transition = "opacity .3s"; setTimeout(() => node.remove(), 300); }, 3200);
+}
+
+export { icon, fmtNum };

package/static/v3/js/core/dom.a2773eb0.js

@@ -0,0 +1,148 @@
+/* ============================================================================
+ * Lattice AI v3 — DOM helpers
+ * A tiny, dependency-free hyperscript. Builds real DOM nodes (no innerHTML for
+ * dynamic content → no injection surface). Ergonomic enough to author views.
+ * ========================================================================== */
+
+/**
+ * h("div.card#id", { props }, ...children)
+ *   - tag selector supports .class (many) and #id
+ *   - props: class | className, id, on:{event:fn}, dataset:{k:v},
+ *            style:{k:v} or string, html (trusted innerHTML), attrs (any other)
+ *   - children: Node | string | number | falsy (skipped) | array (flattened)
+ */
+export function h(selector, props, ...children) {
+  const { tag, id, classes } = parseSelector(selector);
+  const el = document.createElement(tag);
+  if (id) el.id = id;
+  if (classes.length) el.classList.add(...classes);
+
+  if (props && (props.nodeType || typeof props === "string" || Array.isArray(props))) {
+    children.unshift(props);
+    props = null;
+  }
+
+  if (props) {
+    for (const [key, val] of Object.entries(props)) {
+      if (val == null || val === false) continue;
+      if (key === "class" || key === "className") {
+        for (const c of String(val).split(/\s+/).filter(Boolean)) el.classList.add(c);
+      } else if (key === "on" && typeof val === "object") {
+        for (const [ev, fn] of Object.entries(val)) el.addEventListener(ev, fn);
+      } else if (key === "dataset" && typeof val === "object") {
+        for (const [k, v] of Object.entries(val)) { if (v != null) el.dataset[k] = v; }
+      } else if (key === "style" && typeof val === "object") {
+        for (const [k, v] of Object.entries(val)) el.style.setProperty(k, v);
+      } else if (key === "style") {
+        el.setAttribute("style", val);
+      } else if (key === "html") {
+        el.innerHTML = val;
+      } else if (key === "ref" && typeof val === "function") {
+        val(el);
+      } else if (key in el && key !== "list" && typeof val !== "object") {
+        try { el[key] = val; } catch { el.setAttribute(key, val); }
+      } else {
+        el.setAttribute(key, val === true ? "" : val);
+      }
+    }
+  }
+
+  appendChildren(el, children);
+  return el;
+}
+
+function parseSelector(sel) {
+  if (typeof sel !== "string") return { tag: "div", id: "", classes: [] };
+  const idMatch = sel.match(/#([\w-]+)/);
+  const id = idMatch ? idMatch[1] : "";
+  const classes = (sel.match(/\.([\w-]+)/g) || []).map((c) => c.slice(1));
+  const tag = (sel.match(/^([\w-]+)/) || [, "div"])[1];
+  return { tag, id, classes };
+}
+
+function appendChildren(el, children) {
+  for (const child of children.flat(Infinity)) {
+    if (child == null || child === false || child === true) continue;
+    el.append(child.nodeType ? child : document.createTextNode(String(child)));
+  }
+}
+
+/** Fragment of many children. */
+export function frag(...children) {
+  const f = document.createDocumentFragment();
+  appendChildren(f, children);
+  return f;
+}
+
+/** Replace the contents of a node. */
+export function render(host, ...children) {
+  host.replaceChildren();
+  appendChildren(host, children);
+  return host;
+}
+
+export function clear(host) { host.replaceChildren(); return host; }
+
+export function escapeHtml(s) {
+  return String(s == null ? "" : s).replace(/[&<>"']/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+}
+
+export const $ = (sel, root = document) => root.querySelector(sel);
+export const $$ = (sel, root = document) => Array.from(root.querySelectorAll(sel));
+
+/** Tabler icon element: icon("home") → <i class="ti ti-home"> */
+export function icon(name, extra = "") {
+  const i = document.createElement("i");
+  i.className = `ti ti-${name}${extra ? " " + extra : ""}`;
+  i.setAttribute("aria-hidden", "true");
+  i.setAttribute("data-fallback", iconFallback(name));
+  return i;
+}
+
+function iconFallback(name) {
+  const map = {
+    home: "H", search: "?", menu: "=", x: "x", refresh: "R",
+    "arrow-up": "^", "arrow-up-right": ">", "arrows-join": "H",
+    "chart-dots-3": "G", "grid-dots": "V", message: "C", "message-2": "C",
+    "message-plus": "+", "message-off": "C", user: "U", users: "U",
+    settings: "S", files: "F", cpu: "M", "cpu-off": "M", "player-play": ">",
+    "player-stop": "s", "layout-sidebar": "<", "layout-sidebar-right": ">",
+    "external-link": "o", trash: "x", sparkles: "*", "alert-triangle": "!",
+    "alert-circle": "!", "info-circle": "i", "circle-check": "v",
+    "circle-filled": "*", "stack-2": "S", "ruler-2": "R", binary: "B",
+    category: "T", abc: "K", "search-off": "?"
+  };
+  if (map[name]) return map[name];
+  return String(name || "?").split("-").map((part) => part[0] || "").join("").slice(0, 2).toUpperCase() || "?";
+}
+
+/** Compact relative-time formatter. */
+export function timeAgo(value) {
+  if (!value) return "";
+  const then = new Date(value).getTime();
+  if (Number.isNaN(then)) return String(value);
+  const diff = Math.max(0, Date.now() - then);
+  const mins = Math.floor(diff / 60000);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h ago`;
+  const days = Math.floor(hrs / 24);
+  if (days < 30) return `${days}d ago`;
+  return new Date(then).toLocaleDateString();
+}
+
+/** Format a number with thousands separators / compact suffix. */
+export function fmtNum(n) {
+  if (n == null || Number.isNaN(Number(n))) return "—";
+  const v = Number(n);
+  if (Math.abs(v) >= 1_000_000) return (v / 1_000_000).toFixed(1).replace(/\.0$/, "") + "M";
+  if (Math.abs(v) >= 1_000) return (v / 1_000).toFixed(1).replace(/\.0$/, "") + "k";
+  return v.toLocaleString();
+}
+
+export function debounce(fn, ms = 220) {
+  let t;
+  return (...args) => { clearTimeout(t); t = setTimeout(() => fn(...args), ms); };
+}

package/static/v3/js/core/dom.js

@@ -0,0 +1,148 @@
+/* ============================================================================
+ * Lattice AI v3 — DOM helpers
+ * A tiny, dependency-free hyperscript. Builds real DOM nodes (no innerHTML for
+ * dynamic content → no injection surface). Ergonomic enough to author views.
+ * ========================================================================== */
+
+/**
+ * h("div.card#id", { props }, ...children)
+ *   - tag selector supports .class (many) and #id
+ *   - props: class | className, id, on:{event:fn}, dataset:{k:v},
+ *            style:{k:v} or string, html (trusted innerHTML), attrs (any other)
+ *   - children: Node | string | number | falsy (skipped) | array (flattened)
+ */
+export function h(selector, props, ...children) {
+  const { tag, id, classes } = parseSelector(selector);
+  const el = document.createElement(tag);
+  if (id) el.id = id;
+  if (classes.length) el.classList.add(...classes);
+
+  if (props && (props.nodeType || typeof props === "string" || Array.isArray(props))) {
+    children.unshift(props);
+    props = null;
+  }
+
+  if (props) {
+    for (const [key, val] of Object.entries(props)) {
+      if (val == null || val === false) continue;
+      if (key === "class" || key === "className") {
+        for (const c of String(val).split(/\s+/).filter(Boolean)) el.classList.add(c);
+      } else if (key === "on" && typeof val === "object") {
+        for (const [ev, fn] of Object.entries(val)) el.addEventListener(ev, fn);
+      } else if (key === "dataset" && typeof val === "object") {
+        for (const [k, v] of Object.entries(val)) { if (v != null) el.dataset[k] = v; }
+      } else if (key === "style" && typeof val === "object") {
+        for (const [k, v] of Object.entries(val)) el.style.setProperty(k, v);
+      } else if (key === "style") {
+        el.setAttribute("style", val);
+      } else if (key === "html") {
+        el.innerHTML = val;
+      } else if (key === "ref" && typeof val === "function") {
+        val(el);
+      } else if (key in el && key !== "list" && typeof val !== "object") {
+        try { el[key] = val; } catch { el.setAttribute(key, val); }
+      } else {
+        el.setAttribute(key, val === true ? "" : val);
+      }
+    }
+  }
+
+  appendChildren(el, children);
+  return el;
+}
+
+function parseSelector(sel) {
+  if (typeof sel !== "string") return { tag: "div", id: "", classes: [] };
+  const idMatch = sel.match(/#([\w-]+)/);
+  const id = idMatch ? idMatch[1] : "";
+  const classes = (sel.match(/\.([\w-]+)/g) || []).map((c) => c.slice(1));
+  const tag = (sel.match(/^([\w-]+)/) || [, "div"])[1];
+  return { tag, id, classes };
+}
+
+function appendChildren(el, children) {
+  for (const child of children.flat(Infinity)) {
+    if (child == null || child === false || child === true) continue;
+    el.append(child.nodeType ? child : document.createTextNode(String(child)));
+  }
+}
+
+/** Fragment of many children. */
+export function frag(...children) {
+  const f = document.createDocumentFragment();
+  appendChildren(f, children);
+  return f;
+}
+
+/** Replace the contents of a node. */
+export function render(host, ...children) {
+  host.replaceChildren();
+  appendChildren(host, children);
+  return host;
+}
+
+export function clear(host) { host.replaceChildren(); return host; }
+
+export function escapeHtml(s) {
+  return String(s == null ? "" : s).replace(/[&<>"']/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+}
+
+export const $ = (sel, root = document) => root.querySelector(sel);
+export const $$ = (sel, root = document) => Array.from(root.querySelectorAll(sel));
+
+/** Tabler icon element: icon("home") → <i class="ti ti-home"> */
+export function icon(name, extra = "") {
+  const i = document.createElement("i");
+  i.className = `ti ti-${name}${extra ? " " + extra : ""}`;
+  i.setAttribute("aria-hidden", "true");
+  i.setAttribute("data-fallback", iconFallback(name));
+  return i;
+}
+
+function iconFallback(name) {
+  const map = {
+    home: "H", search: "?", menu: "=", x: "x", refresh: "R",
+    "arrow-up": "^", "arrow-up-right": ">", "arrows-join": "H",
+    "chart-dots-3": "G", "grid-dots": "V", message: "C", "message-2": "C",
+    "message-plus": "+", "message-off": "C", user: "U", users: "U",
+    settings: "S", files: "F", cpu: "M", "cpu-off": "M", "player-play": ">",
+    "player-stop": "s", "layout-sidebar": "<", "layout-sidebar-right": ">",
+    "external-link": "o", trash: "x", sparkles: "*", "alert-triangle": "!",
+    "alert-circle": "!", "info-circle": "i", "circle-check": "v",
+    "circle-filled": "*", "stack-2": "S", "ruler-2": "R", binary: "B",
+    category: "T", abc: "K", "search-off": "?"
+  };
+  if (map[name]) return map[name];
+  return String(name || "?").split("-").map((part) => part[0] || "").join("").slice(0, 2).toUpperCase() || "?";
+}
+
+/** Compact relative-time formatter. */
+export function timeAgo(value) {
+  if (!value) return "";
+  const then = new Date(value).getTime();
+  if (Number.isNaN(then)) return String(value);
+  const diff = Math.max(0, Date.now() - then);
+  const mins = Math.floor(diff / 60000);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h ago`;
+  const days = Math.floor(hrs / 24);
+  if (days < 30) return `${days}d ago`;
+  return new Date(then).toLocaleDateString();
+}
+
+/** Format a number with thousands separators / compact suffix. */
+export function fmtNum(n) {
+  if (n == null || Number.isNaN(Number(n))) return "—";
+  const v = Number(n);
+  if (Math.abs(v) >= 1_000_000) return (v / 1_000_000).toFixed(1).replace(/\.0$/, "") + "M";
+  if (Math.abs(v) >= 1_000) return (v / 1_000).toFixed(1).replace(/\.0$/, "") + "k";
+  return v.toLocaleString();
+}
+
+export function debounce(fn, ms = 220) {
+  let t;
+  return (...args) => { clearTimeout(t); t = setTimeout(() => fn(...args), ms); };
+}

package/static/v3/js/core/router.584570f2.js

@@ -0,0 +1,37 @@
+/* ============================================================================
+ * Lattice AI v3 — Hash router
+ * Maps location.hash → { key, params }. Hash routing keeps the SPA shell
+ * served by a single static route (/app) with no server-side rewrites.
+ *   #/home                  → { key: "home" }
+ *   #/admin/users           → { key: "admin/users" }
+ *   #/chat?new=1            → { key: "chat", params: { new: "1" } }
+ * ========================================================================== */
+
+export function createRouter({ onRoute, fallback = "home" }) {
+  function parse() {
+    let hash = location.hash.replace(/^#\/?/, "");
+    let query = "";
+    const qi = hash.indexOf("?");
+    if (qi >= 0) { query = hash.slice(qi + 1); hash = hash.slice(0, qi); }
+    const key = hash.replace(/\/+$/, "") || fallback;
+    const params = {};
+    if (query) new URLSearchParams(query).forEach((v, k) => { params[k] = v; });
+    return { key, params };
+  }
+
+  function handle() { onRoute(parse()); }
+
+  return {
+    start() {
+      window.addEventListener("hashchange", handle);
+      if (!location.hash) { location.replace("#/" + fallback); }
+      else { handle(); }
+    },
+    current: parse,
+    navigate(key, params) {
+      const qs = params && Object.keys(params).length ? "?" + new URLSearchParams(params).toString() : "";
+      const next = "#/" + String(key).replace(/^#?\/?/, "") + qs;
+      if (location.hash === next) handle(); else location.hash = next;
+    },
+  };
+}

package/static/v3/js/core/router.js

@@ -0,0 +1,37 @@
+/* ============================================================================
+ * Lattice AI v3 — Hash router
+ * Maps location.hash → { key, params }. Hash routing keeps the SPA shell
+ * served by a single static route (/app) with no server-side rewrites.
+ *   #/home                  → { key: "home" }
+ *   #/admin/users           → { key: "admin/users" }
+ *   #/chat?new=1            → { key: "chat", params: { new: "1" } }
+ * ========================================================================== */
+
+export function createRouter({ onRoute, fallback = "home" }) {
+  function parse() {
+    let hash = location.hash.replace(/^#\/?/, "");
+    let query = "";
+    const qi = hash.indexOf("?");
+    if (qi >= 0) { query = hash.slice(qi + 1); hash = hash.slice(0, qi); }
+    const key = hash.replace(/\/+$/, "") || fallback;
+    const params = {};
+    if (query) new URLSearchParams(query).forEach((v, k) => { params[k] = v; });
+    return { key, params };
+  }
+
+  function handle() { onRoute(parse()); }
+
+  return {
+    start() {
+      window.addEventListener("hashchange", handle);
+      if (!location.hash) { location.replace("#/" + fallback); }
+      else { handle(); }
+    },
+    current: parse,
+    navigate(key, params) {
+      const qs = params && Object.keys(params).length ? "?" + new URLSearchParams(params).toString() : "";
+      const next = "#/" + String(key).replace(/^#?\/?/, "") + qs;
+      if (location.hash === next) handle(); else location.hash = next;
+    },
+  };
+}