@pylonsync/functions 0.3.292 → 0.3.293

package/dist/define.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Function definition constructors.
+ *
+ * These are the primary API for defining server-side functions.
+ *
+ * Each constructor (query / mutation / action) has two overloads:
+ *
+ *   1. `auth` omitted, or `auth: "user" | "admin"` →  the framework
+ *      enforces a real signed-in user, so the handler's
+ *      `ctx.auth.userId` is narrowed from `string | null` to
+ *      `string`. The redundant `if (!ctx.auth.userId) throw …`
+ *      check disappears from app code.
+ *
+ *   2. `auth: "public" | "guest"` →  the function is reachable by
+ *      anonymous callers, so `ctx.auth.userId` stays `string | null`
+ *      and the handler must check it manually if relevant.
+ *
+ * The framework gate happens BEFORE the handler runs (in Rust,
+ * inside the router). A handler can't accidentally leak data by
+ * forgetting an auth check — when `auth: "user"` is in effect,
+ * an anonymous request never reaches the handler at all.
+ */
+import type { FnDefinition, QueryCtx, MutationCtx, ActionCtx, Validator } from "./types";
+interface CommonDef {
+    args?: Record<string, Validator>;
+    /**
+     * When true, the function is callable only via `ctx.runQuery()` /
+     * `ctx.runMutation()` / `ctx.runAction()` from another function
+     * — never via the public `/api/fn/<name>` HTTP endpoint. The
+     * router refuses external calls with `404 FN_NOT_FOUND` so
+     * probing can't even confirm the name exists.
+     *
+     * Use for helper functions that are safe inside trusted
+     * wrappers but unsafe if any caller could invoke them directly
+     * (e.g. they trust args without re-checking caller authority).
+     *
+     * Internal functions inherit the wrapping handler's auth — the
+     * `auth` field has no effect when `internal: true`. The router
+     * isn't reachable anyway, and the caller has already passed its
+     * own gate.
+     */
+    internal?: boolean;
+    /**
+     * Max wall-clock SECONDS this function may run before the runtime
+     * recycles its worker as wedged. Defaults to `PYLON_FN_CALL_TIMEOUT`
+     * (30s). Raise it for legitimately long-running work — heavy renders,
+     * big batch jobs, slow external calls — so the call isn't force-killed
+     * mid-flight. This also lifts the runtime's wedge backstop for the
+     * worker while such a call is in flight, so a busy-but-progressing
+     * worker (e.g. one doing synchronous canvas/image work that blocks the
+     * event loop) isn't respawned out from under the work.
+     *
+     * Keep it as small as the work honestly needs: a genuinely stuck call
+     * still ties up its worker until this deadline. Prefer offloading very
+     * heavy CPU work to a dedicated service over setting a huge timeout.
+     */
+    timeout?: number;
+}
+interface QueryDefRequired<TArgs, TReturn> extends CommonDef {
+    /** Defaults to `"user"`. See [`AuthMode`] for the full surface. */
+    auth?: "user" | "admin";
+    handler: (ctx: QueryCtx<"required">, args: TArgs) => Promise<TReturn>;
+}
+interface QueryDefOptional<TArgs, TReturn> extends CommonDef {
+    auth: "public" | "guest";
+    handler: (ctx: QueryCtx<"optional">, args: TArgs) => Promise<TReturn>;
+}
+interface MutationDefRequired<TArgs, TReturn> extends CommonDef {
+    auth?: "user" | "admin";
+    handler: (ctx: MutationCtx<"required">, args: TArgs) => Promise<TReturn>;
+}
+interface MutationDefOptional<TArgs, TReturn> extends CommonDef {
+    auth: "public" | "guest";
+    handler: (ctx: MutationCtx<"optional">, args: TArgs) => Promise<TReturn>;
+}
+interface ActionDefRequired<TArgs, TReturn> extends CommonDef {
+    auth?: "user" | "admin";
+    handler: (ctx: ActionCtx<"required">, args: TArgs) => Promise<TReturn>;
+}
+interface ActionDefOptional<TArgs, TReturn> extends CommonDef {
+    auth: "public" | "guest";
+    handler: (ctx: ActionCtx<"optional">, args: TArgs) => Promise<TReturn>;
+}
+/**
+ * Define a read-only query function.
+ *
+ * Queries use the read pool — they never block writes and can run
+ * concurrently. They cannot modify data.
+ *
+ * @example
+ * ```typescript
+ * export default query({
+ *   // auth: "user" is the default — ctx.auth.userId is `string`,
+ *   // not `string | null`, inside the handler.
+ *   args: { auctionId: v.string() },
+ *   async handler(ctx, args) {
+ *     return ctx.db.query("Lot", {
+ *       auctionId: args.auctionId,
+ *       authorId: ctx.auth.userId,
+ *     });
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Explicitly public — landing-page count, never auth-shaped.
+ * export default query({
+ *   auth: "public",
+ *   async handler(ctx) {
+ *     return ctx.db.query("PublicPost", { published: true });
+ *   },
+ * });
+ * ```
+ */
+export declare function query<TArgs = Record<string, unknown>, TReturn = unknown>(def: QueryDefRequired<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
+export declare function query<TArgs = Record<string, unknown>, TReturn = unknown>(def: QueryDefOptional<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
+/**
+ * Define a transactional mutation function.
+ *
+ * The entire handler IS the transaction. If it returns, all writes commit
+ * atomically. If it throws, all writes roll back — including scheduled
+ * functions.
+ *
+ * Mutations can stream data to the client via `ctx.stream.write()`.
+ * Stream chunks are sent immediately; DB writes commit at the end.
+ *
+ * @example
+ * ```typescript
+ * export default mutation({
+ *   args: { lotId: v.string(), amount: v.number() },
+ *   async handler(ctx, args) {
+ *     // ctx.auth.userId is `string` (not nullable) — the runtime
+ *     // already enforced `auth: "user"` (default) before reaching here.
+ *     const lot = await ctx.db.get("Lot", args.lotId);
+ *     if (!lot) throw ctx.error("NOT_FOUND", "Lot not found");
+ *     await ctx.db.insert("Bid", {
+ *       lotId: args.lotId,
+ *       amount: args.amount,
+ *       bidderId: ctx.auth.userId,
+ *     });
+ *     return { accepted: true };
+ *   },
+ * });
+ * ```
+ */
+export declare function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(def: MutationDefRequired<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
+export declare function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(def: MutationDefOptional<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
+/**
+ * Define an action function (external I/O allowed).
+ *
+ * Actions can call external APIs (fetch, email, Stripe, etc.) but cannot
+ * access the database directly. Use `ctx.runQuery()` and `ctx.runMutation()`
+ * for DB access — each runs in its own transaction.
+ *
+ * Actions are NOT automatically retried because they may have side effects.
+ *
+ * **Important:** policies don't gate actions — `auth: "user"` (the
+ * default) is the only thing protecting an action from anonymous calls.
+ * An action that charges Stripe, hits a private API, or reads a
+ * secret will respond happily to anonymous POSTs unless this gate
+ * fires. Pick `auth: "public"` explicitly only when the endpoint is
+ * meant to be open (a webhook receiver, a public form submit, …).
+ *
+ * @example
+ * ```typescript
+ * export default action({
+ *   args: { lotId: v.string() },
+ *   async handler(ctx, args) {
+ *     const lot = await ctx.runQuery("lotDetails", { lotId: args.lotId });
+ *     await fetch("https://api.sendgrid.com/...", { ... });
+ *     await ctx.runMutation("markNotified", { lotId: args.lotId });
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // GitHub webhook receiver — public because GitHub doesn't sign
+ * // in, the handler verifies the signature itself, then optionally
+ * // elevates.
+ * export default action({
+ *   auth: "public",
+ *   async handler(ctx) {
+ *     const ok = verifyGithubSignature(secret, ctx.request!.rawBody, sig);
+ *     if (!ok) throw ctx.error("INVALID_SIGNATURE", "bad sig");
+ *     await ctx.auth.elevate({ admin: true, reason: "github webhook hmac" });
+ *     // …
+ *   },
+ * });
+ * ```
+ */
+export declare function action<TArgs = Record<string, unknown>, TReturn = unknown>(def: ActionDefRequired<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
+export declare function action<TArgs = Record<string, unknown>, TReturn = unknown>(def: ActionDefOptional<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @pylonsync/functions — TypeScript function definitions for pylon.
+ *
+ * This is the developer-facing API. App developers import from here
+ * to define queries, mutations, and actions.
+ *
+ * @example
+ * ```typescript
+ * import { mutation, v } from "@pylonsync/functions";
+ *
+ * export default mutation({
+ *   args: { lotId: v.string(), amount: v.number() },
+ *   async handler(ctx, args) {
+ *     const lot = await ctx.db.get("Lot", args.lotId);
+ *     // ...
+ *   },
+ * });
+ * ```
+ */
+export { query, mutation, action } from "./define";
+export { v } from "./validators";
+export { resetDb, installTestIsolation } from "./testing";
+export { slugifyName, availableSlug } from "./slugify";
+export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, RequireMember, RequireMemberOptions, MemberRow, } from "./types";

package/dist/member.d.ts

@@ -0,0 +1,8 @@
+import type { RequireMember } from "./types";
+/**
+ * Build `ctx.requireMember(orgId, opts)` bound to a membership `read`. Errors
+ * carry `.code` (UNAUTHENTICATED / MISSING_ORG / FORBIDDEN) the same way
+ * `ctx.error` does — self-contained so it also works on the query ctx, which
+ * has no `ctx.error`.
+ */
+export declare function makeRequireMember(userId: string | null | undefined, read: (entity: string, filter: Record<string, unknown>) => Promise<any[]>): RequireMember;

package/dist/runtime.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Function runtime — the Bun process that loads and executes TypeScript functions.
+ *
+ * Protocol: NDJSON over stdin/stdout.
+ *
+ * Usage:
+ *   bun run packages/functions/src/runtime.ts ./functions
+ *
+ * Design:
+ * - A single reader consumes lines from stdin and dispatches by message type.
+ * - Incoming `call` messages launch a handler.
+ * - Incoming `result` messages resolve a pending RPC keyed by call_id.
+ * - Each call's handler has at most ONE outstanding RPC at a time (it awaits
+ *   each ctx.db / ctx.scheduler / ctx.runMutation call), so the map never
+ *   needs to queue multiple RPCs per call_id.
+ */
+import type { DbReader, DbWriter } from "./types";
+export declare function buildDbReader(callId: string): DbReader;
+export declare function buildDbWriter(callId: string): DbWriter;

package/dist/slugify.d.ts

@@ -0,0 +1,49 @@
+import type { DbReader, DbWriter } from "./types";
+/**
+ * Pure: turn a human name into a URL-safe base slug. Doesn't check
+ * uniqueness — combine with `availableSlug` for that.
+ *
+ * Rules:
+ *   - lowercase
+ *   - non-alphanumeric runs become single dashes
+ *   - trim leading/trailing dashes
+ *   - max 40 chars (so a numeric suffix can land within typical
+ *     50-char schema constraints)
+ *   - empty result (e.g. emoji-only name) → `fallback`
+ *
+ * @param name    The user-typed display name to slugify.
+ * @param fallback Replacement when the slug strips to empty. Default: "x".
+ */
+export declare function slugifyName(name: string, fallback?: string): string;
+/**
+ * Find the first slug that's available in the named entity's `field`
+ * column. Tries `base`, then `base-2`, `base-3`, …, then a 6-char
+ * random suffix as a final fallback.
+ *
+ * Reserved slugs (operational subdomain names, brand-protected words)
+ * can be passed via `reserved`; matches are skipped.
+ *
+ * Caller still wraps the eventual insert in try/catch — TOCTOU is
+ * always possible with this kind of "check then write" probe, and
+ * the framework's UNIQUE index is the actual source of truth. The
+ * helper just minimises the number of avoidable retries.
+ *
+ * @example
+ * ```ts
+ * const slug = await availableSlug(ctx.db, {
+ *   entity: "Workspace",
+ *   field: "slug",
+ *   name: args.name,
+ *   reserved: RESERVED_SUBDOMAINS,
+ * });
+ * await ctx.db.insert("Workspace", { slug, ... });
+ * ```
+ */
+export declare function availableSlug(db: DbReader | DbWriter, options: {
+    entity: string;
+    field?: string;
+    name: string;
+    reserved?: ReadonlySet<string> | readonly string[];
+    /** Max numeric suffix to try before falling back to random. Default: 50. */
+    maxNumericTries?: number;
+}): Promise<string>;

package/dist/ssr-client-boundary.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Resolve the nearest boundary module (`<dir>/not-found` or `<dir>/error`)
+ * for a route by walking its component path up to the app root, returning the
+ * first manifest route key that exists. Nearest ancestor wins — the same model
+ * the server's `findBoundary` uses, but driven off the client build manifest's
+ * route keys so the client runtime needs no extra server round-trip.
+ *
+ * `component` is a cwd-relative path with "/" separators and no extension
+ * (e.g. "web/app/dashboard/orgs/[slug]/page"); `routeKeys` is
+ * `Object.keys(manifest.routes)`.
+ */
+export declare function nearestBoundaryComponent(component: string, fileName: "not-found" | "error", routeKeys: Iterable<string>): string | null;
+/** Runtime internals the boundary needs, injected so the module stays
+ *  browser-safe AND unit-testable. */
+export interface BoundaryDeps {
+    /** Resolve the client build manifest (`{ routes: {...} }`). */
+    loadManifest: () => Promise<{
+        routes?: Record<string, unknown>;
+    } | null>;
+    /** Dynamically load a route entry → its Page + Layout chain. */
+    loadRouteEntry: (component: string) => Promise<{
+        Page: any;
+        Layouts: any[];
+    }>;
+    /** Client-side navigation — used by an error boundary's reset(). */
+    navigate: (href: string, opts?: {
+        replace?: boolean;
+    }) => void;
+    /** Wrap a Page in its Layout chain with props (the runtime's buildTree). */
+    buildTree: (Page: any, Layouts: any[], props: any) => any;
+    /** The props the active page was rendered with (auth, serverData, …). */
+    getPageProps: () => any;
+    /** Current same-origin href, for an error boundary's reset() re-navigation. */
+    getResetHref: () => string;
+}
+/**
+ * Build the client error / not-found boundary against the runtime's internals.
+ * Returns `withBoundary(tree, component, navEpoch)` — the transparent root
+ * wrapper the runtime puts around every page — plus `PylonBoundary` for tests.
+ *
+ * Behavior: a `notFound()` (digest "PYLON_NOT_FOUND") or any error thrown
+ * during a descendant's render is caught; the nearest not-found.tsx / error.tsx
+ * for the active route is resolved from the manifest, loaded, and rendered in
+ * its own layout chain WITH the page's props (so an auth-guarding layout sees
+ * the real auth and doesn't redirect away). Resets on navigation via a changing
+ * `navEpoch` prop — not a key — so layouts keep their state across nav.
+ */
+export declare function createPylonBoundary(deps: BoundaryDeps): {
+    withBoundary: (tree: any, component: string, navEpoch: number) => import("react").CElement<any, {
+        componentDidUpdate(prev: any): void;
+        componentDidCatch(err: any): void;
+        render(): any;
+        context: unknown;
+        setState<K extends "err">(state: {
+            err: any;
+        } | ((prevState: Readonly<{
+            err: any;
+        }>, props: Readonly<any>) => {
+            err: any;
+        } | Pick<{
+            err: any;
+        }, K> | null) | Pick<{
+            err: any;
+        }, K> | null, callback?: (() => void) | undefined): void;
+        forceUpdate(callback?: (() => void) | undefined): void;
+        readonly props: Readonly<any>;
+        state: Readonly<{
+            err: any;
+        }>;
+        componentDidMount?(): void;
+        shouldComponentUpdate?(nextProps: Readonly<any>, nextState: Readonly<{
+            err: any;
+        }>, nextContext: any): boolean;
+        componentWillUnmount?(): void;
+        getSnapshotBeforeUpdate?(prevProps: Readonly<any>, prevState: Readonly<{
+            err: any;
+        }>): any;
+        componentWillMount?(): void;
+        UNSAFE_componentWillMount?(): void;
+        componentWillReceiveProps?(nextProps: Readonly<any>, nextContext: any): void;
+        UNSAFE_componentWillReceiveProps?(nextProps: Readonly<any>, nextContext: any): void;
+        componentWillUpdate?(nextProps: Readonly<any>, nextState: Readonly<{
+            err: any;
+        }>, nextContext: any): void;
+        UNSAFE_componentWillUpdate?(nextProps: Readonly<any>, nextState: Readonly<{
+            err: any;
+        }>, nextContext: any): void;
+    }>;
+    PylonBoundary: {
+        new (p: any): {
+            componentDidUpdate(prev: any): void;
+            componentDidCatch(err: any): void;
+            render(): any;
+            context: unknown;
+            setState<K extends "err">(state: {
+                err: any;
+            } | ((prevState: Readonly<{
+                err: any;
+            }>, props: Readonly<any>) => {
+                err: any;
+            } | Pick<{
+                err: any;
+            }, K> | null) | Pick<{
+                err: any;
+            }, K> | null, callback?: (() => void) | undefined): void;
+            forceUpdate(callback?: (() => void) | undefined): void;
+            readonly props: Readonly<any>;
+            state: Readonly<{
+                err: any;
+            }>;
+            componentDidMount?(): void;
+            shouldComponentUpdate?(nextProps: Readonly<any>, nextState: Readonly<{
+                err: any;
+            }>, nextContext: any): boolean;
+            componentWillUnmount?(): void;
+            getSnapshotBeforeUpdate?(prevProps: Readonly<any>, prevState: Readonly<{
+                err: any;
+            }>): any;
+            componentWillMount?(): void;
+            UNSAFE_componentWillMount?(): void;
+            componentWillReceiveProps?(nextProps: Readonly<any>, nextContext: any): void;
+            UNSAFE_componentWillReceiveProps?(nextProps: Readonly<any>, nextContext: any): void;
+            componentWillUpdate?(nextProps: Readonly<any>, nextState: Readonly<{
+                err: any;
+            }>, nextContext: any): void;
+            UNSAFE_componentWillUpdate?(nextProps: Readonly<any>, nextState: Readonly<{
+                err: any;
+            }>, nextContext: any): void;
+        };
+        getDerivedStateFromError(err: any): {
+            err: any;
+        };
+        contextType?: import("react").Context<any> | undefined;
+        propTypes?: any;
+    };
+};

package/dist/ssr-client-bundler.d.ts

@@ -0,0 +1,79 @@
+import { type ManifestFonts } from "./ssr-fonts";
+type Send = (msg: Record<string, unknown>) => void;
+interface BundleClientMessage {
+    type: "bundle_client";
+    call_id: string;
+    /**
+     * Project-relative directory holding the route tree
+     * (`<app_dir>/**​/page.tsx`). Defaults to `"app"` when the host
+     * doesn't send it (older hosts, or the default single-`app/`
+     * layout). The full-stack app that namespaces its frontend under a
+     * subdir — e.g. `web/app` via `discoverAppRoutes({appDir:"web/app"})`
+     * — sends the same dir here so the client bundler and the SSR
+     * manifest agree on where the routes live.
+     */
+    app_dir?: string;
+}
+/**
+ * Manifest schema. One entry per route, indexed by the same
+ * project-relative component path the SSR side passes through.
+ * `file` is the entry chunk, `imports` is the transitive set of
+ * shared chunks the browser needs to load BEFORE the entry runs
+ * — that's the modulepreload list.
+ *
+ * Paths in the manifest are relative to `.pylon/client-build/` so
+ * the Rust host can serve them under `/_pylon/build/<path>` with
+ * no rewriting.
+ */
+export interface PylonBundleManifest {
+    /** Build identity — bumps every successful build. */
+    build_id: string;
+    /** Output root, relative to cwd (always `.pylon/client-build`). */
+    outdir: string;
+    /** Public URL prefix the Rust host serves chunks under. */
+    public_prefix: string;
+    /** routeComponentPath → file + imports for that route. */
+    routes: Record<string, {
+        /** Per-route entry file, relative to outdir. */
+        file: string;
+        /** Transitive shared chunks to modulepreload, relative to outdir. */
+        imports: string[];
+        /** CSS chunks (Phase 1.5f). */
+        css: string[];
+    }>;
+    /** Self-hosted fonts (next/font parity): structured `@font-face`s + the
+     *  `:root` CSS variables + the woff2 files to preload. Global (route-
+     *  independent); rendered into every SSR `<head>` against `public_prefix`.
+     *  Absent when the app declares no `font({...})`. */
+    fonts?: ManifestFonts;
+}
+/** Result of an in-process build — same shape the protocol returns. */
+export interface BuildOutput {
+    manifestPath: string;
+    outdir: string;
+}
+/**
+ * Run the bundler in-process and return the manifest path + outdir.
+ * Used from `handleBundleClient` (protocol RPC path from Rust) AND
+ * from `getManifest` (in-process SSR path).
+ */
+export declare function buildClientBundle(appDirRel?: string): Promise<BuildOutput>;
+/**
+ * Return the bundle manifest. If a fresh manifest exists on disk,
+ * use it (caching parse output across requests). Otherwise build
+ * the bundle in-process (deduped by `buildClientBundle`) and read.
+ *
+ * Called from `ssr-runtime.ts` per-request, so the disk-stat fast
+ * path matters. Bun's `fs.statSync` is a ~5µs syscall; cheap enough
+ * that we don't gate it on a flag.
+ */
+export declare function getManifest(): Promise<PylonBundleManifest>;
+/**
+ * Protocol entry. Builds + responds. Rust calls this via the
+ * `bundle_client` RPC; on success the response carries both
+ * the manifest path (so Rust can load it if it wants, today it
+ * doesn't) and the outdir (so `/_pylon/build/<rel>` serves the
+ * right tree).
+ */
+export declare function handleBundleClient(msg: BundleClientMessage, send: Send): Promise<void>;
+export {};

package/dist/ssr-fonts.d.ts

@@ -0,0 +1,94 @@
+/** One `@font-face` rule. A real face carries `src` (woff2 files); a generated
+ *  fallback face carries `local` + the size-adjust/override metrics instead. */
+export interface FontFace {
+    /** `font-family` — the real family, or `"<Family> Fallback"` for the
+     *  size-adjusted fallback face. */
+    family: string;
+    /** outdir-relative woff2 filenames (real face). Empty for a fallback face. */
+    src: string[];
+    /** `local("...")` source for a size-adjusted fallback face, e.g. `"Arial"`. */
+    local?: string;
+    weight?: string;
+    style?: string;
+    display?: string;
+    unicodeRange?: string;
+    /** `size-adjust` percentage (fallback face only), e.g. `"107.40%"`. */
+    sizeAdjust?: string;
+    /** `ascent-override` percentage (fallback face only). */
+    ascentOverride?: string;
+    /** `descent-override` percentage (fallback face only). */
+    descentOverride?: string;
+    /** `line-gap-override` percentage (fallback face only). */
+    lineGapOverride?: string;
+}
+/** The bundle manifest's `fonts` block: structured faces + CSS variables +
+ *  the woff2 files to `<link rel=preload>`. Rendered into every SSR `<head>`. */
+export interface ManifestFonts {
+    faces: FontFace[];
+    /** CSS custom property → font-family stack, e.g.
+     *  `{"--font-sans": '"Geist", "Geist Fallback", sans-serif'}`. */
+    variables: Record<string, string>;
+    /** outdir-relative woff2 filenames to preload. */
+    preload: string[];
+}
+interface SfntMetrics {
+    unitsPerEm: number;
+    ascent: number;
+    descent: number;
+    lineGap: number;
+    xAvgCharWidth: number;
+}
+/** A `ManifestFont` as it appears in `pylon.manifest.json` (snake_case wire
+ *  shape — see the SDK `font()` helper). */
+interface ManifestFontInput {
+    family: string;
+    variable: string;
+    weights?: string[];
+    styles?: string[];
+    subsets?: string[];
+    display?: string;
+    preload?: boolean;
+    fallback?: string[];
+    adjust_font_fallback?: boolean;
+}
+/** Decode the line-box metrics from a font buffer (woff2 or raw sfnt). Returns
+ *  null when the format/tables can't be read — callers degrade gracefully. */
+export declare function decodeFontMetrics(buf: Uint8Array): SfntMetrics | null;
+/** Compute the size-adjusted fallback `@font-face` for a family. The web font's
+ *  metrics, divided by the size-adjust factor, become the overrides — so the
+ *  local fallback occupies the same line box + average advance as the web font
+ *  will, eliminating the swap-in shift. */
+export declare function computeFallbackFace(metrics: SfntMetrics, family: string, category: "sans-serif" | "serif"): FontFace;
+/** Render the structured faces + `:root` variables into a CSS string. woff2 URLs
+ *  are resolved against `prefix` (the live `public_prefix`) so they match
+ *  wherever the assets are served (same-origin or CDN). */
+export declare function renderFontFaceCss(fonts: ManifestFonts, prefix: string): string;
+interface FontSpec {
+    family: string;
+    weights: string[];
+    styles: string[];
+    subsets: string[];
+    display: string;
+}
+interface FaceBlock {
+    subset: string;
+    style: string;
+    weight: string;
+    unicodeRange: string;
+    url: string;
+}
+/** Build the Google Fonts CSS2 API URL for a spec. */
+export declare function buildGoogleFontsUrl(spec: FontSpec): string;
+/** Parse a Google Fonts CSS2 response into per-subset face blocks, keeping only
+ *  the requested subsets. Each `@font-face` is preceded by a subset comment in
+ *  the API output. */
+export declare function parseGoogleFontsCss(css: string, subsets: string[]): FaceBlock[];
+/** Build all declared fonts: fetch + self-host + metrics + structured faces.
+ *  Network/parse failures for a single family degrade to a variable-only entry
+ *  (so `var(--font-x)` still resolves to the fallback stack) rather than killing
+ *  the build. Returns null when nothing was produced. */
+export declare function buildFonts(fs: any, path: any, cwd: string, outdir: string, fonts: ManifestFontInput[]): Promise<ManifestFonts | null>;
+/** Read the `fonts` array from the app's `pylon.manifest.json` (written next to
+ *  app.ts). Returns [] when absent/unreadable. */
+export declare function readManifestFonts(fs: any, path: any, cwd: string): ManifestFontInput[];
+export {};

package/dist/ssr-form-runtime.d.ts

@@ -0,0 +1,33 @@
+/** Matches HandleFormMessage in crates/functions/src/protocol.rs. */
+export interface HandleFormMessage {
+    type: "handle_form";
+    call_id: string;
+    component: string;
+    route_path: string;
+    method: string;
+    url: string;
+    params: Record<string, string>;
+    search_params: Record<string, string>;
+    form: Record<string, string | string[]>;
+    headers: Record<string, string>;
+    cookies: Record<string, string>;
+    auth: {
+        user_id: string | null;
+        is_admin: boolean;
+        tenant_id: string | null;
+        roles: string[];
+    };
+}
+type Send = (msg: Record<string, unknown>) => void;
+/** Parsed form fields. Mirrors URLSearchParams get/getAll/has semantics. */
+export interface FormFields {
+    /** First value for `name`, or null. */
+    get(name: string): string | null;
+    /** All values for `name` (empty array if none). */
+    getAll(name: string): string[];
+    has(name: string): boolean;
+    /** Raw map: name → value | values. */
+    readonly fields: Record<string, string | string[]>;
+}
+export declare function handleForm(msg: HandleFormMessage, send: Send): Promise<void>;
+export {};