@meekojs/meeko 0.0.3 → 0.1.0

package/dist/framework/client.js

@@ -0,0 +1,249 @@
+import { createAppErrorChannel, provideAppErrorChannel } from "../component-errors.js";
+import { finishWithCleanup, signal } from "../reactivity.js";
+import { pageSearchObject, validatePageInputs } from "./page.js";
+import { runRouteMiddleware } from "./middleware.js";
+import { createNavigator, matchRoute, reportNavigationError } from "./router.js";
+import { hydrateWithStateStore, StateStore, withStateStore } from "./state.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readPayload(value) {
+    const parsed = typeof value === "string" ? JSON.parse(value) : value;
+    if (!isRecord(parsed) || typeof parsed.route !== "string" || !isRecord(parsed.props) || !isRecord(parsed.state)) {
+        throw new TypeError("Invalid Meeko hydration payload");
+    }
+    if (!isRecord(parsed.props.params) || !isRecord(parsed.props.search))
+        throw new TypeError("Invalid Meeko route props");
+    if (parsed.sharedState !== undefined && !isRecord(parsed.sharedState))
+        throw new TypeError("Invalid Meeko shared state");
+    return { route: parsed.route, props: parsed.props, state: parsed.state, sharedState: parsed.sharedState ?? {} };
+}
+function applyCsrfToken(browser, token) {
+    const meta = browser.document.querySelector('meta[name="meeko-csrf-token"]');
+    const previous = meta?.getAttribute("content") ?? null;
+    let created;
+    if (token && meta)
+        meta.content = token;
+    else if (token) {
+        created = browser.document.createElement("meta");
+        created.name = "meeko-csrf-token";
+        created.content = token;
+        browser.document.head.append(created);
+    }
+    else
+        meta?.remove();
+    return () => {
+        if (meta) {
+            if (!meta.isConnected)
+                browser.document.head.append(meta);
+            if (previous === null)
+                meta.removeAttribute("content");
+            else
+                meta.setAttribute("content", previous);
+        }
+        else
+            created?.remove();
+    };
+}
+function bind(component, props) {
+    return {
+        renderWithState: () => component.renderWithState(props),
+        renderToString: () => component.renderToString(props),
+        hydrateScope: (scope, _unused, state) => component.hydrateScope(scope, props, state),
+    };
+}
+async function createTree(route, props, loadPage, fromLayout) {
+    let component = bind(await loadPage(route.file), props);
+    const layouts = [];
+    for (let index = route.layouts.length - 1; index >= fromLayout; index--) {
+        const file = route.layouts[index];
+        const outlet = signal(component);
+        const layoutProps = Object.defineProperty({}, "outlet", {
+            enumerable: true,
+            get: () => outlet.value,
+        });
+        component = bind(await loadPage(file), layoutProps);
+        layouts.unshift({ file, outlet });
+    }
+    return { component, layouts };
+}
+/**
+ * Hydrates the SSR tree and updates only the first changed outlet on navigation.
+ * Layout templates render their outlet with <component is="props.outlet"/>.
+ */
+export async function mountClientApp(options) {
+    const browser = options.browser ?? window;
+    const payload = readPayload(options.payload);
+    const initial = matchRoute(options.routes, browser.location.pathname);
+    if (!initial || initial.route.id !== payload.route)
+        throw new Error("Meeko route hydration mismatch");
+    if (JSON.stringify(initial.params) !== JSON.stringify(payload.props.params))
+        throw new Error("Meeko route parameters do not match SSR");
+    const stateStore = new StateStore(payload.sharedState);
+    const errorChannel = createAppErrorChannel();
+    const observeNavigationError = options.onNavigationError ?? ((error) => {
+        const handler = errorChannel.current();
+        if (handler)
+            return handler(error);
+        reportNavigationError(browser, error);
+    });
+    const hydrateApp = (hydrate) => hydrateWithStateStore(stateStore, () => {
+        provideAppErrorChannel(errorChannel);
+        return hydrate();
+    });
+    const first = await createTree(initial.route, payload.props, options.loadPage, 0);
+    let layouts = first.layouts;
+    let release = hydrateApp(() => first.component.hydrateScope({ root: options.root }, {}, payload.state));
+    let disposed = false;
+    let stableUrl = browser.location.href;
+    const recoverCommitFailure = (error) => {
+        // A failed outlet update or hydration can leave live scopes attached to a
+        // partially replaced tree. Recreate the last committed route with SSR.
+        try {
+            browser.location.replace(stableUrl);
+        }
+        catch (recoveryError) {
+            throw new AggregateError([error, recoveryError], "Meeko navigation failed and could not restore the previous route");
+        }
+        throw error;
+    };
+    const navigator = createNavigator(options.routes, async (context) => {
+        if (options.loadMiddleware) {
+            const response = await runRouteMiddleware(await options.loadMiddleware(), {
+                url: context.url, match: context.match, signal: context.signal, phase: "client",
+            });
+            if (context.signal.aborted || disposed)
+                return false;
+            if (response) {
+                const location = response.headers.get("location");
+                if (response.status >= 300 && response.status < 400 && location) {
+                    const target = new URL(location, context.url);
+                    if (target.href === context.url.href)
+                        throw new Error("Route middleware redirected to the same URL");
+                    browser.location.assign(target.href);
+                }
+                else
+                    reportNavigationError(browser, new Error(`Route middleware blocked navigation: HTTP ${response.status}`), observeNavigationError);
+                return false;
+            }
+        }
+        let props;
+        let serverSharedState;
+        let serverCsrfToken = null;
+        let loaderDraft;
+        if (options.serverData && !options.loadRoute) {
+            const response = await (options.fetch ?? fetch)(context.url.href, {
+                headers: { accept: "application/meeko+json" }, credentials: "same-origin", signal: context.signal,
+            });
+            if (!response.ok)
+                throw new Error(`Route data request failed: HTTP ${response.status}`);
+            serverCsrfToken = response.headers.get("x-meeko-csrf-token");
+            const payload = readPayload(await response.text());
+            if (payload.route !== context.match.route.id)
+                throw new Error("Meeko route data mismatch");
+            if (context.signal.aborted || disposed)
+                return;
+            serverSharedState = payload.sharedState;
+            props = payload.props;
+        }
+        else {
+            const sidecar = context.match.route.sidecar && options.loadRoute
+                ? await options.loadRoute(context.match.route.sidecar)
+                : undefined;
+            const validated = await validatePageInputs(sidecar, context.match.params, pageSearchObject(context.url.searchParams));
+            loaderDraft = sidecar?.load ? stateStore.navigationDraft() : undefined;
+            const data = sidecar?.load ? await sidecar.load({ ...context, ...validated, state: loaderDraft.state }) : undefined;
+            props = {
+                params: validated.params,
+                search: validated.search,
+                ...(data === undefined ? {} : { data }),
+            };
+        }
+        if (context.signal.aborted || disposed)
+            return;
+        const retained = Math.min(context.retainedLayouts, layouts.length);
+        const next = await createTree(context.match.route, props, options.loadPage, retained);
+        if (context.signal.aborted || disposed)
+            return;
+        const commit = () => {
+            if (retained) {
+                try {
+                    withStateStore(stateStore, () => { layouts[retained - 1].outlet.value = next.component; });
+                }
+                catch (error) {
+                    recoverCommitFailure(error);
+                }
+                layouts = [...layouts.slice(0, retained), ...next.layouts];
+                stableUrl = context.url.href;
+                return;
+            }
+            const rendered = withStateStore(stateStore, () => next.component.renderWithState({}));
+            try {
+                release();
+                options.root.innerHTML = rendered.html;
+                release = hydrateApp(() => next.component.hydrateScope({ root: options.root }, {}, rendered.state));
+            }
+            catch (error) {
+                recoverCommitFailure(error);
+            }
+            layouts = next.layouts;
+            stableUrl = context.url.href;
+        };
+        const commitWithToken = () => {
+            const restoreToken = serverCsrfToken === null ? undefined : applyCsrfToken(browser, serverCsrfToken);
+            try {
+                commit();
+            }
+            catch (error) {
+                try {
+                    restoreToken?.();
+                }
+                catch (restoreError) {
+                    throw new AggregateError([error, restoreError], "Meeko navigation and CSRF recovery failed");
+                }
+                throw error;
+            }
+        };
+        if (serverSharedState)
+            stateStore.seedForNavigation(serverSharedState, commitWithToken);
+        else if (loaderDraft)
+            loaderDraft.commit(commitWithToken);
+        else
+            commitWithToken();
+    }, browser, observeNavigationError);
+    const onClick = (event) => {
+        if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+            return;
+        const target = event.target;
+        if (!target || !("closest" in target) || typeof target.closest !== "function")
+            return;
+        const anchor = target.closest("a[href]");
+        if (!anchor || anchor.hasAttribute("download") || (anchor.target && anchor.target !== "_self"))
+            return;
+        let url;
+        try {
+            url = new URL(anchor.href, browser.location.href);
+        }
+        catch {
+            return;
+        }
+        if (url.origin !== browser.location.origin || !matchRoute(options.routes, url.pathname))
+            return;
+        event.preventDefault();
+        void navigator.navigate(url.href).catch((error) => reportNavigationError(browser, error, observeNavigationError));
+    };
+    browser.document.addEventListener("click", onClick);
+    return {
+        navigate: navigator.navigate,
+        state: stateStore,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            navigator.dispose();
+            browser.document.removeEventListener("click", onClick);
+            finishWithCleanup(release, () => errorChannel.clear());
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/framework/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/framework/client.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Component, DomScope } from \"../dom.js\";\nimport { createAppErrorChannel, provideAppErrorChannel } from \"../component-errors.js\";\nimport { finishWithCleanup, signal } from \"../reactivity.js\";\nimport type { Signal } from \"../reactivity.js\";\nimport { pageSearchObject, validatePageInputs } from \"./page.js\";\nimport type { PageSchema } from \"./page.js\";\nimport { runRouteMiddleware } from \"./middleware.js\";\nimport type { RouteMiddleware } from \"./middleware.js\";\nimport { createNavigator, matchRoute, reportNavigationError } from \"./router.js\";\nimport type { NavigationContext, Navigator, RouteRecord } from \"./router.js\";\nimport { hydrateWithStateStore, StateStore, withStateStore } from \"./state.js\";\n\n/** The public shape emitted by the .meeko compiler. */\nexport interface ClientComponent {\n  renderWithState(props: Record<string, unknown>): { html: string; state: Record<string, unknown> };\n  renderToString(props: Record<string, unknown>, state?: Record<string, unknown>): string;\n  hydrateScope(scope: DomScope, props: Record<string, unknown>, state?: Record<string, unknown>): () => void;\n}\n\nexport interface ClientRoute {\n  /** Client-safe loader. Server-only sidecars must not be passed to loadRoute. */\n  params?: PageSchema;\n  search?: PageSchema;\n  load?: (context: NavigationContext & {\n    params: Readonly<Record<string, unknown>>;\n    search: Readonly<Record<string, unknown>>;\n    state: StateStore;\n  }) => Promise<unknown> | unknown;\n}\n\nexport interface ClientAppOptions {\n  readonly routes: readonly RouteRecord[];\n  readonly root: Element;\n  readonly payload: string | unknown;\n  readonly loadPage: (file: string) => Promise<ClientComponent>;\n  readonly loadRoute?: (file: string) => Promise<ClientRoute>;\n  /** Runs the same route guards as SSR before a browser navigation fetch. */\n  readonly loadMiddleware?: () => Promise<readonly RouteMiddleware[]>;\n  /** Fetches public loader data from the SSR handler during browser navigation. */\n  readonly serverData?: boolean;\n  readonly fetch?: typeof fetch;\n  readonly onNavigationError?: (error: unknown) => void;\n  readonly browser?: Window;\n}\n\nexport interface ClientApp {\n  navigate: Navigator[\"navigate\"];\n  readonly state: StateStore;\n  dispose(): void;\n}\n\ninterface HydrationPayload {\n  route: string;\n  props: Record<string, unknown>;\n  state: Record<string, unknown>;\n  sharedState: Record<string, unknown>;\n}\n\ninterface LayoutInstance {\n  file: string;\n  outlet: Signal<Component<Record<string, unknown>>>;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction readPayload(value: unknown): HydrationPayload {\n  const parsed: unknown = typeof value === \"string\" ? JSON.parse(value) : value;\n  if (!isRecord(parsed) || typeof parsed.route !== \"string\" || !isRecord(parsed.props) || !isRecord(parsed.state)) {\n    throw new TypeError(\"Invalid Meeko hydration payload\");\n  }\n  if (!isRecord(parsed.props.params) || !isRecord(parsed.props.search)) throw new TypeError(\"Invalid Meeko route props\");\n  if (parsed.sharedState !== undefined && !isRecord(parsed.sharedState)) throw new TypeError(\"Invalid Meeko shared state\");\n  return { route: parsed.route, props: parsed.props, state: parsed.state, sharedState: parsed.sharedState ?? {} };\n}\n\nfunction applyCsrfToken(browser: Window, token: string): () => void {\n  const meta = browser.document.querySelector<HTMLMetaElement>('meta[name=\"meeko-csrf-token\"]');\n  const previous = meta?.getAttribute(\"content\") ?? null;\n  let created: HTMLMetaElement | undefined;\n  if (token && meta) meta.content = token;\n  else if (token) {\n    created = browser.document.createElement(\"meta\");\n    created.name = \"meeko-csrf-token\";\n    created.content = token;\n    browser.document.head.append(created);\n  } else meta?.remove();\n  return () => {\n    if (meta) {\n      if (!meta.isConnected) browser.document.head.append(meta);\n      if (previous === null) meta.removeAttribute(\"content\");\n      else meta.setAttribute(\"content\", previous);\n    } else created?.remove();\n  };\n}\n\nfunction bind(component: ClientComponent, props: Record<string, unknown>): Component<Record<string, unknown>> {\n  return {\n    renderWithState: () => component.renderWithState(props),\n    renderToString: () => component.renderToString(props),\n    hydrateScope: (scope, _unused, state) => component.hydrateScope(scope, props, state),\n  };\n}\n\nasync function createTree(\n  route: RouteRecord,\n  props: Record<string, unknown>,\n  loadPage: ClientAppOptions[\"loadPage\"],\n  fromLayout: number,\n): Promise<{ component: Component<Record<string, unknown>>; layouts: LayoutInstance[] }> {\n  let component = bind(await loadPage(route.file), props);\n  const layouts: LayoutInstance[] = [];\n  for (let index = route.layouts.length - 1; index >= fromLayout; index--) {\n    const file = route.layouts[index]!;\n    const outlet = signal(component);\n    const layoutProps = Object.defineProperty({}, \"outlet\", {\n      enumerable: true,\n      get: () => outlet.value,\n    }) as Record<string, unknown>;\n    component = bind(await loadPage(file), layoutProps);\n    layouts.unshift({ file, outlet });\n  }\n  return { component, layouts };\n}\n\n/**\n * Hydrates the SSR tree and updates only the first changed outlet on navigation.\n * Layout templates render their outlet with <component is=\"props.outlet\"/>.\n */\nexport async function mountClientApp(options: ClientAppOptions): Promise<ClientApp> {\n  const browser = options.browser ?? window;\n  const payload = readPayload(options.payload);\n  const initial = matchRoute(options.routes, browser.location.pathname);\n  if (!initial || initial.route.id !== payload.route) throw new Error(\"Meeko route hydration mismatch\");\n  if (JSON.stringify(initial.params) !== JSON.stringify(payload.props.params)) throw new Error(\"Meeko route parameters do not match SSR\");\n  const stateStore = new StateStore(payload.sharedState);\n  const errorChannel = createAppErrorChannel();\n  const observeNavigationError = options.onNavigationError ?? ((error: unknown) => {\n    const handler = errorChannel.current();\n    if (handler) return handler(error);\n    reportNavigationError(browser, error);\n  });\n  const hydrateApp = (hydrate: () => () => void) => hydrateWithStateStore(stateStore, () => {\n    provideAppErrorChannel(errorChannel);\n    return hydrate();\n  });\n  const first = await createTree(initial.route, payload.props, options.loadPage, 0);\n  let layouts = first.layouts;\n  let release = hydrateApp(() => first.component.hydrateScope({ root: options.root }, {}, payload.state));\n  let disposed = false;\n  let stableUrl = browser.location.href;\n  const recoverCommitFailure = (error: unknown): never => {\n    // A failed outlet update or hydration can leave live scopes attached to a\n    // partially replaced tree. Recreate the last committed route with SSR.\n    try {\n      browser.location.replace(stableUrl);\n    } catch (recoveryError) {\n      throw new AggregateError([error, recoveryError], \"Meeko navigation failed and could not restore the previous route\");\n    }\n    throw error;\n  };\n  const navigator = createNavigator(options.routes, async (context) => {\n    if (options.loadMiddleware) {\n      const response = await runRouteMiddleware(await options.loadMiddleware(), {\n        url: context.url, match: context.match, signal: context.signal, phase: \"client\",\n      });\n      if (context.signal.aborted || disposed) return false;\n      if (response) {\n        const location = response.headers.get(\"location\");\n        if (response.status >= 300 && response.status < 400 && location) {\n          const target = new URL(location, context.url);\n          if (target.href === context.url.href) throw new Error(\"Route middleware redirected to the same URL\");\n          browser.location.assign(target.href);\n        } else reportNavigationError(browser, new Error(`Route middleware blocked navigation: HTTP ${response.status}`), observeNavigationError);\n        return false;\n      }\n    }\n    let props: Record<string, unknown>;\n    let serverSharedState: Record<string, unknown> | undefined;\n    let serverCsrfToken: string | null = null;\n    let loaderDraft: ReturnType<StateStore[\"navigationDraft\"]> | undefined;\n    if (options.serverData && !options.loadRoute) {\n      const response = await (options.fetch ?? fetch)(context.url.href, {\n        headers: { accept: \"application/meeko+json\" }, credentials: \"same-origin\", signal: context.signal,\n      });\n      if (!response.ok) throw new Error(`Route data request failed: HTTP ${response.status}`);\n      serverCsrfToken = response.headers.get(\"x-meeko-csrf-token\");\n      const payload = readPayload(await response.text());\n      if (payload.route !== context.match.route.id) throw new Error(\"Meeko route data mismatch\");\n      if (context.signal.aborted || disposed) return;\n      serverSharedState = payload.sharedState;\n      props = payload.props;\n    } else {\n      const sidecar = context.match.route.sidecar && options.loadRoute\n        ? await options.loadRoute(context.match.route.sidecar)\n        : undefined;\n      const validated = await validatePageInputs(sidecar, context.match.params, pageSearchObject(context.url.searchParams));\n      loaderDraft = sidecar?.load ? stateStore.navigationDraft() : undefined;\n      const data = sidecar?.load ? await sidecar.load({ ...context, ...validated, state: loaderDraft!.state }) : undefined;\n      props = {\n        params: validated.params,\n        search: validated.search,\n        ...(data === undefined ? {} : { data }),\n      };\n    }\n    if (context.signal.aborted || disposed) return;\n    const retained = Math.min(context.retainedLayouts, layouts.length);\n    const next = await createTree(context.match.route, props, options.loadPage, retained);\n    if (context.signal.aborted || disposed) return;\n    const commit = () => {\n      if (retained) {\n        try {\n          withStateStore(stateStore, () => { layouts[retained - 1]!.outlet.value = next.component; });\n        } catch (error) {\n          recoverCommitFailure(error);\n        }\n        layouts = [...layouts.slice(0, retained), ...next.layouts];\n        stableUrl = context.url.href;\n        return;\n      }\n      const rendered = withStateStore(stateStore, () => next.component.renderWithState({}));\n      try {\n        release();\n        options.root.innerHTML = rendered.html;\n        release = hydrateApp(() => next.component.hydrateScope({ root: options.root }, {}, rendered.state));\n      } catch (error) {\n        recoverCommitFailure(error);\n      }\n      layouts = next.layouts;\n      stableUrl = context.url.href;\n    };\n    const commitWithToken = () => {\n      const restoreToken = serverCsrfToken === null ? undefined : applyCsrfToken(browser, serverCsrfToken);\n      try { commit(); }\n      catch (error) {\n        try { restoreToken?.(); }\n        catch (restoreError) { throw new AggregateError([error, restoreError], \"Meeko navigation and CSRF recovery failed\"); }\n        throw error;\n      }\n    };\n    if (serverSharedState) stateStore.seedForNavigation(serverSharedState, commitWithToken);\n    else if (loaderDraft) loaderDraft.commit(commitWithToken);\n    else commitWithToken();\n  }, browser, observeNavigationError);\n  const onClick = (event: MouseEvent) => {\n    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;\n    const target = event.target;\n    if (!target || !(\"closest\" in target) || typeof target.closest !== \"function\") return;\n    const anchor = target.closest(\"a[href]\") as HTMLAnchorElement | null;\n    if (!anchor || anchor.hasAttribute(\"download\") || (anchor.target && anchor.target !== \"_self\")) return;\n    let url: URL;\n    try { url = new URL(anchor.href, browser.location.href); }\n    catch { return; }\n    if (url.origin !== browser.location.origin || !matchRoute(options.routes, url.pathname)) return;\n    event.preventDefault();\n    void navigator.navigate(url.href).catch((error: unknown) => reportNavigationError(browser, error, observeNavigationError));\n  };\n  browser.document.addEventListener(\"click\", onClick);\n  return {\n    navigate: navigator.navigate,\n    state: stateStore,\n    dispose() {\n      if (disposed) return;\n      disposed = true;\n      navigator.dispose();\n      browser.document.removeEventListener(\"click\", onClick);\n      finishWithCleanup(release, () => errorChannel.clear());\n    },\n  };\n}\n"]}

package/dist/framework/clients.d.ts

@@ -0,0 +1,82 @@
+/** Public descriptors intentionally omit handler files and server schemas. */
+export interface PublicApiEndpoint {
+    readonly clientKey: string;
+    readonly pathname: string;
+    readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    readonly contentType?: "json" | "response";
+}
+export interface PublicRpcEndpoint {
+    readonly id: string;
+    readonly pathname: string;
+}
+export interface PublicServerManifest {
+    readonly api: readonly PublicApiEndpoint[];
+    readonly rpc: readonly PublicRpcEndpoint[];
+}
+/** Strips private handler paths before serializing a discovered server manifest. */
+export declare function createPublicServerManifest(manifest: PublicServerManifest): PublicServerManifest;
+/** Type-only operation declarations can be inferred from public shared schemas. */
+export interface ApiOperation<Params = undefined, Query = undefined, Body = undefined, Output = unknown> {
+    readonly params: Params;
+    readonly query: Query;
+    readonly body: Body;
+    readonly output: Output;
+}
+export interface RpcOperation<Input = unknown, Output = unknown> {
+    readonly input: Input;
+    readonly output: Output;
+}
+type AnyApiOperation = ApiOperation<unknown, unknown, unknown, unknown>;
+type RequestOptions = {
+    readonly signal?: AbortSignal;
+};
+type ParamOption<T> = T extends undefined ? {
+    readonly params?: never;
+} : {
+    readonly params: T;
+};
+type QueryOption<T> = T extends undefined ? {
+    readonly query?: never;
+} : {
+    readonly query: T;
+};
+type BodyOption<T> = T extends undefined ? {
+    readonly body?: never;
+} : {
+    readonly body: T;
+};
+type ApiArguments<O extends AnyApiOperation> = O["params"] extends undefined ? O["query"] extends undefined ? O["body"] extends undefined ? [options?: ParamOption<O["params"]> & QueryOption<O["query"]> & BodyOption<O["body"]> & RequestOptions] : [options: ParamOption<O["params"]> & QueryOption<O["query"]> & BodyOption<O["body"]> & RequestOptions] : [options: ParamOption<O["params"]> & QueryOption<O["query"]> & BodyOption<O["body"]> & RequestOptions] : [options: ParamOption<O["params"]> & QueryOption<O["query"]> & BodyOption<O["body"]> & RequestOptions];
+type Nest<Path extends string, Value> = Path extends `${infer Head}.${infer Tail}` ? {
+    [K in Head]: Nest<Tail, Value>;
+} : {
+    [K in Path]: Value;
+};
+type Intersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (value: infer Result) => void ? Result : never;
+type ApiMethods<Operations> = {
+    [Method in keyof Operations]: Operations[Method] extends AnyApiOperation ? (...args: ApiArguments<Operations[Method]>) => Promise<Operations[Method]["output"]> : never;
+};
+export type ApiClient<Contract extends Record<string, Record<string, AnyApiOperation>>> = Intersection<{
+    [Key in keyof Contract & string]: Nest<Key, ApiMethods<Contract[Key]>>;
+}[keyof Contract & string]>;
+export type RpcClient<Contract extends Record<string, RpcOperation>> = Intersection<{
+    [Key in keyof Contract & string]: Nest<Key, (input: Contract[Key]["input"], options?: RequestOptions) => Promise<Contract[Key]["output"]>>;
+}[keyof Contract & string]>;
+export declare class ClientError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly requestId?: string | undefined;
+    constructor(code: string, status: number, requestId?: string | undefined);
+}
+export interface ClientOptions {
+    readonly baseUrl?: string | (() => string);
+    readonly fetch?: typeof fetch;
+    readonly csrfToken?: string | (() => string | undefined);
+    readonly headers?: HeadersInit | (() => HeadersInit);
+}
+/** Reads the current document token at call time, including after client navigation. */
+export declare function createBrowserClientOptions(): ClientOptions;
+/** Creates browser API methods from public endpoint paths, without server imports. */
+export declare function createApiClient<Contract extends Record<string, Record<string, AnyApiOperation>>>(manifest: Pick<PublicServerManifest, "api">, options?: ClientOptions): ApiClient<Contract>;
+/** Creates browser RPC procedures from public endpoint paths. */
+export declare function createRpcClient<Contract extends Record<string, RpcOperation>>(manifest: Pick<PublicServerManifest, "rpc">, options?: ClientOptions): RpcClient<Contract>;
+export {};

package/dist/framework/clients.js

@@ -0,0 +1,190 @@
+/** Strips private handler paths before serializing a discovered server manifest. */
+export function createPublicServerManifest(manifest) {
+    return {
+        api: manifest.api.map(({ clientKey, pathname, method, contentType }) => ({
+            clientKey, pathname, method, ...(contentType ? { contentType } : {}),
+        })),
+        rpc: manifest.rpc.map(({ id, pathname }) => ({ id, pathname })),
+    };
+}
+export class ClientError extends Error {
+    code;
+    status;
+    requestId;
+    constructor(code, status, requestId) {
+        super(code);
+        this.code = code;
+        this.status = status;
+        this.requestId = requestId;
+        this.name = "ClientError";
+    }
+}
+/** Reads the current document token at call time, including after client navigation. */
+export function createBrowserClientOptions() {
+    const currentCsrfToken = () => typeof document === "undefined"
+        ? undefined
+        : document.querySelector('meta[name="meeko-csrf-token"]')?.getAttribute("content") ?? undefined;
+    return {
+        csrfToken: currentCsrfToken,
+        fetch: async (input, init) => {
+            const sourceDocument = typeof document === "undefined" ? undefined : document;
+            const csrfTokenAtStart = currentCsrfToken();
+            const response = await fetch(input, init);
+            const token = response.headers.get("x-meeko-csrf-token");
+            // Navigation or a newer response may have rotated or cleared the token.
+            if (token !== null && sourceDocument && document === sourceDocument && currentCsrfToken() === csrfTokenAtStart) {
+                let meta = document.querySelector('meta[name="meeko-csrf-token"]');
+                if (!token) {
+                    meta?.remove();
+                    return response;
+                }
+                if (!meta) {
+                    meta = document.createElement("meta");
+                    meta.setAttribute("name", "meeko-csrf-token");
+                    document.head.append(meta);
+                }
+                meta.setAttribute("content", token);
+            }
+            return response;
+        },
+    };
+}
+function pathWithParams(pathname, params = {}) {
+    const used = new Set();
+    const path = pathname.replace(/\[(\.\.\.)?([A-Za-z_$][\w$]*)\]/g, (_match, rest, name) => {
+        const value = params[name];
+        if (!value)
+            throw new TypeError(`Missing route parameter: ${name}`);
+        used.add(name);
+        const parts = rest ? value.split("/") : [value];
+        if (parts.some((part) => !part || part === "." || part === ".." || part.includes("/") || part.includes("\\")))
+            throw new TypeError(`Invalid route parameter: ${name}`);
+        return parts.map(encodeURIComponent).join("/");
+    });
+    for (const key of Object.keys(params))
+        if (!used.has(key))
+            throw new TypeError(`Unknown route parameter: ${key}`);
+    return path;
+}
+function queryString(query) {
+    if (!query)
+        return "";
+    const search = new URLSearchParams();
+    for (const [key, raw] of Object.entries(query)) {
+        for (const value of Array.isArray(raw) ? raw : [raw]) {
+            if (value !== null && value !== undefined)
+                search.append(key, String(value));
+        }
+    }
+    const result = search.toString();
+    return result ? `?${result}` : "";
+}
+async function responseValue(response, contentType = "json") {
+    if (!response.ok) {
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch { /* Bad error bodies still produce a normalized error. */ }
+        const record = payload && typeof payload === "object" ? payload : {};
+        const code = typeof record.code === "string" ? record.code : "HTTP_ERROR";
+        const requestId = typeof record.requestId === "string" ? record.requestId : response.headers.get("x-request-id") ?? undefined;
+        throw new ClientError(code, response.status, requestId);
+    }
+    if (contentType === "response")
+        return response;
+    if (response.status === 204)
+        return undefined;
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new ClientError("INVALID_RESPONSE", response.status, response.headers.get("x-request-id") ?? undefined);
+    }
+}
+function endpointUrl(pathname, options) {
+    const baseUrl = typeof options.baseUrl === "function" ? options.baseUrl() : options.baseUrl;
+    return baseUrl ? new URL(pathname, baseUrl).toString() : pathname;
+}
+function headersFor(options, method, json) {
+    const headers = new Headers(typeof options.headers === "function" ? options.headers() : options.headers);
+    if (json)
+        headers.set("content-type", "application/json");
+    if (method !== "GET" && method !== "HEAD") {
+        const csrf = typeof options.csrfToken === "function" ? options.csrfToken() : options.csrfToken;
+        if (csrf)
+            headers.set("x-meeko-csrf", csrf);
+    }
+    return headers;
+}
+function insert(root, key, value) {
+    const parts = key.split(".");
+    if (parts.some((part) => !/^[A-Za-z_$][\w$]*$/.test(part)))
+        throw new TypeError(`Invalid client key: ${key}`);
+    let node = root;
+    for (const part of parts.slice(0, -1)) {
+        const existing = node[part];
+        if (existing === undefined)
+            node[part] = Object.create(null);
+        else if (!existing || typeof existing !== "object")
+            throw new TypeError(`Client key collision: ${key}`);
+        node = node[part];
+    }
+    const last = parts.at(-1);
+    if (node[last] !== undefined)
+        throw new TypeError(`Client key collision: ${key}`);
+    node[last] = value;
+}
+function ensureObject(root, key) {
+    const parts = key.split(".");
+    if (parts.some((part) => !/^[A-Za-z_$][\w$]*$/.test(part)))
+        throw new TypeError(`Invalid client key: ${key}`);
+    let node = root;
+    for (const part of parts) {
+        const existing = node[part];
+        if (existing === undefined)
+            node[part] = Object.create(null);
+        else if (!existing || typeof existing !== "object")
+            throw new TypeError(`Client key collision: ${key}`);
+        node = node[part];
+    }
+    return node;
+}
+/** Creates browser API methods from public endpoint paths, without server imports. */
+export function createApiClient(manifest, options = {}) {
+    const root = Object.create(null);
+    for (const endpoint of manifest.api) {
+        const methods = ensureObject(root, endpoint.clientKey);
+        const method = endpoint.method.toLowerCase();
+        if (methods[method])
+            throw new TypeError(`Duplicate API method: ${endpoint.clientKey}.${method}`);
+        methods[method] = async (input = {}) => {
+            const path = pathWithParams(endpoint.pathname, input.params) + queryString(input.query);
+            const url = endpointUrl(path, options);
+            const fetcher = options.fetch ?? fetch;
+            const response = await fetcher(url, {
+                method: endpoint.method, headers: headersFor(options, endpoint.method, input.body !== undefined),
+                credentials: "same-origin", ...(input.body === undefined ? {} : { body: JSON.stringify(input.body) }),
+                ...(input.signal ? { signal: input.signal } : {}),
+            });
+            return responseValue(response, endpoint.contentType);
+        };
+    }
+    return root;
+}
+/** Creates browser RPC procedures from public endpoint paths. */
+export function createRpcClient(manifest, options = {}) {
+    const root = Object.create(null);
+    for (const endpoint of manifest.rpc) {
+        insert(root, endpoint.id, async (input, request = {}) => {
+            const fetcher = options.fetch ?? fetch;
+            const response = await fetcher(endpointUrl(endpoint.pathname, options), {
+                method: "POST", headers: headersFor(options, "POST", true), credentials: "same-origin",
+                body: JSON.stringify(input), ...(request.signal ? { signal: request.signal } : {}),
+            });
+            return responseValue(response);
+        });
+    }
+    return root;
+}
+//# sourceMappingURL=clients.js.map

package/dist/framework/clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.js","sourceRoot":"","sources":["../../src/framework/clients.ts"],"names":[],"mappings":"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","sourcesContent":["/** Public descriptors intentionally omit handler files and server schemas. */\nexport interface PublicApiEndpoint {\n  readonly clientKey: string;\n  readonly pathname: string;\n  readonly method: \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n  readonly contentType?: \"json\" | \"response\";\n}\n\nexport interface PublicRpcEndpoint {\n  readonly id: string;\n  readonly pathname: string;\n}\n\nexport interface PublicServerManifest {\n  readonly api: readonly PublicApiEndpoint[];\n  readonly rpc: readonly PublicRpcEndpoint[];\n}\n\n/** Strips private handler paths before serializing a discovered server manifest. */\nexport function createPublicServerManifest(manifest: PublicServerManifest): PublicServerManifest {\n  return {\n    api: manifest.api.map(({ clientKey, pathname, method, contentType }) => ({\n      clientKey, pathname, method, ...(contentType ? { contentType } : {}),\n    })),\n    rpc: manifest.rpc.map(({ id, pathname }) => ({ id, pathname })),\n  };\n}\n\n/** Type-only operation declarations can be inferred from public shared schemas. */\nexport interface ApiOperation<Params = undefined, Query = undefined, Body = undefined, Output = unknown> {\n  readonly params: Params;\n  readonly query: Query;\n  readonly body: Body;\n  readonly output: Output;\n}\n\nexport interface RpcOperation<Input = unknown, Output = unknown> {\n  readonly input: Input;\n  readonly output: Output;\n}\n\ntype AnyApiOperation = ApiOperation<unknown, unknown, unknown, unknown>;\n\ntype SearchValue = string | number | boolean | null | undefined;\ntype QueryValue = SearchValue | readonly SearchValue[];\ntype RequestOptions = { readonly signal?: AbortSignal };\ntype ParamOption<T> = T extends undefined ? { readonly params?: never } : { readonly params: T };\ntype QueryOption<T> = T extends undefined ? { readonly query?: never } : { readonly query: T };\ntype BodyOption<T> = T extends undefined ? { readonly body?: never } : { readonly body: T };\ntype ApiArguments<O extends AnyApiOperation> = O[\"params\"] extends undefined\n  ? O[\"query\"] extends undefined\n    ? O[\"body\"] extends undefined ? [options?: ParamOption<O[\"params\"]> & QueryOption<O[\"query\"]> & BodyOption<O[\"body\"]> & RequestOptions] : [options: ParamOption<O[\"params\"]> & QueryOption<O[\"query\"]> & BodyOption<O[\"body\"]> & RequestOptions]\n    : [options: ParamOption<O[\"params\"]> & QueryOption<O[\"query\"]> & BodyOption<O[\"body\"]> & RequestOptions]\n  : [options: ParamOption<O[\"params\"]> & QueryOption<O[\"query\"]> & BodyOption<O[\"body\"]> & RequestOptions];\ntype Nest<Path extends string, Value> = Path extends `${infer Head}.${infer Tail}` ? { [K in Head]: Nest<Tail, Value> } : { [K in Path]: Value };\ntype Intersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (value: infer Result) => void ? Result : never;\ntype ApiMethods<Operations> = { [Method in keyof Operations]: Operations[Method] extends AnyApiOperation\n  ? (...args: ApiArguments<Operations[Method]>) => Promise<Operations[Method][\"output\"]>\n  : never };\nexport type ApiClient<Contract extends Record<string, Record<string, AnyApiOperation>>> = Intersection<{\n  [Key in keyof Contract & string]: Nest<Key, ApiMethods<Contract[Key]>>\n}[keyof Contract & string]>;\nexport type RpcClient<Contract extends Record<string, RpcOperation>> = Intersection<{\n  [Key in keyof Contract & string]: Nest<Key, (input: Contract[Key][\"input\"], options?: RequestOptions) => Promise<Contract[Key][\"output\"]>>\n}[keyof Contract & string]>;\n\nexport class ClientError extends Error {\n  constructor(public readonly code: string, public readonly status: number, public readonly requestId?: string) {\n    super(code);\n    this.name = \"ClientError\";\n  }\n}\n\nexport interface ClientOptions {\n  readonly baseUrl?: string | (() => string);\n  readonly fetch?: typeof fetch;\n  readonly csrfToken?: string | (() => string | undefined);\n  readonly headers?: HeadersInit | (() => HeadersInit);\n}\n\n/** Reads the current document token at call time, including after client navigation. */\nexport function createBrowserClientOptions(): ClientOptions {\n  const currentCsrfToken = (): string | undefined => typeof document === \"undefined\"\n    ? undefined\n    : document.querySelector('meta[name=\"meeko-csrf-token\"]')?.getAttribute(\"content\") ?? undefined;\n  return {\n    csrfToken: currentCsrfToken,\n    fetch: async (input, init) => {\n      const sourceDocument = typeof document === \"undefined\" ? undefined : document;\n      const csrfTokenAtStart = currentCsrfToken();\n      const response = await fetch(input, init);\n      const token = response.headers.get(\"x-meeko-csrf-token\");\n      // Navigation or a newer response may have rotated or cleared the token.\n      if (token !== null && sourceDocument && document === sourceDocument && currentCsrfToken() === csrfTokenAtStart) {\n        let meta = document.querySelector('meta[name=\"meeko-csrf-token\"]');\n        if (!token) {\n          meta?.remove();\n          return response;\n        }\n        if (!meta) {\n          meta = document.createElement(\"meta\");\n          meta.setAttribute(\"name\", \"meeko-csrf-token\");\n          document.head.append(meta);\n        }\n        meta.setAttribute(\"content\", token);\n      }\n      return response;\n    },\n  };\n}\n\nfunction pathWithParams(pathname: string, params: Readonly<Record<string, string>> = {}): string {\n  const used = new Set<string>();\n  const path = pathname.replace(/\\[(\\.\\.\\.)?([A-Za-z_$][\\w$]*)\\]/g, (_match, rest: string | undefined, name: string) => {\n    const value = params[name];\n    if (!value) throw new TypeError(`Missing route parameter: ${name}`);\n    used.add(name);\n    const parts = rest ? value.split(\"/\") : [value];\n    if (parts.some((part) => !part || part === \".\" || part === \"..\" || part.includes(\"/\") || part.includes(\"\\\\\"))) throw new TypeError(`Invalid route parameter: ${name}`);\n    return parts.map(encodeURIComponent).join(\"/\");\n  });\n  for (const key of Object.keys(params)) if (!used.has(key)) throw new TypeError(`Unknown route parameter: ${key}`);\n  return path;\n}\n\nfunction queryString(query: Readonly<Record<string, QueryValue>> | undefined): string {\n  if (!query) return \"\";\n  const search = new URLSearchParams();\n  for (const [key, raw] of Object.entries(query)) {\n    for (const value of Array.isArray(raw) ? raw : [raw]) {\n      if (value !== null && value !== undefined) search.append(key, String(value));\n    }\n  }\n  const result = search.toString();\n  return result ? `?${result}` : \"\";\n}\n\nasync function responseValue(response: Response, contentType: \"json\" | \"response\" = \"json\"): Promise<unknown> {\n  if (!response.ok) {\n    let payload: unknown;\n    try { payload = await response.json(); } catch { /* Bad error bodies still produce a normalized error. */ }\n    const record = payload && typeof payload === \"object\" ? payload as Record<string, unknown> : {};\n    const code = typeof record.code === \"string\" ? record.code : \"HTTP_ERROR\";\n    const requestId = typeof record.requestId === \"string\" ? record.requestId : response.headers.get(\"x-request-id\") ?? undefined;\n    throw new ClientError(code, response.status, requestId);\n  }\n  if (contentType === \"response\") return response;\n  if (response.status === 204) return undefined;\n  try { return await response.json(); }\n  catch { throw new ClientError(\"INVALID_RESPONSE\", response.status, response.headers.get(\"x-request-id\") ?? undefined); }\n}\n\nfunction endpointUrl(pathname: string, options: ClientOptions): string {\n  const baseUrl = typeof options.baseUrl === \"function\" ? options.baseUrl() : options.baseUrl;\n  return baseUrl ? new URL(pathname, baseUrl).toString() : pathname;\n}\n\nfunction headersFor(options: ClientOptions, method: string, json: boolean): Headers {\n  const headers = new Headers(typeof options.headers === \"function\" ? options.headers() : options.headers);\n  if (json) headers.set(\"content-type\", \"application/json\");\n  if (method !== \"GET\" && method !== \"HEAD\") {\n    const csrf = typeof options.csrfToken === \"function\" ? options.csrfToken() : options.csrfToken;\n    if (csrf) headers.set(\"x-meeko-csrf\", csrf);\n  }\n  return headers;\n}\n\nfunction insert(root: Record<string, unknown>, key: string, value: unknown): void {\n  const parts = key.split(\".\");\n  if (parts.some((part) => !/^[A-Za-z_$][\\w$]*$/.test(part))) throw new TypeError(`Invalid client key: ${key}`);\n  let node = root;\n  for (const part of parts.slice(0, -1)) {\n    const existing = node[part];\n    if (existing === undefined) node[part] = Object.create(null) as Record<string, unknown>;\n    else if (!existing || typeof existing !== \"object\") throw new TypeError(`Client key collision: ${key}`);\n    node = node[part] as Record<string, unknown>;\n  }\n  const last = parts.at(-1)!;\n  if (node[last] !== undefined) throw new TypeError(`Client key collision: ${key}`);\n  node[last] = value;\n}\n\nfunction ensureObject(root: Record<string, unknown>, key: string): Record<string, unknown> {\n  const parts = key.split(\".\");\n  if (parts.some((part) => !/^[A-Za-z_$][\\w$]*$/.test(part))) throw new TypeError(`Invalid client key: ${key}`);\n  let node = root;\n  for (const part of parts) {\n    const existing = node[part];\n    if (existing === undefined) node[part] = Object.create(null) as Record<string, unknown>;\n    else if (!existing || typeof existing !== \"object\") throw new TypeError(`Client key collision: ${key}`);\n    node = node[part] as Record<string, unknown>;\n  }\n  return node;\n}\n\n/** Creates browser API methods from public endpoint paths, without server imports. */\nexport function createApiClient<Contract extends Record<string, Record<string, AnyApiOperation>>>(manifest: Pick<PublicServerManifest, \"api\">, options: ClientOptions = {}): ApiClient<Contract> {\n  const root: Record<string, unknown> = Object.create(null);\n  for (const endpoint of manifest.api) {\n    const methods = ensureObject(root, endpoint.clientKey);\n    const method = endpoint.method.toLowerCase();\n    if (methods[method]) throw new TypeError(`Duplicate API method: ${endpoint.clientKey}.${method}`);\n    methods[method] = async (input: { params?: Record<string, string>; query?: Record<string, QueryValue>; body?: unknown; signal?: AbortSignal } = {}) => {\n      const path = pathWithParams(endpoint.pathname, input.params) + queryString(input.query);\n      const url = endpointUrl(path, options);\n      const fetcher = options.fetch ?? fetch;\n      const response = await fetcher(url, {\n        method: endpoint.method, headers: headersFor(options, endpoint.method, input.body !== undefined),\n        credentials: \"same-origin\", ...(input.body === undefined ? {} : { body: JSON.stringify(input.body) }),\n        ...(input.signal ? { signal: input.signal } : {}),\n      });\n      return responseValue(response, endpoint.contentType);\n    };\n  }\n  return root as ApiClient<Contract>;\n}\n\n/** Creates browser RPC procedures from public endpoint paths. */\nexport function createRpcClient<Contract extends Record<string, RpcOperation>>(manifest: Pick<PublicServerManifest, \"rpc\">, options: ClientOptions = {}): RpcClient<Contract> {\n  const root: Record<string, unknown> = Object.create(null);\n  for (const endpoint of manifest.rpc) {\n    insert(root, endpoint.id, async (input: unknown, request: RequestOptions = {}) => {\n      const fetcher = options.fetch ?? fetch;\n      const response = await fetcher(endpointUrl(endpoint.pathname, options), {\n        method: \"POST\", headers: headersFor(options, \"POST\", true), credentials: \"same-origin\",\n        body: JSON.stringify(input), ...(request.signal ? { signal: request.signal } : {}),\n      });\n      return responseValue(response);\n    });\n  }\n  return root as RpcClient<Contract>;\n}\n"]}

package/dist/framework/config-type.d.ts

@@ -0,0 +1,10 @@
+export interface MeekoConfig {
+    /** Layers are applied after the application, in declaration order. Collisions fail. */
+    readonly extends?: readonly string[];
+    /** Modules use the same app/pages convention as layers. */
+    readonly modules?: readonly string[];
+    readonly imports?: {
+        readonly serverDirs?: readonly string[];
+    };
+}
+export declare function defineMeekoConfig<const T extends MeekoConfig>(config: T): T;

package/dist/framework/config-type.js

@@ -0,0 +1,4 @@
+export function defineMeekoConfig(config) {
+    return config;
+}
+//# sourceMappingURL=config-type.js.map

package/dist/framework/config-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-type.js","sourceRoot":"","sources":["../../src/framework/config-type.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,iBAAiB,CAA8B,MAAS;IACtE,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["export interface MeekoConfig {\n  /** Layers are applied after the application, in declaration order. Collisions fail. */\n  readonly extends?: readonly string[];\n  /** Modules use the same app/pages convention as layers. */\n  readonly modules?: readonly string[];\n  readonly imports?: { readonly serverDirs?: readonly string[] };\n}\n\nexport function defineMeekoConfig<const T extends MeekoConfig>(config: T): T {\n  return config;\n}\n"]}