alabjs 0.1.0

package/dist/client/hooks.js

@@ -0,0 +1,220 @@
+import { use, useReducer, useTransition, useCallback, useState, useEffect, useRef } from "react";
+// Promise cache keyed by URL.
+// • On the SERVER: cleared before each page render (via _clearALabSSRCache) so
+//   re-renders after Suspense resolution return the same promise object, which
+//   is required for renderToPipeableStream to correctly resolve Suspense.
+// • On the CLIENT: intentionally persists for the session to avoid redundant
+//   network round-trips on subsequent re-renders.
+const _promiseCache = new Map();
+/** Clear the server-side promise cache between SSR renders. Called by alab's dev server. */
+export function _clearALabSSRCache() {
+    _promiseCache.clear();
+}
+/**
+ * Fetch server data with full type inference from a `ServerFn`.
+ *
+ * Use `import type` to reference the server function — type-only imports
+ * are erased at compile time and never cross the server/client boundary.
+ *
+ * @example
+ * ```tsx
+ * // app/posts/[id]/page.tsx
+ * import type { getPost } from "./page.server"; // ← import type, safe
+ * import { useServerData } from "alabjs/client";
+ *
+ * export default function PostPage({ params }: { params: { id: string } }) {
+ *   // Return type is inferred from getPost — no manual type annotation needed
+ *   const post = useServerData<typeof getPost>("getPost", params);
+ *   post.title; // ✅ typed
+ *   post.foo;   // ✅ TS error — doesn't exist on the return type
+ * }
+ * ```
+ */
+export function useServerData(fnName, params) {
+    const searchParams = params
+        ? new URLSearchParams(params).toString()
+        : "";
+    // When running in Node.js (SSR) fetch requires an absolute URL.
+    // Alab's dev/prod server sets ALAB_ORIGIN before rendering each page.
+    const origin = typeof window !== "undefined"
+        ? ""
+        : (process.env["ALAB_ORIGIN"] ?? "http://localhost:3000");
+    const url = `${origin}/_alabjs/data/${fnName}${searchParams ? `?${searchParams}` : ""}`;
+    let promise = _promiseCache.get(url);
+    if (!promise) {
+        promise = fetch(url).then((r) => {
+            if (!r.ok)
+                throw new Error(`[alabjs] server data fetch failed: ${r.status} ${r.statusText} — ${url}`);
+            return r.json();
+        });
+        _promiseCache.set(url, promise);
+    }
+    return use(promise);
+}
+function mutationReducer(_state, action) {
+    switch (action.type) {
+        case "start": return { status: "pending", data: undefined, error: undefined, zodError: undefined };
+        case "success": return { status: "success", data: action.data, error: undefined, zodError: undefined };
+        case "error": return { status: "error", data: undefined, error: action.error, zodError: undefined };
+        case "invalid": return { status: "invalid", data: undefined, error: undefined, zodError: action.zodError };
+        case "reset": return { status: "idle", data: undefined, error: undefined, zodError: undefined };
+    }
+}
+/**
+ * Trigger a server function mutation from the client, with full async state
+ * and optional optimistic updates.
+ *
+ * @example
+ * ```tsx
+ * import type { updateTodo } from "./page.server";
+ * import { useMutation } from "alabjs/client";
+ *
+ * // Basic
+ * const { mutate, data, isPending, error, zodError, reset } =
+ *   useMutation<typeof updateTodo>("updateTodo");
+ *
+ * // With optimistic update
+ * const { mutate, optimisticData } = useMutation<typeof updateTodo>("updateTodo", {
+ *   optimistic: (input) => ({ ...currentTodo, ...input }),
+ *   onError: (err, rollback) => rollback(),
+ * });
+ * ```
+ */
+export function useMutation(fnName, options) {
+    const [state, dispatch] = useReducer((mutationReducer), { status: "idle", data: undefined, error: undefined, zodError: undefined });
+    // Optimistic value lives in separate state so it can be cleared independently.
+    const [optimisticData, setOptimisticData] = useState(undefined);
+    const [isPending, startTransition] = useTransition();
+    const rollback = useCallback(() => {
+        setOptimisticData(undefined);
+        dispatch({ type: "reset" });
+    }, []);
+    const mutate = useCallback((input) => {
+        dispatch({ type: "start" });
+        if (options?.optimistic) {
+            setOptimisticData(options.optimistic(input));
+        }
+        startTransition(() => {
+            void (async () => {
+                try {
+                    const r = await fetch(`/_alabjs/fn/${fnName}`, {
+                        method: "POST",
+                        headers: { "content-type": "application/json" },
+                        body: JSON.stringify(input),
+                    });
+                    // Zod validation error from server
+                    if (r.status === 422) {
+                        const body = await r.json();
+                        setOptimisticData(undefined);
+                        dispatch({ type: "invalid", zodError: body["zodError"] });
+                        return;
+                    }
+                    if (!r.ok)
+                        throw new Error(`[alabjs] mutation failed: ${r.status} ${r.statusText}`);
+                    const data = await r.json();
+                    setOptimisticData(undefined);
+                    dispatch({ type: "success", data });
+                    options?.onSuccess?.(data);
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    setOptimisticData(undefined);
+                    dispatch({ type: "error", error });
+                    options?.onError?.(error, rollback);
+                }
+            })();
+        });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [fnName, rollback]);
+    const reset = useCallback(() => {
+        setOptimisticData(undefined);
+        dispatch({ type: "reset" });
+    }, []);
+    return {
+        mutate,
+        data: state.data,
+        /** Present when `optimistic` option is set and the request is in flight. */
+        optimisticData,
+        isPending: isPending || state.status === "pending",
+        error: state.error,
+        /** Zod validation errors returned by `defineServerFn` schema checks (HTTP 422). */
+        zodError: state.zodError,
+        isSuccess: state.status === "success",
+        isError: state.status === "error",
+        isInvalid: state.status === "invalid",
+        reset,
+    };
+}
+/**
+ * Subscribe to a server-sent event stream from a `defineSSEHandler` route.
+ *
+ * The EventSource is created when the component mounts and closed on unmount.
+ * Data is parsed as JSON automatically.
+ *
+ * @example
+ * ```tsx
+ * import { useSSE } from "alabjs/client";
+ *
+ * export default function PricesPage() {
+ *   const { data, readyState } = useSSE<{ ticker: string; price: number }>(
+ *     "/api/prices?ticker=BTC",
+ *     { event: "price" },
+ *   );
+ *
+ *   return <div>{readyState === "open" ? data?.price ?? "—" : "connecting…"}</div>;
+ * }
+ * ```
+ */
+export function useSSE(url, options = {}) {
+    const { event = "message", enabled = true, onOpen, onError } = options;
+    const [data, setData] = useState(undefined);
+    const [lastEventId, setLastEventId] = useState("");
+    const [readyState, setReadyState] = useState("connecting");
+    // Keep callbacks stable across renders without re-subscribing
+    const onOpenRef = useRef(onOpen);
+    const onErrorRef = useRef(onError);
+    onOpenRef.current = onOpen;
+    onErrorRef.current = onError;
+    const esRef = useRef(null);
+    const close = useCallback(() => {
+        esRef.current?.close();
+        esRef.current = null;
+        setReadyState("closed");
+    }, []);
+    useEffect(() => {
+        if (!enabled || typeof EventSource === "undefined")
+            return;
+        const es = new EventSource(url);
+        esRef.current = es;
+        setReadyState("connecting");
+        es.addEventListener("open", () => {
+            setReadyState("open");
+            onOpenRef.current?.();
+        });
+        es.addEventListener(event, (e) => {
+            setLastEventId(e.lastEventId ?? "");
+            try {
+                setData(e.data ? JSON.parse(e.data) : undefined);
+            }
+            catch {
+                // Server sent data that isn't valid JSON — log and discard rather than
+                // silently casting a raw string to T (which would cause runtime type errors).
+                console.warn("[alabjs] useSSE: received non-JSON data on", url, "— discarding:", e.data);
+            }
+        });
+        es.addEventListener("error", (e) => {
+            onErrorRef.current?.(e);
+            if (es.readyState === EventSource.CLOSED) {
+                setReadyState("closed");
+            }
+        });
+        return () => {
+            es.close();
+            esRef.current = null;
+        };
+        // Re-subscribe if url or event type changes
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [url, event, enabled]);
+    return { data, lastEventId, readyState, close };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/client/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/client/hooks.ts"],"names":[],"mappings":"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"}

package/dist/client/hooks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hooks.test.d.ts.map

package/dist/client/hooks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.test.d.ts","sourceRoot":"","sources":["../../src/client/hooks.test.ts"],"names":[],"mappings":""}

package/dist/client/hooks.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { _clearALabSSRCache } from "./hooks.js";
+// Note: useServerData, useMutation, and useSSE are React hooks that require a
+// component context and browser APIs (fetch, EventSource). Testing the full hooks
+// would require a React test renderer + fetch mocking. Here we test the exported
+// utility and the mutation state machine logic that can be exercised without React.
+describe("_clearALabSSRCache", () => {
+    it("is a function", () => {
+        expect(typeof _clearALabSSRCache).toBe("function");
+    });
+    it("can be called without error", () => {
+        // This clears the internal promise cache used during SSR.
+        // Should not throw even when cache is empty.
+        expect(() => _clearALabSSRCache()).not.toThrow();
+    });
+    it("can be called multiple times", () => {
+        expect(() => {
+            _clearALabSSRCache();
+            _clearALabSSRCache();
+            _clearALabSSRCache();
+        }).not.toThrow();
+    });
+});
+// ─── Mutation state machine (via module internals) ────────────────────────────
+// The mutationReducer is not exported, but we can test the state machine logic
+// by verifying the expected types and shape of the module exports.
+describe("hooks module exports", () => {
+    it("exports useServerData", async () => {
+        const mod = await import("./hooks.js");
+        expect(typeof mod.useServerData).toBe("function");
+    });
+    it("exports useMutation", async () => {
+        const mod = await import("./hooks.js");
+        expect(typeof mod.useMutation).toBe("function");
+    });
+    it("exports useSSE", async () => {
+        const mod = await import("./hooks.js");
+        expect(typeof mod.useSSE).toBe("function");
+    });
+    it("exports _clearALabSSRCache", async () => {
+        const mod = await import("./hooks.js");
+        expect(typeof mod._clearALabSSRCache).toBe("function");
+    });
+});
+//# sourceMappingURL=hooks.test.js.map

package/dist/client/hooks.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.test.js","sourceRoot":"","sources":["../../src/client/hooks.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,8EAA8E;AAC9E,kFAAkF;AAClF,iFAAiF;AACjF,oFAAoF;AAEpF,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,eAAe,EAAE,GAAG,EAAE;QACvB,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACrC,0DAA0D;QAC1D,6CAA6C;QAC7C,MAAM,CAAC,GAAG,EAAE,CAAC,kBAAkB,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,GAAG,EAAE;YACV,kBAAkB,EAAE,CAAC;YACrB,kBAAkB,EAAE,CAAC;YACrB,kBAAkB,EAAE,CAAC;QACvB,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,iFAAiF;AAEjF,+EAA+E;AAC/E,mEAAmE;AAEnE,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,uBAAuB,EAAE,KAAK,IAAI,EAAE;QACrC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QACvC,MAAM,CAAC,OAAO,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qBAAqB,EAAE,KAAK,IAAI,EAAE;QACnC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QACvC,MAAM,CAAC,OAAO,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QACvC,MAAM,CAAC,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4BAA4B,EAAE,KAAK,IAAI,EAAE;QAC1C,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QACvC,MAAM,CAAC,OAAO,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/client/index.d.ts

@@ -0,0 +1,6 @@
+export { useServerData, useMutation, useSSE, _clearALabSSRCache } from "./hooks.js";
+export type { UseSSEOptions, UseSSEResult, SSEReadyState } from "./hooks.js";
+export { useOfflineMutations } from "./offline.js";
+export type { UseOfflineMutationsResult, OfflineMutationResult } from "./offline.js";
+export { AlabProvider } from "./provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACpF,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,4 @@
+export { useServerData, useMutation, useSSE, _clearALabSSRCache } from "./hooks.js";
+export { useOfflineMutations } from "./offline.js";
+export { AlabProvider } from "./provider.js";
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEpF,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/client/offline.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Alab offline support — client-side registration + queue observation.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { useOfflineMutations } from "alabjs/client";
+ *
+ * export default function RootLayout({ children }) {
+ *   const { isOffline, queuedCount, replay } = useOfflineMutations();
+ *
+ *   return (
+ *     <>
+ *       {isOffline && (
+ *         <div className="offline-banner">
+ *           You're offline — {queuedCount} mutation(s) will sync when reconnected.
+ *           <button onClick={replay}>Retry now</button>
+ *         </div>
+ *       )}
+ *       {children}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export interface OfflineMutationResult {
+    replayed: {
+        fn: string;
+        ok: boolean;
+    }[];
+}
+export interface UseOfflineMutationsResult {
+    /** True when `navigator.onLine` is false. */
+    isOffline: boolean;
+    /** Number of mutations currently held in the offline queue. */
+    queuedCount: number;
+    /** Manually trigger a replay of the offline queue. */
+    replay: () => void;
+    /** History of replayed mutations since mount (cleared on replay start). */
+    replayed: OfflineMutationResult["replayed"];
+}
+/**
+ * Register the Alab offline service worker and observe queue state.
+ *
+ * On mount this registers `/_alabjs/offline-sw.js` (emitted by `alab build`).
+ * The hook listens for SW messages and browser online/offline events to keep
+ * state in sync.
+ *
+ * Safe to call in SSR — all browser APIs are guarded behind `typeof window`.
+ */
+export declare function useOfflineMutations(): UseOfflineMutationsResult;
+//# sourceMappingURL=offline.d.ts.map

package/dist/client/offline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline.d.ts","sourceRoot":"","sources":["../../src/client/offline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,yBAAyB;IACxC,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,2EAA2E;IAC3E,QAAQ,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;CAC7C;AAID;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,yBAAyB,CA2D/D"}

package/dist/client/offline.js

@@ -0,0 +1,90 @@
+/**
+ * Alab offline support — client-side registration + queue observation.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { useOfflineMutations } from "alabjs/client";
+ *
+ * export default function RootLayout({ children }) {
+ *   const { isOffline, queuedCount, replay } = useOfflineMutations();
+ *
+ *   return (
+ *     <>
+ *       {isOffline && (
+ *         <div className="offline-banner">
+ *           You're offline — {queuedCount} mutation(s) will sync when reconnected.
+ *           <button onClick={replay}>Retry now</button>
+ *         </div>
+ *       )}
+ *       {children}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+import { useState, useEffect, useCallback } from "react";
+const SW_PATH = "/_alabjs/offline-sw.js";
+/**
+ * Register the Alab offline service worker and observe queue state.
+ *
+ * On mount this registers `/_alabjs/offline-sw.js` (emitted by `alab build`).
+ * The hook listens for SW messages and browser online/offline events to keep
+ * state in sync.
+ *
+ * Safe to call in SSR — all browser APIs are guarded behind `typeof window`.
+ */
+export function useOfflineMutations() {
+    const [isOffline, setIsOffline] = useState(typeof navigator !== "undefined" ? !navigator.onLine : false);
+    const [queuedCount, setQueuedCount] = useState(0);
+    const [replayed, setReplayed] = useState([]);
+    // Stable SW controller ref
+    const [swReg, setSwReg] = useState(null);
+    useEffect(() => {
+        if (typeof window === "undefined" || !("serviceWorker" in navigator))
+            return;
+        // Register SW
+        navigator.serviceWorker.register(SW_PATH, { scope: "/" }).then((reg) => {
+            setSwReg(reg);
+        }).catch(() => { });
+        // Online / offline events
+        const handleOnline = () => setIsOffline(false);
+        const handleOffline = () => setIsOffline(true);
+        window.addEventListener("online", handleOnline);
+        window.addEventListener("offline", handleOffline);
+        // Messages from the SW
+        const handleMessage = (event) => {
+            const msg = event.data;
+            if (!msg)
+                return;
+            switch (msg["type"]) {
+                case "ALAB_QUEUED":
+                    setQueuedCount(msg["count"]);
+                    break;
+                case "ALAB_REPLAYED":
+                    setReplayed((prev) => [...prev, { fn: msg["fn"], ok: msg["ok"] }]);
+                    break;
+                case "ALAB_QUEUE_EMPTY":
+                    setQueuedCount(0);
+                    break;
+            }
+        };
+        navigator.serviceWorker.addEventListener("message", handleMessage);
+        return () => {
+            window.removeEventListener("online", handleOnline);
+            window.removeEventListener("offline", handleOffline);
+            navigator.serviceWorker.removeEventListener("message", handleMessage);
+        };
+    }, []);
+    const replay = useCallback(() => {
+        setReplayed([]);
+        if (swReg?.active) {
+            swReg.active.postMessage({ type: "ALAB_REPLAY" });
+        }
+        else {
+            navigator.serviceWorker.controller?.postMessage({ type: "ALAB_REPLAY" });
+        }
+    }, [swReg]);
+    return { isOffline, queuedCount, replay, replayed };
+}
+//# sourceMappingURL=offline.js.map

package/dist/client/offline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline.js","sourceRoot":"","sources":["../../src/client/offline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAiBzD,MAAM,OAAO,GAAG,wBAAwB,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CACxC,OAAO,SAAS,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAC7D,CAAC;IACF,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAClD,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAoC,EAAE,CAAC,CAAC;IAEhF,2BAA2B;IAC3B,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAmC,IAAI,CAAC,CAAC;IAE3E,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,eAAe,IAAI,SAAS,CAAC;YAAE,OAAO;QAE7E,cAAc;QACd,SAAS,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;YACrE,QAAQ,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAwD,CAAC,CAAC,CAAC;QAEzE,0BAA0B;QAC1B,MAAM,YAAY,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/C,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QAChD,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QAElD,uBAAuB;QACvB,MAAM,aAAa,GAAG,CAAC,KAAmB,EAAE,EAAE;YAC5C,MAAM,GAAG,GAAG,KAAK,CAAC,IAA+B,CAAC;YAClD,IAAI,CAAC,GAAG;gBAAE,OAAO;YACjB,QAAQ,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACpB,KAAK,aAAa;oBAChB,cAAc,CAAC,GAAG,CAAC,OAAO,CAAW,CAAC,CAAC;oBACvC,MAAM;gBACR,KAAK,eAAe;oBAClB,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,IAAI,CAAW,EAAE,EAAE,EAAE,GAAG,CAAC,IAAI,CAAY,EAAE,CAAC,CAAC,CAAC;oBACxF,MAAM;gBACR,KAAK,kBAAkB;oBACrB,cAAc,CAAC,CAAC,CAAC,CAAC;oBAClB,MAAM;YACV,CAAC;QACH,CAAC,CAAC;QACF,SAAS,CAAC,aAAa,CAAC,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QAEnE,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;YACnD,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;YACrD,SAAS,CAAC,aAAa,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QACxE,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE;QAC9B,WAAW,CAAC,EAAE,CAAC,CAAC;QAChB,IAAI,KAAK,EAAE,MAAM,EAAE,CAAC;YAClB,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,SAAS,CAAC,aAAa,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAEZ,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACtD,CAAC"}

package/dist/client/provider.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from "react";
+interface AlabProviderProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+/**
+ * Root provider for Alab apps.
+ * Wraps the app in a Suspense boundary for `useServerData` hooks.
+ */
+export declare function AlabProvider({ children, fallback }: AlabProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=provider.d.ts.map

package/dist/client/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/client/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEjD,UAAU,iBAAiB;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,QAAe,EAAE,EAAE,iBAAiB,2CAE5E"}

package/dist/client/provider.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense } from "react";
+/**
+ * Root provider for Alab apps.
+ * Wraps the app in a Suspense boundary for `useServerData` hooks.
+ */
+export function AlabProvider({ children, fallback = null }) {
+    return _jsx(Suspense, { fallback: fallback, children: children });
+}
+//# sourceMappingURL=provider.js.map

package/dist/client/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/client/provider.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,QAAQ,EAAkB,MAAM,OAAO,CAAC;AAOjD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,EAAqB;IAC3E,OAAO,KAAC,QAAQ,IAAC,QAAQ,EAAE,QAAQ,YAAG,QAAQ,GAAY,CAAC;AAC7D,CAAC"}

package/dist/commands/build.d.ts

@@ -0,0 +1,18 @@
+interface BuildOptions {
+    cwd: string;
+    /** Skip TypeScript type checking (--skip-typecheck flag). */
+    skipTypecheck?: boolean;
+    /**
+     * Build mode:
+     * - `"ssr"` (default) — full SSR + client bundle, requires a Node.js server.
+     * - `"spa"` — pure client-side bundle, deployable to any CDN. No Node.js needed.
+     *   Server functions become direct fetch calls to `/_alabjs/fn/*`; point these at
+     *   a separate API server or use Cloudflare Workers for the data layer.
+     */
+    mode?: "ssr" | "spa";
+    /** Open an interactive bundle size treemap after build (`--analyze`). */
+    analyze?: boolean;
+}
+export declare function build({ cwd, skipTypecheck, mode, analyze }: BuildOptions): Promise<void>;
+export {};
+//# sourceMappingURL=build.d.ts.map

package/dist/commands/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAKA,UAAU,YAAY;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACrB,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAsED,wBAAsB,KAAK,CAAC,EAAE,GAAG,EAAE,aAAqB,EAAE,IAAY,EAAE,OAAe,EAAE,EAAE,YAAY,iBAmFtG"}