@cmj/juice 0.0.1

package/dist/runtime/router.js

@@ -0,0 +1,367 @@
+// ── juice/runtime router ───────────────────────────────────────────
+// The sole public entry point. Creates a WinterCG-compatible fetch
+// handler from a flight manifest.
+//
+// WinterCG only. No Node.js APIs. No bundler awareness.
+// ────────────────────────────────────────────────────────────────────
+import { ManifestValidationError, HookExecutionError } from './errors.js';
+import { _compileRoutes, _matchRoute } from './matcher.js';
+import { _renderPipeline } from './render.js';
+import { _serverActionPipeline } from './actions.js';
+import { _generateDevErrorOverlay } from './dev.js';
+// ── Manifest Normalization ────────────────────────────────────────
+/**
+ * Normalizes a compiler-emitted manifest into the runtime’s expected shape.
+ *
+ * The Juice compiler emits `{ $schema, version, clientModules, ssrModules, serverActions }`
+ * where serverActions use `module` and `name` fields. The runtime expects
+ * `{ routes, clientModules, serverActions }` with `moduleId` and `exportName` fields.
+ *
+ * This function bridges the gap so `createRouter()` accepts both shapes.
+ *
+ * @internal
+ */
+function _normalizeManifest(raw) {
+    // Non-objects pass through to _validateManifest which will reject them
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return raw;
+    }
+    const obj = raw;
+    // If the manifest already has the runtime shape, return as-is
+    // (but still normalize serverActions field names if needed)
+    if (obj.routes && typeof obj.routes === 'object') {
+        const sa = obj.serverActions;
+        if (sa && typeof sa === 'object') {
+            const normalized = _normalizeServerActions(sa);
+            if (normalized !== sa) {
+                return { ...obj, serverActions: normalized };
+            }
+        }
+        return obj;
+    }
+    // Detect compiler-shaped manifest by the presence of $schema or version.
+    // Only compiler output has these markers. Without them, a random object
+    // missing "routes" should still fail validation — not be silently patched.
+    const isCompilerManifest = '$schema' in obj || 'version' in obj;
+    if (!isCompilerManifest) {
+        return obj; // let _validateManifest catch the missing "routes" field
+    }
+    // Compiler-shaped manifest: provide default empty routes and normalize
+    const result = {
+        routes: obj.routes ?? {},
+        clientModules: obj.clientModules ?? {},
+        serverActions: {},
+    };
+    const sa = obj.serverActions;
+    if (sa && typeof sa === 'object') {
+        result.serverActions = _normalizeServerActions(sa);
+    }
+    return result;
+}
+/**
+ * Normalizes server action entries from the compiler’s format
+ * (`{ module, name }`) to the runtime’s format (`{ moduleId, exportName }`).
+ *
+ * If an entry already has `moduleId`, it’s left as-is.
+ *
+ * @internal
+ */
+function _normalizeServerActions(actions) {
+    const result = {};
+    let changed = false;
+    for (const [id, entry] of Object.entries(actions)) {
+        // Compiler uses `module` + `name`; runtime uses `moduleId` + `exportName`
+        if (entry.module && !entry.moduleId) {
+            result[id] = {
+                moduleId: entry.module,
+                exportName: entry.name ?? 'default',
+            };
+            changed = true;
+        }
+        else {
+            result[id] = entry;
+        }
+    }
+    return changed ? result : actions;
+}
+// ── Manifest Validation ────────────────────────────────────────────
+/**
+ * Validates the flight manifest at router initialization time.
+ * Fails fast with actionable error messages.
+ *
+ * @internal
+ */
+function _validateManifest(manifest) {
+    if (manifest === null) {
+        throw new ManifestValidationError('expected an object but received null');
+    }
+    if (manifest === undefined) {
+        throw new ManifestValidationError('expected an object but received undefined. ' +
+            'Did you forget to pass the manifest to createRouter()?');
+    }
+    if (typeof manifest !== 'object' || Array.isArray(manifest)) {
+        throw new ManifestValidationError('expected an object but received ' +
+            (Array.isArray(manifest) ? 'an array' : typeof manifest));
+    }
+    const m = manifest;
+    if (!m.routes || typeof m.routes !== 'object') {
+        throw new ManifestValidationError('missing "routes" field. The manifest must have a "routes" object ' +
+            'mapping URL patterns to route entries');
+    }
+    if (!m.clientModules || typeof m.clientModules !== 'object') {
+        throw new ManifestValidationError('missing "clientModules" field. The manifest must have a "clientModules" ' +
+            'object mapping client component IDs to chunk info');
+    }
+    if (!m.serverActions || typeof m.serverActions !== 'object') {
+        throw new ManifestValidationError('missing "serverActions" field. The manifest must have a "serverActions" ' +
+            'object mapping action IDs to handler modules');
+    }
+}
+// ── Default Hooks ──────────────────────────────────────────────────
+/** @internal */
+function _defaultOnNotFound(req) {
+    const url = new URL(req.url);
+    return new Response(`Not Found: ${url.pathname}`, { status: 404 });
+}
+/** @internal */
+function _defaultOnError(error, _req) {
+    console.error('[juice/runtime] Unhandled error:', error);
+    return new Response('Internal Server Error', { status: 500 });
+}
+// ── Hook Safety Wrappers ───────────────────────────────────────────
+/**
+ * Safely executes a user-provided hook. If the hook throws,
+ * catches the error and falls back gracefully instead of
+ * crashing the server.
+ *
+ * @internal
+ */
+async function _safeCallHook(hookName, hookFn, fallback) {
+    try {
+        return await hookFn();
+    }
+    catch (cause) {
+        // If the hook threw a Response, honor it — it's intentional.
+        if (cause instanceof Response) {
+            return cause;
+        }
+        console.error(new HookExecutionError(hookName, cause));
+        return fallback;
+    }
+}
+/**
+ * Creates a promise that rejects after `ms` milliseconds with a
+ * 504 Gateway Timeout response. Used for per-request timeout.
+ *
+ * @internal
+ */
+function _createTimeout(ms) {
+    let timeoutId;
+    const promise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new Response('Gateway Timeout', {
+                status: 504,
+                headers: { 'Content-Type': 'text/plain' },
+            }));
+        }, ms);
+    });
+    return {
+        promise,
+        clear: () => clearTimeout(timeoutId),
+    };
+}
+// ── Public API ─────────────────────────────────────────────────────
+/**
+ * Creates a WinterCG-compatible fetch handler for the Juice edge runtime.
+ *
+ * The returned function has the signature `(req: Request) => Promise<Response>`,
+ * which is the universal handler interface for Cloudflare Workers, Bun,
+ * Deno, and any WinterCG-compliant runtime.
+ *
+ * **Architecture:**
+ * - `GET` requests are routed to React 19's `renderToReadableStream`.
+ * - `POST` requests execute server actions resolved from the manifest.
+ * - All other methods return `405 Method Not Allowed`.
+ *
+ * **Thrown Response pattern:**
+ * User components can `throw new Response(body, { status })` to signal
+ * non-200 outcomes (404, redirect, etc.). The router catches these,
+ * aborts the React stream, and returns the thrown `Response` directly.
+ *
+ * **Hardened hooks:**
+ * User-provided hooks (`onBeforeRequest`, `onNotFound`, `onError`) are
+ * wrapped in try/catch. If a hook throws, the error is logged and a
+ * safe fallback response is returned — the server never crashes.
+ *
+ * @param manifest - The flight manifest generated by the Juice compiler.
+ *   This is the sole bridge between the build step and the runtime.
+ * @param options  - Optional runtime configuration (hooks, base path, timeout).
+ * @returns A `(req: Request) => Promise<Response>` fetch handler.
+ *
+ * @throws {ManifestValidationError} If the manifest is structurally invalid.
+ *
+ * @example
+ * ```ts
+ * // ── Cloudflare Workers ──────────────────────────────
+ * import manifest from './flight-manifest.json';
+ * import { createRouter } from '@cmj/juice/runtime';
+ *
+ * export default { fetch: createRouter(manifest) };
+ * ```
+ *
+ * @example
+ * ```ts
+ * // ── Bun ─────────────────────────────────────────────
+ * import manifest from './flight-manifest.json';
+ * import { createRouter } from '@cmj/juice/runtime';
+ *
+ * Bun.serve({ fetch: createRouter(manifest) });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // ── With options ────────────────────────────────────
+ * import manifest from './flight-manifest.json';
+ * import { createRouter } from '@cmj/juice/runtime';
+ *
+ * export default {
+ *   fetch: createRouter(manifest, {
+ *     basePath: '/app',
+ *     requestTimeout: 10_000, // 10 seconds
+ *     onBeforeRequest: (req) => {
+ *       if (!getSession(req)) {
+ *         return Response.redirect('/login', 302);
+ *       }
+ *     },
+ *     onNotFound: () => new Response('Custom 404', { status: 404 }),
+ *     onError: (err) => {
+ *       reportToSentry(err);
+ *       return new Response('Oops', { status: 500 });
+ *     },
+ *   }),
+ * };
+ * ```
+ */
+export function createRouter(manifest, options) {
+    // ── Normalize compiler-shaped manifest to runtime shape ───────
+    const normalized = _normalizeManifest(manifest);
+    // ── Fail fast: validate at initialization, not per-request ───
+    _validateManifest(normalized);
+    const resolvedManifest = normalized;
+    // ── Resolve options with defaults ────────────────────────────
+    // Read _meta from the manifest (injected by the Vite plugin) as
+    // defaults. User-provided options always take precedence.
+    const meta = resolvedManifest._meta;
+    const basePath = options?.basePath ?? '/';
+    const requestTimeout = options?.requestTimeout ?? 0;
+    const root = options?.root ?? meta?.root;
+    const isDev = (options?.mode ?? meta?.mode) === 'development';
+    const hmrUrl = options?.hmrUrl ?? meta?.hmrUrl;
+    const assetPrefix = options?.assetPrefix ?? meta?.assetPrefix ?? '/';
+    const clientEntry = options?.clientEntry ?? meta?.clientEntry;
+    const resolvedOptions = {
+        ...options,
+        root,
+        isDev,
+        hmrUrl,
+        assetPrefix,
+        clientEntry,
+        onNotFound: options?.onNotFound ?? _defaultOnNotFound,
+        onError: options?.onError ?? _defaultOnError,
+    };
+    if (isDev) {
+        console.log('[juice/dev] \u{1F9C3} Dev mode active \u2014 error overlays, module cache-busting, HMR enabled');
+    }
+    // ── Compile routes once ──────────────────────────────────────
+    const compiledRoutes = _compileRoutes(resolvedManifest.routes, basePath);
+    // ── Return the fetch handler ─────────────────────────────────
+    return async function handleRequest(req) {
+        // ── Request timeout race ─────────────────────────────────────
+        if (requestTimeout > 0) {
+            const timeout = _createTimeout(requestTimeout);
+            try {
+                return await Promise.race([
+                    _handleRequestInner(req, compiledRoutes, resolvedManifest, resolvedOptions),
+                    timeout.promise,
+                ]);
+            }
+            catch (thrown) {
+                // Timeout rejects with a Response object
+                if (thrown instanceof Response) {
+                    return thrown;
+                }
+                return resolvedOptions.onError(thrown, req);
+            }
+            finally {
+                timeout.clear();
+            }
+        }
+        return _handleRequestInner(req, compiledRoutes, resolvedManifest, resolvedOptions);
+    };
+}
+/**
+ * Inner request handler — separated so timeout can race against it.
+ * @internal
+ */
+async function _handleRequestInner(req, compiledRoutes, manifest, resolvedOptions) {
+    try {
+        // ── onBeforeRequest hook (guarded) ───────────────────────────
+        if (resolvedOptions.onBeforeRequest) {
+            const hookFn = resolvedOptions.onBeforeRequest;
+            const earlyResponse = await _safeCallHook('onBeforeRequest', () => hookFn(req), undefined);
+            if (earlyResponse instanceof Response) {
+                return earlyResponse;
+            }
+        }
+        // ── Method dispatch ────────────────────────────────────────
+        const method = req.method.toUpperCase();
+        switch (method) {
+            case 'GET':
+            case 'HEAD': {
+                // ── Route matching ─────────────────────────────────────
+                const match = _matchRoute(req.url, compiledRoutes);
+                if (!match) {
+                    return _safeCallHook('onNotFound', () => resolvedOptions.onNotFound(req), new Response('Not Found', { status: 404 }));
+                }
+                // ── Render pipeline ────────────────────────────────────
+                const response = await _renderPipeline(req, match, manifest, resolvedOptions);
+                // HEAD requests: return headers only, strip body
+                if (method === 'HEAD') {
+                    return new Response(null, {
+                        status: response.status,
+                        statusText: response.statusText,
+                        headers: response.headers,
+                    });
+                }
+                return response;
+            }
+            case 'POST': {
+                return _serverActionPipeline(req, manifest, resolvedOptions);
+            }
+            default: {
+                return new Response('Method Not Allowed', {
+                    status: 405,
+                    headers: { Allow: 'GET, HEAD, POST' },
+                });
+            }
+        }
+    }
+    catch (thrown) {
+        // ── Top-level safety net ─────────────────────────────────
+        // Thrown Responses that somehow escaped the pipelines.
+        if (thrown instanceof Response) {
+            return thrown;
+        }
+        // ── Dev mode: rich error overlay ─────────────────────────
+        if (resolvedOptions.isDev) {
+            console.error('[juice/dev]', thrown);
+            return new Response(_generateDevErrorOverlay(thrown, req), {
+                status: 500,
+                headers: { 'Content-Type': 'text/html; charset=utf-8' },
+            });
+        }
+        // Guard the onError hook itself — if it throws, don't crash.
+        return _safeCallHook('onError', () => resolvedOptions.onError(thrown, req), new Response('Internal Server Error', { status: 500 }));
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/runtime/router.js.map

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

package/dist/runtime/types.d.ts

@@ -0,0 +1,245 @@
+/**
+ * A single route entry mapping a URL pattern to its server component module.
+ */
+export interface RouteEntry {
+    /** The module ID for dynamic import (relative to runtime root). */
+    readonly moduleId: string;
+    /**
+     * Named export to use as the page component.
+     * @default 'default'
+     */
+    readonly exportName?: string;
+}
+/**
+ * Resolution info for a client component chunk, used by React Flight
+ * to load client components on the browser.
+ */
+export interface ClientModuleRef {
+    /** Chunk filenames for the client bundle. */
+    readonly chunks: readonly string[];
+    /** The named export within the chunk. */
+    readonly name: string;
+}
+/**
+ * Resolution info for a server action, mapping an action ID to its
+ * handler module and export.
+ */
+export interface ServerActionRef {
+    /** The module ID containing the action handler. */
+    readonly moduleId: string;
+    /** The named export for the action function. */
+    readonly exportName: string;
+}
+/**
+ * The manifest generated by the Juice Vite plugin at build time.
+ * Maps server component paths to their client-side chunk references,
+ * route patterns to page modules, and action IDs to handlers.
+ *
+ * This is the **sole bridge** between the compiler and the runtime.
+ * The runtime never reads the filesystem — it receives this object
+ * from the caller.
+ *
+ * @example
+ * ```ts
+ * import manifest from './flight-manifest.json';
+ * import { createRouter } from '@cmj/juice/runtime';
+ *
+ * export default { fetch: createRouter(manifest) };
+ * ```
+ */
+export interface FlightManifest {
+    /** Map of URL pathname patterns to their server component modules. */
+    readonly routes: Readonly<Record<string, RouteEntry>>;
+    /** Map of client component IDs to their chunk resolution info. */
+    readonly clientModules: Readonly<Record<string, ClientModuleRef>>;
+    /** Map of server action IDs to their handler modules. */
+    readonly serverActions: Readonly<Record<string, ServerActionRef>>;
+    /**
+     * Build-time metadata injected by the Vite plugin.
+     * When present, `createRouter` reads these as defaults — no need
+     * to pass `root`, `mode`, or `hmrUrl` manually.
+     *
+     * @see {@link RouterOptions.mode}
+     * @see {@link RouterOptions.hmrUrl}
+     * @see {@link RouterOptions.root}
+     */
+    readonly _meta?: {
+        readonly root?: string;
+        readonly mode?: 'development' | 'production';
+        readonly hmrUrl?: string;
+        /** Public URL prefix for client assets (e.g., `'/assets/'`). */
+        readonly assetPrefix?: string;
+        /** Client entry script that calls `hydrateRoot()`. */
+        readonly clientEntry?: string;
+    };
+}
+/**
+ * Optional configuration for the Juice edge router.
+ *
+ * All fields are optional and additive — the router works with zero
+ * configuration. Use hooks for auth guards, custom error pages,
+ * logging, and other cross-cutting concerns.
+ *
+ * @example
+ * ```ts
+ * createRouter(manifest, {
+ *   basePath: '/app',
+ *   onBeforeRequest: (req) => {
+ *     if (!getSession(req)) {
+ *       return Response.redirect('/login', 302);
+ *     }
+ *   },
+ *   onNotFound: () => new Response('Page not found', { status: 404 }),
+ *   onError: (err, req) => {
+ *     console.error('[app]', req.url, err);
+ *     return new Response('Something broke', { status: 500 });
+ *   },
+ * });
+ * ```
+ */
+export interface RouterOptions {
+    /**
+     * The root URL for resolving module paths in `import()` calls.
+     *
+     * **Why this is needed:** The runtime resolves module paths like
+     * `'./app/routes/home.tsx'` via dynamic `import()`. Without a root,
+     * these paths resolve relative to the **runtime package's** directory
+     * (e.g., `node_modules/juice/dist/runtime/`), not your app's root.
+     *
+     * Pass `import.meta.url` from your server entry point to anchor
+     * module resolution to your project directory.
+     *
+     * @example
+     * ```ts
+     * // server.ts
+     * import { createRouter } from '@cmj/juice/runtime';
+     * import manifest from './flight-manifest.json';
+     *
+     * export default {
+     *   fetch: createRouter(manifest, {
+     *     root: import.meta.url, // anchors imports to this file's directory
+     *   }),
+     * };
+     * ```
+     */
+    readonly root?: string;
+    /**
+     * Base path prefix for all routes (e.g., `'/app'`).
+     * Trailing slashes are normalized automatically.
+     * @default '/'
+     */
+    readonly basePath?: string;
+    /**
+     * Hook called before every request is routed.
+     *
+     * Return a `Response` to short-circuit the pipeline entirely
+     * (useful for auth guards, CORS preflight, redirects, etc.).
+     * Return `void` / `undefined` to continue normal routing.
+     */
+    readonly onBeforeRequest?: (req: Request) => Response | void | Promise<Response | void>;
+    /**
+     * Hook called when no route matches the request URL.
+     *
+     * @default Returns `new Response('Not Found', { status: 404 })`
+     */
+    readonly onNotFound?: (req: Request) => Response | Promise<Response>;
+    /**
+     * Hook called on unhandled errors (NOT thrown `Response` objects).
+     *
+     * Thrown `Response` objects are always returned directly — they
+     * never reach this hook.
+     *
+     * @default Returns `new Response('Internal Server Error', { status: 500 })`
+     */
+    readonly onError?: (error: unknown, req: Request) => Response | Promise<Response>;
+    /**
+     * Maximum time (in milliseconds) allowed for a single request.
+     * If a render or action exceeds this, the request is aborted and
+     * a `504 Gateway Timeout` response is returned.
+     *
+     * Set to `0` or `undefined` to disable (no timeout).
+     *
+     * @default undefined (no timeout)
+     */
+    readonly requestTimeout?: number;
+    /**
+     * Runtime mode. Controls error verbosity, module caching, and
+     * HMR integration.
+     *
+     * - `'development'`: Rich HTML error overlays with stack traces,
+     *   module cache-busting on every request (edits are picked up
+     *   without restart), and Vite HMR client script injection.
+     * - `'production'`: Minimal error responses, modules cached
+     *   normally, no dev tooling injected.
+     *
+     * @default 'production'
+     *
+     * @example
+     * ```ts
+     * createRouter(manifest, {
+     *   mode: process.env.NODE_ENV === 'production' ? 'production' : 'development',
+     *   root: import.meta.url,
+     * });
+     * ```
+     */
+    readonly mode?: 'development' | 'production';
+    /**
+     * Vite HMR WebSocket URL to inject into SSR-rendered pages.
+     * Only used when `mode` is `'development'`.
+     *
+     * When set, a `<script type="module" src="/@vite/client"></script>`
+     * tag is injected into every HTML response, enabling Vite's
+     * hot module replacement and fast refresh in the browser.
+     *
+     * @default '/@vite/client'
+     *
+     * @example
+     * ```ts
+     * createRouter(manifest, {
+     *   mode: 'development',
+     *   hmrUrl: '/@vite/client',
+     * });
+     * ```
+     */
+    readonly hmrUrl?: string;
+    /**
+     * Public URL prefix prepended to client chunk paths from the
+     * manifest. Ensures `bootstrapModules` generates valid browser
+     * URLs (e.g., `'/assets/'` → `'/assets/Counter.CxK3d.js'`).
+     *
+     * Auto-detected from manifest `_meta` when the Vite plugin
+     * injects it. Only set manually for non-standard deployments.
+     *
+     * @default '/' in production, Vite dev server base in development
+     */
+    readonly assetPrefix?: string;
+    /**
+     * Path to the client entry module that calls `hydrateRoot()`.
+     * Injected into `bootstrapModules` so React knows how to
+     * hydrate the page on the client.
+     *
+     * Auto-detected from manifest `_meta` when the Vite plugin
+     * injects it.
+     *
+     * @example `'/src/entry-client.tsx'`
+     */
+    readonly clientEntry?: string;
+}
+/**
+ * A compiled route pairs a `URLPattern` with its manifest entry.
+ * Created once at startup inside `createRouter`.
+ * @internal
+ */
+export interface _CompiledRoute {
+    readonly pattern: URLPattern;
+    readonly entry: RouteEntry;
+}
+/**
+ * Result of a successful route match.
+ * @internal
+ */
+export interface _RouteMatch {
+    readonly entry: RouteEntry;
+    readonly params: Readonly<Record<string, string>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAEnC,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAEtD,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IAElE,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IAElE;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;QAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,gEAAgE;QAChE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,sDAAsD;QACtD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,GAAG,EAAE,OAAO,KACT,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErE;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CACjB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,KACT,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAElC;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;IAE7C;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD"}

package/dist/runtime/types.js

@@ -0,0 +1,5 @@
+// ── juice/runtime types ────────────────────────────────────────────
+// WinterCG only. No Node.js APIs. No bundler awareness.
+// ────────────────────────────────────────────────────────────────────
+export {};
+//# sourceMappingURL=types.js.map

package/dist/runtime/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,wDAAwD;AACxD,uEAAuE"}