@voltro/web 0.1.0

package/dist/ssr.d.ts

@@ -0,0 +1,322 @@
+import { ComponentType } from 'react';
+import { PipeableStream } from 'react-dom/server';
+import { ReactNode } from 'react';
+
+declare interface ErrorBoundaryProps {
+    readonly error: unknown;
+    readonly reset: () => void;
+}
+
+/**
+ * How the client-side JS hydrates a server-rendered page.
+ *
+ *   - 'full'    — Hydrate the entire page tree as one React root.
+ *                 Default for `'spa'` pages and the safe default for
+ *                 `'static'` pages that haven't been thought through.
+ *                 Subscriptions + interactivity work everywhere.
+ *   - 'islands' — Skip the full-tree hydration. The client runtime
+ *                 only hydrates `<div data-voltro-island>` markers
+ *                 emitted by `island()`. Other parts of the page stay
+ *                 pure static HTML with no React lifecycle running.
+ *                 Best perf for content-heavy pages with isolated
+ *                 interactive zones.
+ *
+ * Defaults to `'full'` when not specified.
+ */
+declare type InteractiveMode = 'full' | 'islands' | 'none';
+
+declare interface LoaderContext {
+    readonly params: Readonly<Record<string, string>>;
+    readonly pathname: string;
+    /** Aborted when the user navigates away before the loader resolves. */
+    readonly signal: AbortSignal;
+    /** Request headers when the loader runs server-side via `voltro
+     *  start`. Lowercased keys. Empty `{}` for client-side loader
+     *  invocations (browser-fetch goes through the rpc layer, not the
+     *  loader). Use this for tenant resolution, auth headers, etc.
+     *  until the auth slice ships a typed Subject. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Server-side one-shot rpc fetch. Invokes any backend rpc (queries
+     *  included — the FIRST snapshot of a streaming query is resolved and
+     *  returned) over the api's HTTP rpc surface (`POST /rpc`), forwarding
+     *  the request's `cookie` header so the api resolves the same Subject +
+     *  tenant the WS path would. Bound to the app's single / first api.
+     *
+     *  Present ONLY when the loader runs server-side (`voltro start` /
+     *  `voltro dev` SSR). `undefined` for client-side loader invocations —
+     *  in the browser, use `useSubscription` in the component for live data
+     *  instead; the loader's `query` is for SSR first-paint + `meta`. */
+    readonly query?: <T = unknown>(tag: string, input?: Record<string, unknown>) => Promise<T>;
+}
+
+declare type LoaderFn<T = unknown> = (ctx: LoaderContext) => Promise<T> | T;
+
+declare interface PageDescriptor<TLoaderData = unknown> {
+    /** URL pattern, e.g. `/`, `/about`, `/users/[id]`, `/docs/[...slug]`. */
+    readonly pattern: string;
+    /** The page component. Present on eager routes; on a LAZY route (see
+     *  `load`) it's filled by the Router once the page chunk has loaded. */
+    readonly Component?: ComponentType | undefined;
+    /** LAZY route: a thunk that dynamically imports the page module. When set,
+     *  the page chunk is fetched only when this route first matches, so the
+     *  initial bundle never imports every page. The Router resolves
+     *  `Component` / `loader` / `meta` / … from the loaded module; the layout
+     *  `chain` stays eager. */
+    readonly load?: (() => Promise<Record<string, unknown>>) | undefined;
+    /** Static meta, or a function of `{ params, loaderData, locale }` —
+     *  so a document title can read what the page loader fetched (the
+     *  dynamic metadata case) AND can localise per-locale at SSG time
+     *  for URL-prefix i18n routing. `loaderData` is the page loader's
+     *  result; `locale` is the active i18n locale during pre-render
+     *  (driven by `params.locale` for `[locale]/...` routes, falling
+     *  back to the app's defaultLocale). On the client, `locale` is
+     *  the URL-derived locale when the route is locale-prefixed,
+     *  otherwise the framework's resolved locale (cookie / Accept-
+     *  Language / default). */
+    readonly meta?: PageMeta | ((ctx: {
+        readonly params: Readonly<Record<string, string>>;
+        readonly loaderData: unknown;
+        readonly locale: string;
+    }) => PageMeta) | undefined;
+    /** Async data preload; result available via useLoaderData<T>(). */
+    readonly loader?: LoaderFn<TLoaderData> | undefined;
+    /** Catches render + loader errors for THIS leaf. Tighter scope than `chain[*].Error`. */
+    readonly ErrorBoundary?: ComponentType<ErrorBoundaryProps> | undefined;
+    /** Shown while the loader is in flight (first navigation to the route). */
+    readonly Pending?: ComponentType | undefined;
+    /**
+     * Outer-to-inner layer chain. Each segment maps to one directory level
+     * (or route group) on the way from the pages root down to this leaf.
+     * Codegen produces this from the discovery walk; user code rarely
+     * writes it by hand.
+     */
+    readonly chain?: ReadonlyArray<RouteSegment> | undefined;
+    /** How the page's HTML is produced. Defaults to 'static' so pages
+     *  pre-render by default — SEO + first-paint speed are wins users
+     *  pay nothing for. Opt out with `'spa'` for pages that need a
+     *  per-request render. */
+    readonly renderMode?: RenderMode | undefined;
+    /** How the page's client-side JS hydrates. Defaults to `'full'`
+     *  (whole tree). Pages designed around the islands pattern should
+     *  set this to `'islands'` so only marked interactive zones
+     *  hydrate; the rest stays pure static HTML. */
+    readonly interactive?: InteractiveMode | undefined;
+}
+
+declare interface PageMeta {
+    readonly title?: string;
+    readonly description?: string;
+    /** Canonical URL for this page. Emitted as `<link rel="canonical">`.
+     *  Relative paths are accepted — search engines resolve them
+     *  against the document's base URL. Use this on duplicated routes
+     *  (locale variants, alternate URL forms) to declare the preferred
+     *  one indexable URL. */
+    readonly canonical?: string;
+    /** Arbitrary additional meta tags. `name` OR `property` is required. */
+    readonly tags?: ReadonlyArray<{
+        readonly name?: string;
+        readonly property?: string;
+        readonly content: string;
+    }>;
+    /** Arbitrary additional `<link>` tags. Use for `alternate` hreflang,
+     *  prev/next pagination, RSS feeds, manifest, etc. (For the common
+     *  canonical case, prefer the dedicated `canonical` field above.) */
+    readonly links?: ReadonlyArray<{
+        readonly rel: string;
+        readonly href: string;
+        readonly hreflang?: string;
+        readonly type?: string;
+        readonly title?: string;
+    }>;
+    /** JSON-LD structured-data payloads. Each entry is emitted as a
+     *  separate `<script type="application/ld+json">` so search engines
+     *  and LLM crawlers can pick up rich metadata (Article, Product,
+     *  SoftwareApplication, BreadcrumbList, FAQPage, etc.). Anything
+     *  JSON-serialisable is accepted; `@context` + `@type` are
+     *  authored, not synthesised. */
+    readonly jsonLd?: ReadonlyArray<Record<string, unknown>>;
+}
+
+export declare const parseCookieHeader: (raw: string | undefined) => Record<string, string>;
+
+/**
+ * Helper for the build pipeline: stringify the resolved meta into a
+ * `<head>`-ready HTML fragment. Returns an empty string when no meta
+ * is set so the caller can blindly inject the result.
+ */
+export declare const renderMetaToHtml: (meta: PageMeta | null) => string;
+
+/**
+ * How a page's HTML is produced.
+ *
+ *   - 'static'  — Pre-rendered to flat HTML at build time. Default.
+ *                 Shipped as `dist/<route>/index.html`. JS bundle
+ *                 still loads to hydrate islands + handle SPA-style
+ *                 navigation, but the first paint is instant + SEO
+ *                 friendly. Loaders MUST be side-effect-free + must
+ *                 not require per-request context (subject, headers).
+ *   - 'spa'     — Client-only rendering. No HTML pre-render; the
+ *                 shipped HTML is a shell that mounts on the
+ *                 client. Useful for pages that genuinely need a
+ *                 fresh client render every load (most reactive
+ *                 dashboards).
+ *
+ *   - 'ssr'  — Rendered on every request, server-side, via `voltro
+ *               start`. Loaders run per request with access to
+ *               `headers` + `query` (the api HTTP rpc); the resolved
+ *               HTML is sent fresh each time. Use for personalised /
+ *               tenant-scoped first paint.
+ *   - 'isr'  — Like 'ssr' on the first request, then cached and
+ *               revalidated in the background on a TTL.
+ */
+declare type RenderMode = 'static' | 'spa' | 'ssr' | 'isr';
+
+export declare interface RenderPageOptions {
+    /** Descriptor produced by codegen (`pageRoute(...)`). */
+    readonly descriptor: PageDescriptor;
+    /** URL pattern's resolved params. `{}` for static, no-param routes. */
+    readonly params: Readonly<Record<string, string>>;
+    /** Pathname this render resolves under. Used by `useLocation()` on
+     *  the server side. */
+    readonly pathname: string;
+    /** Page (leaf) loader data — pre-resolved by the caller. The build /
+     *  SSR pipeline runs the descriptor's `loader` (if any) and passes the
+     *  result here; reachable via `useLoaderData()` inside the page. */
+    readonly loaderData: unknown;
+    /** Per-layout loader data, keyed by chain-segment index. The pipeline
+     *  runs each `chain[i].loader` and passes the results here; each layout
+     *  reads ITS own via `useLoaderData()`. Omit when no layout loaders. */
+    readonly segmentLoaderData?: Readonly<Record<number, unknown>>;
+    /** Request snapshot (cookies + headers) exposed to the rendered tree
+     *  via `useServerRequest()`. Optional: omit on builds (static
+     *  prerender) where no per-request data exists; provide on
+     *  per-request SSR so consumers can resolve cookie-driven preferences
+     *  like locale or theme. */
+    readonly requestContext?: ServerRequestContextValue;
+    /** Outer wrapper to apply around the rendered tree. The build and
+     *  the SSR runtime pass an `<I18nProvider>` wrapper here when the
+     *  consumer app has `locales` configured — without it, any page
+     *  calling `useT()` would crash at render time ("Could not find
+     *  required `intl` object"). The wrapper is generic on purpose:
+     *  any cross-cutting provider (i18n, theme, feature-flag context)
+     *  rides this slot so `@voltro/web` stays free of optional deps. */
+    readonly outerWrap?: (children: ReactNode) => ReactNode;
+    /** Active locale for this render. Drives meta resolution so a page's
+     *  `meta` function can localise title / description / canonical /
+     *  hreflang per locale. The build passes `params.locale ?? defaultLocale`
+     *  so locale-prefixed routes (`[locale]/...`) get their per-locale
+     *  catalog at meta-resolve time. Optional: when absent, page
+     *  `meta(ctx)` callbacks see `ctx.locale = 'en'` as a safe default. */
+    readonly locale?: string;
+}
+
+export declare interface RenderPageResult {
+    /** HTML for the page body — goes inside `<div id="root">…</div>`. */
+    readonly html: string;
+    /** Resolved page meta (after running the descriptor's `meta`
+     *  function with `params` if present). Caller renders this into
+     *  the document head. */
+    readonly meta: PageMeta | null;
+}
+
+export declare interface RenderPageStreamOptions extends RenderPageOptions {
+    /** Called once React commits the shell (all Suspense boundaries that
+     *  weren't deferred have resolved). Flush the `<head>` (with `meta`) +
+     *  opening `<body>` here, then pipe the returned stream into the response.
+     *  The build pipeline uses this to send bytes before the whole tree is
+     *  ready — the streaming-SSR win over `renderToString`. */
+    readonly onShellReady?: () => void;
+    /** Called if the shell itself fails to render (before any bytes flushed) —
+     *  the pipeline should fall back to an error page / a 500. */
+    readonly onShellError?: (error: unknown) => void;
+    /** Called when the ENTIRE tree (incl. deferred Suspense content) has
+     *  streamed. Close the response's trailing `</body></html>` here. */
+    readonly onAllReady?: () => void;
+    /** Bootstrap `<script>` module URLs injected by React at the end of the
+     *  shell — the client bundle that hydrates the streamed HTML. */
+    readonly bootstrapModules?: ReadonlyArray<string>;
+}
+
+export declare interface RenderPageStreamResult {
+    /** The React pipeable stream. `pipe(res)` into a Node writable to flush the
+     *  page body; `abort()` to cancel a slow render. */
+    readonly stream: PipeableStream;
+    /** Resolved page meta — available synchronously (meta runs before render),
+     *  so the caller can write `<head>` in `onShellReady` before piping. */
+    readonly meta: PageMeta | null;
+}
+
+/**
+ * Render a page to an HTML string using its layout chain + loader data. The
+ * returned `html` is the body fragment — the caller composes the surrounding
+ * document. Renders synchronously via `renderToString`; for the streaming
+ * path (flush the shell before the whole tree is ready) use
+ * {@link renderPageToStream}.
+ */
+export declare const renderPageToHtml: (options: RenderPageOptions) => RenderPageResult;
+
+/**
+ * Streaming SSR — the richer path alongside {@link renderPageToHtml}. Renders
+ * the page via React's `renderToPipeableStream` so the server can flush the
+ * shell (and each Suspense boundary as it resolves) instead of buffering the
+ * whole document into one string. Same tree, same providers, same meta as the
+ * sync path; the difference is time-to-first-byte and native Suspense
+ * streaming.
+ *
+ * The caller drives the response: write the doctype + `<head>` (using the
+ * synchronously-returned `meta`) + opening `<body><div id="root">` in
+ * `onShellReady`, `stream.pipe(res)`, then close the document in `onAllReady`.
+ */
+export declare const renderPageToStream: (options: RenderPageStreamOptions) => RenderPageStreamResult;
+
+/**
+ * One layer in a page's nesting chain. Each represents a directory level
+ * in the file-convention layout (or a route group).
+ *
+ * Layouts wrap their children — outer layers wrap inner ones. Errors are
+ * caught by the deepest layer with an `Error` component; if none, the
+ * error bubbles up the chain. NotFound applies when an URL is under this
+ * layer's scope but no concrete page matches.
+ *
+ * The chain persists across navigation within its scope — React preserves
+ * the layout component instances because their position in the tree is
+ * stable for any leaf within that subtree.
+ */
+declare interface RouteSegment {
+    /** Outer-vs-inner ordering label (debug only). */
+    readonly id?: string | undefined;
+    readonly Layout?: ComponentType<{
+        children: ReactNode;
+    }> | undefined;
+    readonly Error?: ComponentType<ErrorBoundaryProps> | undefined;
+    readonly Pending?: ComponentType | undefined;
+    readonly NotFound?: ComponentType | undefined;
+    /** Async data preload for THIS layout level. Runs in parallel with the
+     *  page loader (and the other layouts') before mount; the result is
+     *  reachable via `useLoaderData<T>()` from INSIDE this layout (each
+     *  level sees its own loader's data). A `layout.tsx` exports it like a
+     *  page does — codegen wires it onto the segment. Server-side it
+     *  receives request `headers` (session/tenant resolution). */
+    readonly loader?: LoaderFn | undefined;
+}
+
+/**
+ * Serialise loader data into a `<script>` payload safe to embed in
+ * HTML. The result is wrapped in `<script type="application/json"
+ * id="__voltro_state__">` by the caller; here we just produce the
+ * JSON body with `</` sequences escaped (the well-known SSR XSS
+ * vector).
+ */
+export declare const serialiseStateForInlining: (state: unknown) => string;
+
+declare interface ServerRequestContextValue {
+    readonly cookies: Readonly<Record<string, string>>;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Raw request URL as it came off the wire (path + query). Useful
+     *  for SSR pages that need to read `?q=…` style search params
+     *  without touching anything client-only. Empty string for build-
+     *  time SSG renders where there is no incoming request. */
+    readonly url: string;
+}
+
+export { }

package/dist/ssr.js

@@ -0,0 +1,76 @@
+import { c as e, d as t, r as n, t as r, x as i } from "./serverContext-D5-Dmh8d.js";
+import { createElement as a } from "react";
+import { renderToPipeableStream as o, renderToString as s } from "react-dom/server";
+//#region src/ssr.tsx
+var c = (t, n, r, i) => {
+	let o = a(e.Provider, { value: r }, a(t));
+	if (!n) return o;
+	for (let t = n.length - 1; t >= 0; t--) {
+		let r = n[t];
+		if (r.Layout) {
+			let n = r.Layout;
+			o = a(e.Provider, { value: i(t) }, a(n, { children: o }));
+		}
+	}
+	return o;
+}, l = (e) => {
+	let { descriptor: n, params: o, pathname: s, loaderData: l, segmentLoaderData: u, requestContext: d, outerWrap: f, locale: p } = e, m = i(n.meta, o, l, p), h = {
+		pathname: s,
+		search: "",
+		params: o,
+		loaderData: l,
+		navigate: () => {
+			throw Error("navigate() is not supported during server-side rendering. Trigger navigations on the client only.");
+		},
+		prefetch: () => {},
+		registerBlocker: () => () => {},
+		blocked: null
+	}, g = n.Component;
+	if (!g) throw Error(`SSR received a descriptor with no Component for "${s}". Lazy page routes are a client-only optimization and must not be used on the server.`);
+	let _ = a(t.Provider, { value: h }, c(g, n.chain, l, (e) => u?.[e]));
+	return d && (_ = a(r.Provider, { value: d }, _)), f && (_ = f(_)), {
+		tree: _,
+		meta: m
+	};
+}, u = (e) => {
+	let { tree: t, meta: n } = l(e);
+	return {
+		html: s(t),
+		meta: n
+	};
+}, d = (e) => {
+	let { tree: t, meta: n } = l(e);
+	return {
+		stream: o(t, {
+			...e.bootstrapModules ? { bootstrapModules: [...e.bootstrapModules] } : {},
+			...e.onShellReady ? { onShellReady: e.onShellReady } : {},
+			...e.onShellError ? { onShellError: e.onShellError } : {},
+			...e.onAllReady ? { onAllReady: e.onAllReady } : {}
+		}),
+		meta: n
+	};
+}, f = (e) => {
+	if (!e) return "";
+	let t = [];
+	if (typeof e.title == "string" && t.push(`<title>${m(e.title)}</title>`), e.description && t.push(`<meta name="description" content="${h(e.description)}" />`), e.canonical && t.push(`<link rel="canonical" href="${h(e.canonical)}" />`), e.tags) for (let n of e.tags) {
+		let e = n.name ? `name="${h(n.name)}"` : n.property ? `property="${h(n.property)}"` : "";
+		e && t.push(`<meta ${e} content="${h(n.content)}" />`);
+	}
+	if (e.links) for (let n of e.links) {
+		let e = [
+			`rel="${h(n.rel)}"`,
+			`href="${h(n.href)}"`,
+			n.hreflang ? `hreflang="${h(n.hreflang)}"` : "",
+			n.type ? `type="${h(n.type)}"` : "",
+			n.title ? `title="${h(n.title)}"` : ""
+		].filter(Boolean).join(" ");
+		t.push(`<link ${e} />`);
+	}
+	if (e.jsonLd) for (let n of e.jsonLd) {
+		let e = JSON.stringify(n).replace(/<\/(script)/gi, "<\\/$1").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+		t.push(`<script type="application/ld+json" data-voltro-page-jsonld>${e}<\/script>`);
+	}
+	return t.join("\n    ");
+}, p = (e) => JSON.stringify(e ?? null).replace(/</g, "\\u003c"), m = (e) => e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"), h = (e) => e.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+//#endregion
+export { n as parseCookieHeader, f as renderMetaToHtml, u as renderPageToHtml, d as renderPageToStream, p as serialiseStateForInlining };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@voltro/web",
+  "version": "0.1.0",
+  "description": "The Voltro web framework — file-based routing, render modes (SSR / SSG / islands), the page-export contract, data hooks, and the browser mount.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./mount": {
+      "types": "./dist/mount.d.ts",
+      "import": "./dist/mount.js",
+      "default": "./dist/mount.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js",
+      "default": "./dist/hooks.js"
+    },
+    "./runtime": {
+      "types": "./dist/frameworkBoot.d.ts",
+      "import": "./dist/frameworkBoot.js",
+      "default": "./dist/frameworkBoot.js"
+    },
+    "./ssr": {
+      "types": "./dist/ssr.d.ts",
+      "import": "./dist/ssr.js",
+      "default": "./dist/ssr.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/client": "0.1.0",
+    "@voltro/ui": "0.1.0"
+  },
+  "peerDependencies": {
+    "@effect/platform": "^0.96.2",
+    "@effect/rpc": "^0.75.1",
+    "effect": "^3.21.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}