@mauroandre/velojs 0.0.59 → 0.0.61

package/dist/config.d.ts

@@ -40,5 +40,13 @@ export interface VeloConfig {
      * @hono/vite-dev-server, não os substituem.
      */
     devServerExclude?: (string | RegExp)[];
+    /**
+     * Padrões de glob (`*`, `**`, `?`) que declaram módulos só de servidor ao
+     * diagnóstico de vazamento server->client, casados contra o caminho do
+     * arquivo do módulo relativo à raiz do projeto, com `/` como separador
+     * (ex.: `serverOnly: ["src/fsm/**", "server/**"]`). Serve só ao
+     * diagnóstico — nada é bloqueado ou alterado por causa da declaração.
+     */
+    serverOnly?: string[];
 }
 export declare function defineConfig(config: VeloConfig): VeloConfig;

package/dist/hooks.d.ts

@@ -4,6 +4,8 @@ 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";
+export { useLiveAction } from "./live-action.js";
+export type { LiveActionStub, LiveActionHandle, } from "./live-action.js";
 /**
  * What `Loader()`/`useLoader()` return. `freshness` is the page-level state of
  * the live loader: `"live"` (connected), `"stale"` (connection closed,

package/dist/hooks.js

@@ -4,14 +4,15 @@ import { useLocation as b, useParams as $, useSearch as B } from "wouter-preact"
 import { refetchModule as C, loaderLoading as D, loaderEntry as N } from "./loader-store.js";
 import { __veloUpdatePending as X } from "./loader-store.js";
 import { loaderFreshness as w, moduleChannelFreshness as O } from "./live-loader.js";
+import { useLiveAction as Z } from "./live-action.js";
 function j() {
   return typeof window > "u" ? {} : window.__VELO_BOOT__ ?? {};
 }
-function F(e) {
+function x(e) {
   const t = e.value;
   t === null || typeof t != "object" || (e.value = Array.isArray(t) ? [...t] : { ...t });
 }
-function J(e) {
+function F(e) {
   return typeof window > "u" ? {
     data: {
       get value() {
@@ -38,7 +39,7 @@ function J(e) {
     freshnessByChannel: S({})
   };
 }
-function M(e, t) {
+function J(e, t) {
   let n, r;
   if (Array.isArray(e) ? r = e : (n = e, r = t), typeof window > "u") {
     let a = null;
@@ -64,16 +65,16 @@ function M(e, t) {
       freshness: w(),
       freshnessByChannel: s({})
     };
-  const l = N(n), o = D(n), u = () => C(n), h = w(), y = E(!0);
+  const c = N(n), o = D(n), u = () => C(n), h = w(), y = E(!0);
   return m(() => {
-    y.current && (y.current = !1, l.value !== null) || u();
-  }, r ?? []), { data: l, loading: o, refetch: u, freshness: h, freshnessByChannel: O(n) };
+    y.current && (y.current = !1, c.value !== null) || u();
+  }, r ?? []), { data: c, loading: o, refetch: u, freshness: h, freshnessByChannel: O(n) };
 }
-function q() {
+function M() {
   const [, e] = b();
   return e;
 }
-function x() {
+function q() {
   return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__params ?? {} : $();
 }
 function G() {
@@ -88,14 +89,14 @@ function Q() {
   return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__pathname ?? "/" : (b(), window.location.pathname);
 }
 function V(e, t = {}) {
-  const n = s(null), r = s(null), l = s(!1), o = s(null), { channel: u, enabled: h = !0 } = t;
+  const n = s(null), r = s(null), c = s(!1), o = s(null), { channel: u, enabled: h = !0 } = t;
   return m(() => {
     if (typeof window > "u" || !h) return;
     if (!e.__path) {
       console.warn("[velojs] useEventStream: stream has no __path");
       return;
     }
-    l.value = !1, o.value = null;
+    c.value = !1, o.value = null;
     const y = u ? `${e.__path}?channel=${encodeURIComponent(u)}` : e.__path, a = new EventSource(y);
     return a.addEventListener("snapshot", (g) => {
       try {
@@ -111,47 +112,47 @@ function V(e, t = {}) {
       }
     }), a.addEventListener("heartbeat", () => {
     }), a.addEventListener("close", () => {
-      l.value = !0, a.close();
+      c.value = !0, a.close();
     }), a.addEventListener("error", () => {
-      a.readyState === EventSource.CLOSED && (l.value = !0);
+      a.readyState === EventSource.CLOSED && (c.value = !0);
     }), () => {
       a.close();
     };
-  }, [e, u, h]), { data: n, snapshot: r, closed: l, error: o };
+  }, [e, u, h]), { data: n, snapshot: r, closed: c, error: o };
 }
 function z(e, t = {}) {
-  const n = s("connecting"), r = s(null), l = s(null), o = E(null), u = E([]), { channel: h, onMessage: y, onOpen: a, onClose: g, onError: v, enabled: L = !0 } = t;
+  const n = s("connecting"), r = s(null), c = s(null), o = E(null), u = E([]), { channel: h, onMessage: y, onOpen: a, onClose: g, onError: v, enabled: L = !0 } = t;
   return m(() => {
     if (typeof window > "u" || !L) return;
     if (!e.__path) {
       console.warn("[velojs] useSocket: stub has no __path");
       return;
     }
-    n.value = "connecting", l.value = null;
+    n.value = "connecting", c.value = null;
     const d = `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.host}`, i = h ? `${d}${e.__path}?channel=${encodeURIComponent(h)}` : `${d}${e.__path}`, f = new WebSocket(i);
     return f.binaryType = "arraybuffer", o.current = f, f.addEventListener("open", () => {
       n.value = "open";
-      const c = u.current;
+      const l = u.current;
       u.current = [];
-      for (const _ of c)
+      for (const _ of l)
         try {
           f.send(_);
         } catch {
         }
       a?.();
-    }), f.addEventListener("message", (c) => {
+    }), f.addEventListener("message", (l) => {
       let _;
-      if (typeof c.data == "string")
-        _ = c.data;
-      else if (c.data instanceof ArrayBuffer)
-        _ = new Uint8Array(c.data);
+      if (typeof l.data == "string")
+        _ = l.data;
+      else if (l.data instanceof ArrayBuffer)
+        _ = new Uint8Array(l.data);
       else
         return;
       r.value = _, y?.(_);
-    }), f.addEventListener("close", (c) => {
-      n.value = "closed", o.current = null, g?.(c);
-    }), f.addEventListener("error", (c) => {
-      l.value = c, v?.(c);
+    }), f.addEventListener("close", (l) => {
+      n.value = "closed", o.current = null, g?.(l);
+    }), f.addEventListener("error", (l) => {
+      c.value = l, v?.(l);
     }), () => {
       o.current = null;
       try {
@@ -176,17 +177,18 @@ function z(e, t = {}) {
         i.close(p, d);
       } catch {
       }
-  }, status: n, lastMessage: r, error: l };
+  }, status: n, lastMessage: r, error: c };
 }
 export {
-  J as Loader,
+  F as Loader,
   X as __veloUpdatePending,
-  F as touch,
+  x as touch,
   j as useBoot,
   V as useEventStream,
-  M as useLoader,
-  q as useNavigate,
-  x as useParams,
+  Z as useLiveAction,
+  J as useLoader,
+  M as useNavigate,
+  q as useParams,
   Q as usePathname,
   G as useQuery,
   z as useSocket

package/dist/leak-diagnostic.d.ts

@@ -0,0 +1,77 @@
+/** One import in the chain: `from` imports `to` at `line` (`null` = generated). */
+export interface LeakLink {
+    from: string;
+    line: number | null;
+    to: string;
+}
+export interface LeakItem {
+    /** Display path of the leaked server module. */
+    target: string;
+    /** Why it qualifies as a server module (English). */
+    qualifiers: string[];
+    /** Full import chain, client entry -> target, one link per import. */
+    chain: LeakLink[];
+    /** Index in `chain` of the entry-point link — the cut. */
+    entryIndex: number;
+}
+export interface LeakReport {
+    leaks: LeakItem[];
+    /** True when the enumeration stopped at its safety budget. */
+    truncated: boolean;
+    /** Stable fingerprint of what ships to the client (dev re-emit trigger). */
+    signature: string;
+    /** How many modules the walk visited (informational). */
+    moduleCount: number;
+}
+export type ResolveFn = (spec: string, importer: string) => string | null;
+export interface ModuleInfo {
+    file: string;
+    display: string;
+    edges: RawEdge[];
+    builtins: string[];
+    patterns: string[];
+}
+export interface CachedModule {
+    mtimeMs: number;
+    info: ModuleInfo;
+}
+export interface LeakAnalyzerOptions {
+    /** Project root — display paths and `serverOnly` matching are relative to it. */
+    rootDir: string;
+    /** Absolute app directory (velo:transform's scope). */
+    appDir: string;
+    /** Routes file name inside appDir (default "routes.tsx"). */
+    routesFile?: string | undefined;
+    /** The client entry's import specifiers (the virtual entry's imports). */
+    entrySpecs: string[];
+    /** Glob patterns declaring server-only modules (VeloConfig.serverOnly). */
+    serverOnly?: readonly string[] | undefined;
+    /** Import resolver: (specifier, importer file) -> absolute file or null. */
+    resolve?: ResolveFn | undefined;
+    /** Optional parse cache shared across runs (dev). */
+    cache?: Map<string, CachedModule> | undefined;
+}
+interface RawEdge {
+    spec: string;
+    line: number;
+    kind: "static" | "dynamic";
+    locals: string[];
+}
+/** True when the specifier names a Node builtin (with or without the `node:` prefix). */
+export declare function isBuiltinSpec(spec: string): boolean;
+/**
+ * Compiles a glob (`*` = within a segment, `**` across segments, `?` = one
+ * char) into a full-match regex over the module path relative to the project
+ * root, always with `/` separators.
+ */
+export declare function globToRegex(glob: string): RegExp;
+/**
+ * Resolution mirroring what the client build follows: relative specifiers with
+ * TS extension completion, bare specifiers through `node_modules` with the
+ * package's browser/import `exports` conditions. Returns null for anything
+ * that does not resolve to a file (external, virtual or unresolvable).
+ */
+export declare function defaultResolve(spec: string, importer: string): string | null;
+export declare function analyzeClientLeaks(options: LeakAnalyzerOptions): LeakReport;
+export declare function formatLeakReport(report: LeakReport): string;
+export {};

package/dist/leak-diagnostic.js

@@ -0,0 +1,14 @@
+import "node:fs";
+import "node:path";
+import "node:module";
+import "@babel/parser";
+import "@babel/traverse";
+import "@babel/types";
+import { a as s, d as l, f, g, i as n } from "./vite.js";
+export {
+  s as analyzeClientLeaks,
+  l as defaultResolve,
+  f as formatLeakReport,
+  g as globToRegex,
+  n as isBuiltinSpec
+};

package/dist/live-action.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Live actions — client runtime.
+ *
+ * A tab is not a route: it is client state, and its content loads at open time
+ * from an action with its own arguments (the resource id, the file path). When
+ * that content is a **value that tracks server state over time**, the action
+ * declares interest in living (`liveActions` in the route module) and the tab
+ * subscribes:
+ *
+ * ```tsx
+ * const { data, loading, freshness } = useLiveAction(action_abrirFicha, { id });
+ * ```
+ *
+ * The hook receives the action itself — its client stub, which the Vite plugin
+ * marks with the subscription address (`__path`, the socket-stub ruler) — and
+ * the args. It opens ONE SSE connection per subscription at
+ * `GET /_live/{moduleId}/{actionName}?_args=<json>`; the connect snapshot (the
+ * action executed once with the declared args) is the whole loading gesture —
+ * there is no initial POST. Every `emit()` in any of the action's declared
+ * channels re-executes the action server-side with the same args and pushes the
+ * fresh value, which **replaces** `data` whole (no merge — the updated payload
+ * has the same shape as the original answer).
+ *
+ * The subscription's life is the mount: the tab component unmounts (tab closed,
+ * page left) and the connection closes — nothing arrives afterwards and the
+ * server holds nothing for the gone. It remounts (tab reopened, refresh
+ * restored the tabs) and the subscription is born again with a snapshot of the
+ * current state: reopening is indistinguishable from never having closed. The
+ * args are the identity — changing them reconnects (new subscription, new
+ * snapshot), the twin of the loader connection keyed by its route params.
+ *
+ * `freshness` is the subscription's own `"live"` / `"stale"` / `"error"` signal
+ * — the same three states and the same 60s silence detector as the live loader
+ * — and it never touches the page aggregate: a stale tab does not stale the
+ * page, and the other way around.
+ *
+ * On the server (SSR) the hook does not connect: the tab is client state the
+ * server does not know, so it returns `data` null with `loading` true. In a
+ * static build the load really failed (there is no server to run the action):
+ * no connection is opened and the handle is `data` undefined, `loading` false,
+ * `freshness` `"error"` — the deliberate contrast with a channel, which stays
+ * `"live"` because there is nothing to sync.
+ */
+import { type Signal } from "@preact/signals";
+import { type Freshness } from "./live-loader.js";
+/**
+ * The client stub of a live action — the form the Vite plugin generates for an
+ * action the module declares in `liveActions`. The call signature is the
+ * action's own (typed from its `ActionArgs` and return); the live marks are
+ * what `useLiveAction` reads to find the subscription address.
+ */
+export interface LiveActionStub<TArgs extends Record<string, unknown>, TData> {
+    (args: {
+        body: TArgs;
+    }): Promise<TData>;
+    /** Set by the Vite plugin on every stub the module declares live. */
+    __isVeloLiveAction?: boolean;
+    /** `/_live/{moduleId}/{actionName}` — the subscription address. */
+    __path?: string;
+}
+/** What `useLiveAction` returns. */
+export interface LiveActionHandle<T> {
+    /** The action's return, replaced whole by every snapshot. */
+    data: Signal<T | null | undefined>;
+    /** True until the first snapshot or error of the current subscription. */
+    loading: Signal<boolean>;
+    /** The subscription's own freshness — never the page aggregate's. */
+    freshness: Signal<Freshness>;
+}
+/**
+ * Subscribes to a live action and reads its value as it tracks server state.
+ *
+ * The connection is keyed by the args: passing different args is a different
+ * subscription (the old one closes, the new one opens with a fresh snapshot).
+ * The life is the mount — unmount closes, remount reopens with the current
+ * state. See the module docs for the full contract.
+ *
+ * ```tsx
+ * export const Component = () => {
+ *     const { data, loading, freshness } = useLiveAction(action_abrirFicha, { id: 7 });
+ *     if (loading.value) return <div class="tab-loading" />;
+ *     return <article class={freshness.value}>{data.value?.nome}</article>;
+ * };
+ * ```
+ */
+export declare function useLiveAction<TArgs extends Record<string, unknown>, TData>(action: LiveActionStub<TArgs, TData>, args: TArgs): LiveActionHandle<TData>;

package/dist/live-action.js

@@ -0,0 +1,52 @@
+import { useSignal as s } from "@preact/signals";
+import { useEffect as d } from "preact/hooks";
+import { CHANNEL_SILENCE_MS as _ } from "./live-loader.js";
+const p = "snapshot";
+function S(n, v) {
+  const l = s(null), t = s(!0), e = s("live"), i = JSON.stringify(v ?? {});
+  return d(() => {
+    if (typeof window > "u") return;
+    if (typeof __VELO_STATIC__ < "u" && __VELO_STATIC__) {
+      t.value = !1, e.value = "error", l.value = void 0;
+      return;
+    }
+    if (!n.__isVeloLiveAction || !n.__path) {
+      console.warn(
+        '[velojs] useLiveAction: this action has no live declaration — add it to the module\'s `liveActions` export (e.g. `export const liveActions = { abrirFicha: ["fichaProjeto"] };`).'
+      ), t.value = !1, e.value = "error";
+      return;
+    }
+    t.value = !0;
+    const f = `${n.__path}?_args=${encodeURIComponent(i)}`, o = new EventSource(f);
+    let r = null;
+    const u = () => {
+      r !== null && clearTimeout(r), r = setTimeout(() => {
+        r = null, e.value = "stale";
+      }, _);
+    };
+    return u(), o.addEventListener(p, (a) => {
+      try {
+        l.value = JSON.parse(a.data), t.value = !1, e.value = "live", u();
+      } catch {
+      }
+    }), o.addEventListener("error", (a) => {
+      const c = a.data;
+      if (typeof c == "string" && c.length > 0) {
+        t.value = !1, e.value = "error";
+        return;
+      }
+      e.value = "stale";
+    }), o.addEventListener("close", () => {
+      e.value = "stale";
+    }), () => {
+      r !== null && clearTimeout(r);
+      try {
+        o.close();
+      } catch {
+      }
+    };
+  }, [n.__path, i]), { data: l, loading: t, freshness: e };
+}
+export {
+  S as useLiveAction
+};

package/dist/server.d.ts

@@ -2,7 +2,7 @@ import { Hono } from "hono";
 import type { AppRoutes } from "./types.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 export { emit, inspectChannels, registerChannels } from "./channels.js";
-export type { ChannelDefinition, ChannelMap, ChannelScopeContext, ChannelGroupOpenContext, ChannelGroupCloseContext, ChannelScopeResult, ChannelRegistryOptions, ChannelEmitModule, ChannelEmitKind, ChannelSlice, ChannelInspectGroup, ChannelInspectChannel, ChannelInspectWindow, ChannelInspectReport, } from "./channels.js";
+export type { ChannelDefinition, ChannelMap, ChannelScopeContext, ChannelGroupOpenContext, ChannelGroupCloseContext, ChannelScopeResult, ChannelRegistryOptions, ChannelEmitModule, ChannelEmitKind, ChannelSlice, ChannelInspectGroup, ChannelInspectChannel, ChannelInspectWindow, ChannelInspectLiveAction, ChannelInspectReport, } from "./channels.js";
 export declare const serverDataStorage: AsyncLocalStorage<Record<string, unknown>>;
 type ServerCallback = (server: import("http").Server) => void;
 export declare function onServer(fn: ServerCallback): void;