@mauroandre/velojs 0.0.55 → 0.0.57

package/dist/channels.js

@@ -0,0 +1,376 @@
+import { DEFAULT_HEARTBEAT_MS as J } from "./events.js";
+const U = "snapshot", V = "slice", ne = "error", oe = "close", H = 50, W = 3e5;
+let d = {}, O = H, M = W, N = J, F = !0;
+function ye(e, t) {
+  d = e ? { ...e } : {}, O = t?.coalesceMs ?? H, M = t?.idleMs ?? W, N = t?.heartbeatMs ?? J, F = t?.logEmits ?? !0, Q(), E.clear();
+}
+function we() {
+  return d;
+}
+function ge() {
+  return Object.keys(d);
+}
+const f = /* @__PURE__ */ new Map(), E = /* @__PURE__ */ new Map(), $ = /* @__PURE__ */ new Map();
+function se(e, t) {
+  const r = P(e, t);
+  if ($.has(r)) return;
+  const n = setTimeout(() => {
+    $.delete(r), Y(e, t);
+  }, O), o = n.unref;
+  typeof o == "function" && o.call(n), $.set(r, { timer: n, channel: e, partition: t });
+}
+function Q() {
+  for (const e of $.values()) clearTimeout(e.timer);
+  $.clear();
+}
+function ve() {
+  const e = [];
+  let t = 0;
+  for (const [n, o] of f) {
+    const s = [];
+    for (const [l, c] of o) {
+      const p = /* @__PURE__ */ new Map();
+      for (const a of c) {
+        const u = p.get(a.moduleId) ?? { count: 0, last: void 0 };
+        u.count += 1, a.lastDeliveryAt !== void 0 && (u.last === void 0 || a.lastDeliveryAt > u.last) && (u.last = a.lastDeliveryAt), p.set(a.moduleId, u);
+      }
+      for (const [a, u] of p)
+        s.push({
+          moduleId: a,
+          partition: l,
+          connections: u.count,
+          lastDeliveryAt: u.last === void 0 ? null : new Date(u.last).toISOString()
+        });
+    }
+    e.push({
+      channel: n,
+      groups: s,
+      connections: q(o)
+    }), t += q(o);
+  }
+  const r = [];
+  for (const n of $.values())
+    r.push({ channel: n.channel, partition: n.partition });
+  return { channels: e, openCoalesceWindows: r, totalConnections: t };
+}
+function q(e) {
+  let t = 0;
+  for (const r of e.values()) t += r.size;
+  return t;
+}
+function P(e, t) {
+  return `${e}\0${t}`;
+}
+function ie(e) {
+  let t = f.get(e.channel);
+  t || (t = /* @__PURE__ */ new Map(), f.set(e.channel, t));
+  let r = t.get(e.partition);
+  r || (r = /* @__PURE__ */ new Set(), t.set(e.partition, r));
+  const n = r.size === 0;
+  return r.add(e), n;
+}
+function x(e) {
+  const t = f.get(e.channel), r = t?.get(e.partition);
+  if (!t || !r) return !1;
+  r.delete(e);
+  const n = r.size === 0;
+  return n && t.delete(e.partition), t.size === 0 && f.delete(e.channel), n;
+}
+function B(e, t, r) {
+  const n = P(e, t), o = d[e]?.onGroupOpen, s = (async () => {
+    if (typeof o == "function")
+      try {
+        await o({ partition: t, params: r });
+      } catch (l) {
+        console.error(
+          `[velojs] channel "${e}" onGroupOpen failed for partition "${t}":`,
+          l
+        );
+      }
+  })();
+  return E.set(n, s), s.then(() => {
+    E.get(n) === s && E.delete(n);
+  }), s;
+}
+async function ae(e) {
+  const t = P(e.channel, e.partition), r = E.get(t);
+  r && await r;
+  const n = f.get(e.channel)?.get(e.partition);
+  if (!n || !n.has(e) || n.size > 1) {
+    x(e);
+    return;
+  }
+  const o = d[e.channel]?.onGroupClose;
+  if (typeof o == "function")
+    try {
+      await o({ partition: e.partition });
+    } catch (c) {
+      console.error(
+        `[velojs] channel "${e.channel}" onGroupClose failed for partition "${e.partition}":`,
+        c
+      );
+    }
+  x(e);
+  const s = f.get(e.channel)?.get(e.partition), l = s ? [...s][0] : void 0;
+  l && await B(e.channel, e.partition, l.params);
+}
+function Ee() {
+  f.clear(), E.clear(), Q();
+}
+async function T(e, t) {
+  const r = e.scope;
+  return typeof r != "function" ? "all" : await r(t);
+}
+function le(e, t) {
+  return e.get(t);
+}
+async function K(e, t) {
+  const r = f.get(e)?.get(t);
+  if (!r || r.size === 0) return null;
+  const n = d[e], o = [];
+  for (const s of [...r]) {
+    let l;
+    try {
+      l = await T(n, {
+        user: s.principal,
+        params: s.params
+      });
+    } catch (c) {
+      console.error(`[velojs] channel "${e}" scope threw on emit:`, c), l = null;
+    }
+    if (l == null || l !== t) {
+      await s.terminate();
+      continue;
+    }
+    o.push(s);
+  }
+  return o.length > 0 ? o : null;
+}
+async function Y(e, t) {
+  const r = await K(e, t);
+  r && await Promise.all(r.map((n) => X(n)));
+}
+async function X(e) {
+  let t;
+  try {
+    t = await e.loader({
+      params: e.params,
+      query: e.query,
+      c: e.c
+    });
+  } catch (r) {
+    await e.send(
+      ne,
+      JSON.stringify({
+        message: r instanceof Error ? r.message : String(r)
+      })
+    );
+    return;
+  }
+  t instanceof Response || await e.send(U, JSON.stringify(t ?? null));
+}
+function $e(e, t, r, n) {
+  return typeof e == "string" ? ue(e, t ?? {}) : ce(e, t, r, n);
+}
+async function ue(e, t) {
+  const r = d[e];
+  if (!r)
+    throw new Error(
+      `[velojs] emit("${e}"): this channel has no entry in app/channels.ts. Add one — a typo or a renamed channel would otherwise be a silent no-op.`
+    );
+  const n = await T(r, t), o = n == null ? 0 : f.get(e)?.get(n)?.size ?? 0;
+  if (Z(e, n, "invalidate", o), n != null && o !== 0) {
+    if (O <= 0) {
+      await Y(e, n);
+      return;
+    }
+    se(e, n);
+  }
+}
+async function ce(e, t, r, n) {
+  const o = e?.metadata?.moduleId;
+  if (!o)
+    throw new Error(
+      `[velojs] emit(module, "${t}", …): the module has no metadata.moduleId — pass the imported route module (the Vite plugin injects its metadata), the same object the route tree uses.`
+    );
+  const s = e.channels;
+  if (!Array.isArray(s) || !s.includes(t))
+    throw new Error(
+      `[velojs] emit(module, "${t}", …): module "${o}" does not declare channel "${t}" — add it to the module's \`channels\` export, or use emit("${t}", ctx) for the invalidation mode.`
+    );
+  if (typeof e.loader != "function")
+    throw new Error(
+      `[velojs] emit(module, "${t}", …): module "${o}" has no \`loader\` — there is no data shape to slice.`
+    );
+  const l = d[t];
+  if (!l)
+    throw new Error(
+      `[velojs] emit(module, "${t}", …): this channel has no entry in app/channels.ts. Add one — a typo or a renamed channel would otherwise be a silent no-op.`
+    );
+  if (n === null || typeof n != "object" || Array.isArray(n))
+    throw new Error(
+      `[velojs] emit(module, "${t}", …): the slice must be the object of changed keys — got ${n === null ? "null" : Array.isArray(n) ? "an array" : typeof n}.`
+    );
+  const c = await T(l, r), p = c == null ? void 0 : f.get(t)?.get(c), a = p?.size ?? 0;
+  if (Z(t, c, "slice", a), c == null || !p || a === 0) return;
+  const u = await K(t, c);
+  if (!u) return;
+  const w = u.filter((g) => g.moduleId === o);
+  if (w.length === 0) return;
+  const S = JSON.stringify(n);
+  await Promise.all(w.map((g) => g.send(V, S)));
+}
+function Z(e, t, r, n) {
+  if (!F) return;
+  const o = typeof t == "string" ? `"${t}"` : "null";
+  console.log(
+    `[velojs] emit kind=${r} channel="${e}" partition=${o} connections=${n} at=${(/* @__PURE__ */ new Date()).toISOString()}`
+  );
+}
+function fe(e, t) {
+  let r = Promise.resolve();
+  return (n) => (r = r.then(() => t(n)).then(() => {
+  }).catch((o) => {
+    console.warn(
+      `[velojs] channel "${e}": SSE write failed — the snapshot did not reach the client:`,
+      o
+    );
+  }), r);
+}
+const C = "_route";
+function de(e) {
+  return e ? e.split("/").filter((t) => t.startsWith(":")).map((t) => t.slice(1)) : [];
+}
+function pe(e, t) {
+  if (e == null || e === "")
+    return { params: {}, error: null };
+  let r;
+  try {
+    r = JSON.parse(e);
+  } catch {
+    return { params: {}, error: `the ?${C}= payload is not valid JSON` };
+  }
+  if (r === null || typeof r != "object" || Array.isArray(r))
+    return {
+      params: {},
+      error: `the ?${C}= payload must be an object of route params`
+    };
+  const n = {};
+  for (const [o, s] of Object.entries(r)) {
+    if (!t.includes(o)) {
+      const l = t.length > 0 ? t.join(", ") : "none";
+      return {
+        params: {},
+        error: `route param "${o}" is not declared by the module's path (declared: ${l})`
+      };
+    }
+    if (typeof s != "string")
+      return { params: {}, error: `route param "${o}" must be a URL string` };
+    n[o] = s;
+  }
+  return { params: n, error: null };
+}
+function Se(e, t, r, n, o, s) {
+  if (typeof n.loader != "function")
+    throw new Error(
+      `[velojs] module "${o}" declares \`channels\` without a \`loader\` — there is nothing to synchronize. Add a loader or remove the export.`
+    );
+  if (!d[r])
+    throw new Error(
+      `[velojs] module "${o}" declares channel "${r}" with no entry in app/channels.ts — add the partition resolver for "${r}".`
+    );
+  const l = n.loader, c = de(n.metadata?.fullPath), p = async (a) => {
+    const u = d[r], w = pe(
+      a.req.query(C),
+      c
+    );
+    if (w.error)
+      return console.error(`[velojs] channel "${r}": rejecting subscription — ${w.error}`), a.json({ error: "invalid-route-params", message: w.error }, 400);
+    const S = w.params, g = le(a, "user");
+    let b;
+    try {
+      b = await T(u, { user: g, params: S });
+    } catch (h) {
+      return console.error(`[velojs] channel "${r}" scope threw:`, h), a.json({ error: "forbidden" }, 403);
+    }
+    if (b == null)
+      return a.json({ error: "forbidden" }, 403);
+    const { streamSSE: ee } = await import("hono/streaming"), D = {};
+    for (const [h, m] of Object.entries(a.req.query()))
+      h !== C && (D[h] = m);
+    const A = await ee(a, async (h) => {
+      let m = !1, R = () => {
+      };
+      const te = new Promise((i) => {
+        R = i;
+      }), _ = fe(
+        r,
+        (i) => typeof i == "string" ? h.write(i) : h.writeSSE(i)
+      ), j = {
+        channel: r,
+        partition: b,
+        moduleId: o,
+        principal: g,
+        loader: l,
+        c: a,
+        params: S,
+        query: D,
+        send: (i, G) => m ? Promise.resolve() : i === U || i === V ? _({ event: i, data: G }).then(() => {
+          m || (j.lastDeliveryAt = Date.now(), L());
+        }) : _({ event: i, data: G }),
+        terminate: (i) => z(i)
+      }, k = () => {
+        m || (m = !0, y !== null && clearTimeout(y), v !== null && clearInterval(v), R(), ae(j));
+      }, z = async (i = "partition") => {
+        m || (await j.send(oe, JSON.stringify({ reason: i })), k());
+      };
+      let y = null;
+      const L = () => {
+        if (M <= 0 || m) return;
+        y !== null && clearTimeout(y), y = setTimeout(() => {
+          y = null, z("idle");
+        }, M);
+        const i = y.unref;
+        typeof i == "function" && i.call(y);
+      };
+      let v = null;
+      N > 0 && (v = setInterval(() => {
+        m || _(`: ping
+
+`);
+      }, N));
+      const re = ie(j);
+      if (h.onAbort(k), L(), v !== null) {
+        const i = v.unref;
+        typeof i == "function" && i.call(v);
+      }
+      re && await B(r, b, S), await X(j), await te;
+    }), I = new Headers(A.headers);
+    return I.set("Cache-Control", "no-store"), new Response(A.body, {
+      status: A.status,
+      statusText: A.statusText,
+      headers: I
+    });
+  };
+  s.length > 0 ? e.on(["GET"], [t], ...s, p) : e.on(["GET"], [t], p);
+}
+export {
+  oe as CHANNEL_CLOSE_EVENT,
+  ne as CHANNEL_ERROR_EVENT,
+  H as DEFAULT_COALESCE_MS,
+  W as DEFAULT_IDLE_MS,
+  C as ROUTE_PARAMS_QUERY,
+  V as SLICE_EVENT,
+  U as SNAPSHOT_EVENT,
+  Ee as __resetChannels,
+  ge as channelNames,
+  fe as createChannelWriteChain,
+  de as declaredRouteParams,
+  $e as emit,
+  we as getChannelMap,
+  ve as inspectChannels,
+  pe as parseRouteParamsQuery,
+  X as pushSnapshot,
+  Se as registerChannelRoute,
+  ye as registerChannels
+};

package/dist/client.js

@@ -1,92 +1,103 @@
-import { jsxs as j, jsx as o } from "preact/jsx-runtime";
-import { hydrate as w } from "preact";
-import { Router as x, Route as a, Switch as $, useLocation as S } from "wouter-preact";
-import { useEffect as b } from "preact/hooks";
+import { jsxs as w, jsx as r } from "preact/jsx-runtime";
+import { hydrate as x } from "preact";
+import { Router as S, Route as f, Switch as y, useLocation as b } from "wouter-preact";
+import { useEffect as B } from "preact/hooks";
 import { registerRoutePatterns as L, syncLocation as W } from "./loader-store.js";
-const s = (t, n, e) => n ? e && n === "/" ? t || "/" : n.startsWith("/") ? t + n : t + "/" + n : t, v = (t) => t === "" ? "*" : `${t}/*?`, E = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), M = (t) => {
+import { ChannelBoundary as v } from "./live-loader.js";
+const l = (t, n, e) => n ? e && n === "/" ? t || "/" : n.startsWith("/") ? t + n : t + "/" + n : t, E = (t) => t === "" ? "*" : `${t}/*?`, I = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), M = (t) => {
   let n = !1;
   t.endsWith("/*?") && (t = t.slice(0, -3), n = !0);
-  const e = t.split("/").map((c) => c.startsWith(":") ? "[^/]+" : E(c)).join("/");
+  const e = t.split("/").map((c) => c.startsWith(":") ? "[^/]+" : I(c)).join("/");
   return n ? `${e}(?:/.*)?` : e;
-}, p = (t, n) => {
+}, d = (t, n) => {
   if (t.path === "*") return [];
   if (!t.module) {
-    const c = s(n, t.path, !1);
-    return (t.children ?? []).flatMap((i) => p(i, c));
+    const c = l(n, t.path, !1);
+    return (t.children ?? []).flatMap((i) => d(i, c));
   }
   if (!t.children)
-    return [s(n, t.path, !0) || "/"];
+    return [l(n, t.path, !0) || "/"];
   if (t.path)
-    return [`${s(n, t.path, !1)}/*?`];
-  const e = s(n, t.path, !1);
-  return (t.children ?? []).flatMap((c) => p(c, e));
+    return [`${l(n, t.path, !1)}/*?`];
+  const e = l(n, t.path, !1);
+  return (t.children ?? []).flatMap((c) => d(c, e));
 }, _ = (t, n) => {
-  const e = p(t, n);
+  const e = d(t, n);
   return new RegExp(`^(?:${e.map(M).join("|")})$`);
-}, R = (t) => {
+}, C = (t) => {
   for (const n of t) {
     if (n.path === "*" && n.module) return n.module.Component;
     if (n.children) {
-      const e = R(n.children);
+      const e = C(n.children);
       if (e) return e;
     }
   }
   return null;
-}, y = (t, n) => n ? [...t, /* @__PURE__ */ o(a, { children: /* @__PURE__ */ o(n, {}) }, "__notfound")] : t, h = (t, n, e, c) => {
+}, R = (t, n) => n ? [...t, /* @__PURE__ */ r(f, { children: /* @__PURE__ */ r(n, {}) }, "__notfound")] : t, h = (t, n, e, c) => {
   const i = [];
-  for (let u = 0; u < t.length; u++) {
-    const r = t[u], l = `${c}${u}`;
-    if (r.path === "*") continue;
-    if (!r.module) {
-      if (r.children) {
-        const f = s(n, r.path, !1);
-        i.push(...h(r.children, f, e, `${l}-`));
+  for (let a = 0; a < t.length; a++) {
+    const o = t[a], s = `${c}${a}`;
+    if (o.path === "*") continue;
+    if (!o.module) {
+      if (o.children) {
+        const u = l(n, o.path, !1);
+        i.push(...h(o.children, u, e, `${s}-`));
       }
       continue;
     }
-    const d = r.module.Component;
-    if (!r.children) {
-      const f = s(n, r.path, !0) || "/";
+    const p = o.module.Component, m = (u) => /* @__PURE__ */ r(
+      v,
+      {
+        moduleId: o.module?.metadata?.moduleId,
+        channels: o.module?.channels,
+        fullPath: o.module?.metadata?.fullPath,
+        children: u
+      }
+    );
+    if (!o.children) {
+      const u = l(n, o.path, !0) || "/";
       i.push(
-        /* @__PURE__ */ o(a, { path: f, children: /* @__PURE__ */ o(d, {}) }, l)
+        /* @__PURE__ */ r(f, { path: u, children: m(/* @__PURE__ */ r(p, {})) }, s)
       );
       continue;
     }
-    if (r.isRoot) {
+    if (o.isRoot) {
       i.push(
-        /* @__PURE__ */ o($, { children: y(
-          h(r.children, "", e, `${l}-`),
+        /* @__PURE__ */ r(y, { children: R(
+          h(o.children, "", e, `${s}-`),
           e
-        ) }, l)
+        ) }, s)
       );
       continue;
     }
-    const m = s(n, r.path, !1), C = r.path ? v(m) : _(r, n);
+    const $ = l(n, o.path, !1), j = o.path ? E($) : _(o, n);
     i.push(
-      /* @__PURE__ */ o(a, { path: C, children: /* @__PURE__ */ o(d, { children: /* @__PURE__ */ o($, { children: y(
-        h(r.children, m, e, `${l}-`),
-        e
-      ) }) }) }, l)
+      /* @__PURE__ */ r(f, { path: j, children: m(
+        /* @__PURE__ */ r(p, { children: /* @__PURE__ */ r(y, { children: R(
+          h(o.children, $, e, `${s}-`),
+          e
+        ) }) })
+      ) }, s)
     );
   }
   return i;
 }, g = () => {
-  const [t] = S();
-  return b(() => {
+  const [t] = b();
+  return B(() => {
     W(window.location.pathname);
   }, [t]), null;
 }, k = ({ routes: t }) => {
   L(t);
-  const n = R(t), e = h(t, "", n, "");
-  return /* @__PURE__ */ j(x, { children: [
-    /* @__PURE__ */ o(g, {}),
+  const n = C(t), e = h(t, "", n, "");
+  return /* @__PURE__ */ w(S, { children: [
+    /* @__PURE__ */ r(g, {}),
     e
   ] });
-}, z = (t) => {
+}, H = (t) => {
   const { routes: n } = t, e = document.querySelector("body");
-  e && w(/* @__PURE__ */ o(k, { routes: n }), e);
+  e && x(/* @__PURE__ */ r(k, { routes: n }), e);
 };
 export {
   k as ClientRoutes,
-  z as startClient
+  H as startClient
 };

package/dist/components.js

@@ -3,7 +3,8 @@ import { useRouter as L, Link as $ } from "wouter-preact";
 import "@preact/signals";
 import "preact/hooks";
 import { __veloUpdatePending as C } from "./loader-store.js";
-function w({ basePath: t, favicon: e = "/favicon.ico" } = {}) {
+import "./live-loader.js";
+function y({ basePath: t, favicon: e = "/favicon.ico" } = {}) {
   const n = process.env.NODE_ENV !== "production";
   t = t || process.env.STATIC_BASE_URL || (process.env.VELO_STATIC ? "/client" : "");
   const s = e === !1 ? void 0 : e.endsWith(".svg") ? "image/svg+xml" : e.endsWith(".png") ? "image/png" : "image/x-icon", i = e !== !1 && /* @__PURE__ */ r("link", { rel: "icon", href: `${t}${e}`, type: s });
@@ -25,7 +26,7 @@ function S({ localStorage: t, cookies: e } = {}) {
   const n = (c) => JSON.stringify(c).replace(/</g, "\\u003c"), s = t && t.length > 0 ? `var L=${n(t)};for(var i=0;i<L.length;i++){var v=localStorage.getItem(L[i]);if(v!==null)b[L[i]]=v;}` : "", i = e && e.length > 0 ? `var C=${n(e)};var s=document.cookie?document.cookie.split("; "):[];var m={};for(var j=0;j<s.length;j++){var p=s[j].indexOf("=");if(p>0){m[s[j].slice(0,p)]=decodeURIComponent(s[j].slice(p+1));}}for(var k=0;k<C.length;k++){if(C[k]in m)b[C[k]]=m[C[k]];}` : "";
   return `(function(){var b={};try{${s}}catch(e){}try{${i}}catch(e){}if(Object.keys(b).length){window.__VELO_BOOT__=Object.assign(window.__VELO_BOOT__||{},b);var d=document.documentElement;for(var q in b){d.setAttribute("data-"+String(q).replace(/[^a-zA-Z0-9-]/g,"-"),b[q]);}}})();`;
 }
-function y(t) {
+function I(t) {
   const e = S(t);
   return e ? /* @__PURE__ */ r("script", { dangerouslySetInnerHTML: { __html: e } }) : null;
 }
@@ -35,7 +36,7 @@ function m(t, e) {
     n = n.replace(`:${s}`, i);
   return n;
 }
-function I({ to: t, params: e, search: n, absolute: s, ...i }) {
+function V({ to: t, params: e, search: n, absolute: s, ...i }) {
   const c = typeof t != "string", l = L(), _ = c ? t.metadata?.fullPath ?? "/" : t, f = e ? m(_, e) : _, u = n ? `?${new URLSearchParams(n).toString()}` : "", v = `${f}${u}`;
   if (typeof window < "u" && C.value) {
     let a;
@@ -61,9 +62,9 @@ function I({ to: t, params: e, search: n, absolute: s, ...i }) {
   return /* @__PURE__ */ r($, { to: v, ...i });
 }
 export {
-  y as Boot,
-  I as Link,
-  w as Scripts,
+  I as Boot,
+  V as Link,
+  y as Scripts,
   S as bootScript,
   m as substituteParams
 };

package/dist/events.d.ts

@@ -284,6 +284,12 @@ interface StreamListener<TEvent> {
     (event: TEvent): void;
     close(): void;
 }
+/**
+ * The house's single SSE transport heartbeat, in milliseconds — the same
+ * default the live-loader channels use. Exported so the two surfaces never
+ * diverge in operational expectation.
+ */
+export declare const DEFAULT_HEARTBEAT_MS = 20000;
 export declare function flushPendingStreamRoutes(app: Hono): void;
 /** @internal Used by `@mauroandre/velojs/testing` to reset all streams. */
 export declare function getRegisteredStreams(): ReadonlySet<EventStream<unknown, unknown>>;

package/dist/events.js

@@ -232,6 +232,7 @@ function k(r, b, o, a = []) {
   a.length > 0 ? r.on(["GET"], [b], ...a, p) : r.on(["GET"], [b], p);
 }
 export {
+  D as DEFAULT_HEARTBEAT_MS,
   x as createEventStream,
   F as flushPendingStreamRoutes,
   O as getRegisteredStreams,

package/dist/hooks.d.ts

@@ -1,7 +1,28 @@
-import { type Signal } from "@preact/signals";
+import { type ReadonlySignal, type Signal } from "@preact/signals";
 import type { EventStream } from "./events.js";
 import type { SocketHandler, SocketStub } from "./sockets.js";
 import { __veloUpdatePending } from "./loader-store.js";
+import { type Freshness } from "./live-loader.js";
+export type { Freshness } from "./live-loader.js";
+/**
+ * What `Loader()`/`useLoader()` return. `freshness` is the page-level state of
+ * the live loader: `"live"` (connected), `"stale"` (connection closed,
+ * reconnecting or silent) and `"error"` (the last loader re-execution failed).
+ * On a page with no `channels` it exists and stays `"live"`. The framework
+ * exposes it as data for CSS to react to — it renders no JSX of its own.
+ *
+ * `freshnessByChannel` is the same state with per-channel granularity, keyed
+ * by the channel names the module declares — a page with two channels, one
+ * fallen and one following, shows both states at once. Empty record when the
+ * module declares no channels.
+ */
+export interface LoaderHandle<T> {
+    data: Signal<T | null>;
+    loading: Signal<boolean>;
+    refetch: () => void;
+    freshness: Signal<Freshness>;
+    freshnessByChannel: ReadonlySignal<Record<string, Freshness>>;
+}
 export { __veloUpdatePending };
 declare global {
     interface Window {
@@ -58,11 +79,7 @@ export declare function touch<T>(sig: Signal<T | null>): void;
  *
  * @param moduleId - Injetado automaticamente pelo veloPlugin
  */
-export declare function Loader<T>(moduleId?: string): {
-    data: Signal<T | null>;
-    loading: Signal<boolean>;
-    refetch: () => void;
-};
+export declare function Loader<T>(moduleId?: string): LoaderHandle<T>;
 /**
  * Hook para acessar dados do loader dentro de componentes
  * Suporta SSR hydration e navegação SPA (faz fetch se necessário)
@@ -82,21 +99,9 @@ export declare function Loader<T>(moduleId?: string): {
  * @param moduleId - Injetado automaticamente pelo veloPlugin
  * @param deps - Array de dependências (triggers re-fetch quando mudam)
  */
-export declare function useLoader<T>(): {
-    data: Signal<T | null>;
-    loading: Signal<boolean>;
-    refetch: () => void;
-};
-export declare function useLoader<T>(deps: any[]): {
-    data: Signal<T | null>;
-    loading: Signal<boolean>;
-    refetch: () => void;
-};
-export declare function useLoader<T>(moduleId: string, deps?: any[]): {
-    data: Signal<T | null>;
-    loading: Signal<boolean>;
-    refetch: () => void;
-};
+export declare function useLoader<T>(): LoaderHandle<T>;
+export declare function useLoader<T>(deps: any[]): LoaderHandle<T>;
+export declare function useLoader<T>(moduleId: string, deps?: any[]): LoaderHandle<T>;
 /**
  * Hook para navegação programática
  *