@canmi/seam-server 0.4.18 → 0.5.27

package/dist/index.js

@@ -1,6 +1,6 @@
+import { validate } from "jtd";
 import { existsSync, readFileSync, watch } from "node:fs";
 import { extname, join } from "node:path";
-import { validate } from "jtd";
 import { escapeHtml, renderPage } from "@canmi/seam-engine";
 import { readFile } from "node:fs/promises";
 
@@ -141,24 +141,42 @@ const t = {
 };
 
 //#endregion
-//#region src/manifest/index.ts
-function buildManifest(definitions, channels) {
-	const mapped = {};
-	for (const [name, def] of Object.entries(definitions)) {
-		const entry = {
-			type: def.type === "subscription" ? "subscription" : def.type === "command" ? "command" : "query",
-			input: def.input._schema,
-			output: def.output._schema
-		};
-		if (def.error) entry.error = def.error._schema;
-		mapped[name] = entry;
-	}
-	const manifest = {
-		version: 1,
-		procedures: mapped
+//#region src/validation/index.ts
+function validateInput(schema, data) {
+	const errors = validate(schema, data, {
+		maxDepth: 32,
+		maxErrors: 10
+	});
+	return {
+		valid: errors.length === 0,
+		errors
 	};
-	if (channels && Object.keys(channels).length > 0) manifest.channels = channels;
-	return manifest;
+}
+function formatValidationErrors(errors) {
+	return errors.map((e) => {
+		return `${e.instancePath.length > 0 ? e.instancePath.join("/") : "(root)"} (schema: ${e.schemaPath.join("/")})`;
+	}).join("; ");
+}
+/** Walk a nested object along a key path, returning undefined if unreachable */
+function walkPath(obj, keys) {
+	let cur = obj;
+	for (const k of keys) {
+		if (cur === null || cur === void 0 || typeof cur !== "object") return void 0;
+		cur = cur[k];
+	}
+	return cur;
+}
+/** Extract structured details from JTD validation errors (best-effort) */
+function formatValidationDetails(errors, schema, data) {
+	return errors.map((e) => {
+		const detail = { path: "/" + e.instancePath.join("/") };
+		const schemaValue = walkPath(schema, e.schemaPath);
+		if (typeof schemaValue === "string") detail.expected = schemaValue;
+		const actualValue = walkPath(data, e.instancePath);
+		if (actualValue !== void 0) detail.actual = typeof actualValue;
+		else if (e.instancePath.length === 0) detail.actual = typeof data;
+		return detail;
+	});
 }
 
 //#endregion
@@ -174,57 +192,248 @@ const DEFAULT_STATUS = {
 var SeamError = class extends Error {
 	code;
 	status;
-	constructor(code, message, status) {
+	details;
+	constructor(code, message, status, details) {
 		super(message);
 		this.code = code;
 		this.status = status ?? DEFAULT_STATUS[code] ?? 500;
+		this.details = details;
 		this.name = "SeamError";
 	}
 	toJSON() {
+		const error = {
+			code: this.code,
+			message: this.message,
+			transient: false
+		};
+		if (this.details) error.details = this.details;
 		return {
 			ok: false,
-			error: {
-				code: this.code,
-				message: this.message,
-				transient: false
-			}
+			error
 		};
 	}
 };
 
 //#endregion
-//#region src/validation/index.ts
-function validateInput(schema, data) {
-	const errors = validate(schema, data, {
-		maxDepth: 32,
-		maxErrors: 10
-	});
+//#region src/context.ts
+/** Parse extract rule into source type and key, e.g. "header:authorization" -> { source: "header", key: "authorization" } */
+function parseExtractRule(rule) {
+	const idx = rule.indexOf(":");
+	if (idx === -1) throw new Error(`Invalid extract rule "${rule}": expected "source:key" format`);
+	const source = rule.slice(0, idx);
+	const key = rule.slice(idx + 1);
+	if (!source || !key) throw new Error(`Invalid extract rule "${rule}": source and key must be non-empty`);
 	return {
-		valid: errors.length === 0,
-		errors
+		source,
+		key
 	};
 }
-function formatValidationErrors(errors) {
-	return errors.map((e) => {
-		return `${e.instancePath.length > 0 ? e.instancePath.join("/") : "(root)"} (schema: ${e.schemaPath.join("/")})`;
-	}).join("; ");
+/** Check whether any context fields are defined */
+function contextHasExtracts(config) {
+	return Object.keys(config).length > 0;
+}
+/** Parse a Cookie header into key-value pairs */
+function parseCookieHeader(header) {
+	const result = {};
+	for (const pair of header.split(";")) {
+		const idx = pair.indexOf("=");
+		if (idx > 0) result[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
+	}
+	return result;
+}
+/** Build a RawContextMap keyed by config key from request headers, cookies, and query params */
+function buildRawContext(config, headerFn, url) {
+	const raw = {};
+	let cookieCache;
+	for (const [key, field] of Object.entries(config)) {
+		const { source, key: extractKey } = parseExtractRule(field.extract);
+		switch (source) {
+			case "header":
+				raw[key] = headerFn?.(extractKey) ?? null;
+				break;
+			case "cookie":
+				if (!cookieCache) cookieCache = parseCookieHeader(headerFn?.("cookie") ?? "");
+				raw[key] = cookieCache[extractKey] ?? null;
+				break;
+			case "query":
+				raw[key] = url.searchParams.get(extractKey) ?? null;
+				break;
+			default: raw[key] = null;
+		}
+	}
+	return raw;
+}
+/**
+* Resolve raw strings into validated context object.
+*
+* For each requested key:
+* - If raw value is null/missing -> pass null to JTD; schema decides via nullable()
+* - If schema expects string -> use raw value directly
+* - If schema expects object -> JSON.parse then validate
+*/
+function resolveContext(config, raw, requestedKeys) {
+	const result = {};
+	for (const key of requestedKeys) {
+		const field = config[key];
+		if (!field) throw new SeamError("CONTEXT_ERROR", `Context field "${key}" is not defined in router context config`, 400);
+		const rawValue = raw[key] ?? null;
+		let value;
+		if (rawValue === null) value = null;
+		else {
+			const schema = field.schema._schema;
+			const isStringSchema = "type" in schema && schema.type === "string" && !("nullable" in schema && schema.nullable);
+			const isNullableStringSchema = "type" in schema && schema.type === "string" && "nullable" in schema && schema.nullable;
+			if (isStringSchema || isNullableStringSchema) value = rawValue;
+			else try {
+				value = JSON.parse(rawValue);
+			} catch {
+				throw new SeamError("CONTEXT_ERROR", `Context field "${key}": failed to parse value as JSON`, 400);
+			}
+		}
+		const validation = validateInput(field.schema._schema, value);
+		if (!validation.valid) throw new SeamError("CONTEXT_ERROR", `Context field "${key}" validation failed: ${formatValidationErrors(validation.errors)}`, 400);
+		result[key] = value;
+	}
+	return result;
+}
+/** Syntax sugar for building extract rules; the underlying "source:key" format is unchanged. */
+const extract = {
+	header: (name) => `header:${name}`,
+	cookie: (name) => `cookie:${name}`,
+	query: (name) => `query:${name}`
+};
+
+//#endregion
+//#region src/manifest/index.ts
+function normalizeInvalidates(targets) {
+	return targets.map((t) => {
+		if (typeof t === "string") return { query: t };
+		const normalized = { query: t.query };
+		if (t.mapping) normalized.mapping = Object.fromEntries(Object.entries(t.mapping).map(([k, v]) => [k, typeof v === "string" ? { from: v } : v]));
+		return normalized;
+	});
+}
+function buildManifest(definitions, channels, contextConfig, transportDefaults) {
+	const mapped = {};
+	for (const [name, def] of Object.entries(definitions)) {
+		const k = def.kind ?? def.type;
+		const kind = k === "upload" ? "upload" : k === "stream" ? "stream" : k === "subscription" ? "subscription" : k === "command" ? "command" : "query";
+		const entry = {
+			kind,
+			input: def.input._schema
+		};
+		if (kind === "stream") entry.chunkOutput = def.output._schema;
+		else entry.output = def.output._schema;
+		if (def.error) entry.error = def.error._schema;
+		if (kind === "command" && def.invalidates && def.invalidates.length > 0) entry.invalidates = normalizeInvalidates(def.invalidates);
+		if (def.context && def.context.length > 0) entry.context = def.context;
+		const defAny = def;
+		if (defAny.transport) entry.transport = defAny.transport;
+		if (defAny.suppress) entry.suppress = defAny.suppress;
+		if (defAny.cache !== void 0) entry.cache = defAny.cache;
+		mapped[name] = entry;
+	}
+	const context = {};
+	if (contextConfig) for (const [key, field] of Object.entries(contextConfig)) context[key] = {
+		extract: field.extract,
+		schema: field.schema._schema
+	};
+	const manifest = {
+		version: 2,
+		context,
+		procedures: mapped,
+		transportDefaults: transportDefaults ?? {}
+	};
+	if (channels && Object.keys(channels).length > 0) manifest.channels = channels;
+	return manifest;
+}
+
+//#endregion
+//#region src/page/route-matcher.ts
+function compileRoute(pattern) {
+	return { segments: pattern.split("/").filter(Boolean).map((seg) => {
+		if (seg.startsWith("*")) {
+			const optional = seg.endsWith("?");
+			return {
+				kind: "catch-all",
+				name: optional ? seg.slice(1, -1) : seg.slice(1),
+				optional
+			};
+		}
+		if (seg.startsWith(":")) return {
+			kind: "param",
+			name: seg.slice(1)
+		};
+		return {
+			kind: "static",
+			value: seg
+		};
+	}) };
 }
+function matchRoute(segments, pathParts) {
+	const params = {};
+	for (let i = 0; i < segments.length; i++) {
+		const seg = segments[i];
+		if (seg.kind === "catch-all") {
+			const rest = pathParts.slice(i);
+			if (rest.length === 0 && !seg.optional) return null;
+			params[seg.name] = rest.join("/");
+			return params;
+		}
+		if (i >= pathParts.length) return null;
+		if (seg.kind === "static") {
+			if (seg.value !== pathParts[i]) return null;
+		} else params[seg.name] = pathParts[i];
+	}
+	if (segments.length !== pathParts.length) return null;
+	return params;
+}
+var RouteMatcher = class {
+	routes = [];
+	add(pattern, value) {
+		this.routes.push({
+			pattern,
+			compiled: compileRoute(pattern),
+			value
+		});
+	}
+	match(path) {
+		const parts = path.split("/").filter(Boolean);
+		for (const route of this.routes) {
+			const params = matchRoute(route.compiled.segments, parts);
+			if (params) return {
+				value: route.value,
+				params,
+				pattern: route.pattern
+			};
+		}
+		return null;
+	}
+};
 
 //#endregion
 //#region src/router/handler.ts
-async function handleRequest(procedures, procedureName, rawBody, validateOutput) {
+async function handleRequest(procedures, procedureName, rawBody, shouldValidateInput = true, validateOutput, ctx) {
 	const procedure = procedures.get(procedureName);
 	if (!procedure) return {
 		status: 404,
 		body: new SeamError("NOT_FOUND", `Procedure '${procedureName}' not found`).toJSON()
 	};
-	const validation = validateInput(procedure.inputSchema, rawBody);
-	if (!validation.valid) return {
-		status: 400,
-		body: new SeamError("VALIDATION_ERROR", `Input validation failed: ${formatValidationErrors(validation.errors)}`).toJSON()
-	};
+	if (shouldValidateInput) {
+		const validation = validateInput(procedure.inputSchema, rawBody);
+		if (!validation.valid) {
+			const details = formatValidationDetails(validation.errors, procedure.inputSchema, rawBody);
+			return {
+				status: 400,
+				body: new SeamError("VALIDATION_ERROR", `Input validation failed for procedure '${procedureName}': ${formatValidationErrors(validation.errors)}`, void 0, details).toJSON()
+			};
+		}
+	}
 	try {
-		const result = await procedure.handler({ input: rawBody });
+		const result = await procedure.handler({
+			input: rawBody,
+			ctx: ctx ?? {}
+		});
 		if (validateOutput) {
 			const outValidation = validateInput(procedure.outputSchema, result);
 			if (!outValidation.valid) return {
@@ -250,9 +459,10 @@ async function handleRequest(procedures, procedureName, rawBody, validateOutput)
 		};
 	}
 }
-async function handleBatchRequest(procedures, calls, validateOutput) {
+async function handleBatchRequest(procedures, calls, shouldValidateInput = true, validateOutput, ctxResolver) {
 	return { results: await Promise.all(calls.map(async (call) => {
-		const result = await handleRequest(procedures, call.procedure, call.input, validateOutput);
+		const ctx = ctxResolver ? ctxResolver(call.procedure) : void 0;
+		const result = await handleRequest(procedures, call.procedure, call.input, shouldValidateInput, validateOutput, ctx);
 		if (result.status === 200) return {
 			ok: true,
 			data: result.body.data
@@ -263,12 +473,20 @@ async function handleBatchRequest(procedures, calls, validateOutput) {
 		};
 	})) };
 }
-async function* handleSubscription(subscriptions, name, rawInput, validateOutput) {
+async function* handleSubscription(subscriptions, name, rawInput, shouldValidateInput = true, validateOutput, ctx) {
 	const sub = subscriptions.get(name);
 	if (!sub) throw new SeamError("NOT_FOUND", `Subscription '${name}' not found`);
-	const validation = validateInput(sub.inputSchema, rawInput);
-	if (!validation.valid) throw new SeamError("VALIDATION_ERROR", `Input validation failed: ${formatValidationErrors(validation.errors)}`);
-	for await (const value of sub.handler({ input: rawInput })) {
+	if (shouldValidateInput) {
+		const validation = validateInput(sub.inputSchema, rawInput);
+		if (!validation.valid) {
+			const details = formatValidationDetails(validation.errors, sub.inputSchema, rawInput);
+			throw new SeamError("VALIDATION_ERROR", `Input validation failed: ${formatValidationErrors(validation.errors)}`, void 0, details);
+		}
+	}
+	for await (const value of sub.handler({
+		input: rawInput,
+		ctx: ctx ?? {}
+	})) {
 		if (validateOutput) {
 			const outValidation = validateInput(sub.outputSchema, value);
 			if (!outValidation.valid) throw new SeamError("INTERNAL_ERROR", `Output validation failed: ${formatValidationErrors(outValidation.errors)}`);
@@ -276,19 +494,259 @@ async function* handleSubscription(subscriptions, name, rawInput, validateOutput
 		yield value;
 	}
 }
+async function handleUploadRequest(uploads, procedureName, rawBody, file, shouldValidateInput = true, validateOutput, ctx) {
+	const upload = uploads.get(procedureName);
+	if (!upload) return {
+		status: 404,
+		body: new SeamError("NOT_FOUND", `Procedure '${procedureName}' not found`).toJSON()
+	};
+	if (shouldValidateInput) {
+		const validation = validateInput(upload.inputSchema, rawBody);
+		if (!validation.valid) {
+			const details = formatValidationDetails(validation.errors, upload.inputSchema, rawBody);
+			return {
+				status: 400,
+				body: new SeamError("VALIDATION_ERROR", `Input validation failed for procedure '${procedureName}': ${formatValidationErrors(validation.errors)}`, void 0, details).toJSON()
+			};
+		}
+	}
+	try {
+		const result = await upload.handler({
+			input: rawBody,
+			file,
+			ctx: ctx ?? {}
+		});
+		if (validateOutput) {
+			const outValidation = validateInput(upload.outputSchema, result);
+			if (!outValidation.valid) return {
+				status: 500,
+				body: new SeamError("INTERNAL_ERROR", `Output validation failed: ${formatValidationErrors(outValidation.errors)}`).toJSON()
+			};
+		}
+		return {
+			status: 200,
+			body: {
+				ok: true,
+				data: result
+			}
+		};
+	} catch (error) {
+		if (error instanceof SeamError) return {
+			status: error.status,
+			body: error.toJSON()
+		};
+		return {
+			status: 500,
+			body: new SeamError("INTERNAL_ERROR", error instanceof Error ? error.message : "Unknown error").toJSON()
+		};
+	}
+}
+async function* handleStream(streams, name, rawInput, shouldValidateInput = true, validateOutput, ctx) {
+	const stream = streams.get(name);
+	if (!stream) throw new SeamError("NOT_FOUND", `Stream '${name}' not found`);
+	if (shouldValidateInput) {
+		const validation = validateInput(stream.inputSchema, rawInput);
+		if (!validation.valid) {
+			const details = formatValidationDetails(validation.errors, stream.inputSchema, rawInput);
+			throw new SeamError("VALIDATION_ERROR", `Input validation failed: ${formatValidationErrors(validation.errors)}`, void 0, details);
+		}
+	}
+	for await (const value of stream.handler({
+		input: rawInput,
+		ctx: ctx ?? {}
+	})) {
+		if (validateOutput) {
+			const outValidation = validateInput(stream.chunkOutputSchema, value);
+			if (!outValidation.valid) throw new SeamError("INTERNAL_ERROR", `Output validation failed: ${formatValidationErrors(outValidation.errors)}`);
+		}
+		yield value;
+	}
+}
+
+//#endregion
+//#region src/router/categorize.ts
+function resolveKind(name, def) {
+	if ("kind" in def && def.kind) return def.kind;
+	if ("type" in def && def.type) {
+		console.warn(`[seam] "${name}": "type" field in procedure definition is deprecated, use "kind" instead`);
+		return def.type;
+	}
+	return "query";
+}
+/** Split a flat definition map into typed procedure/subscription/stream maps */
+function categorizeProcedures(definitions, contextConfig) {
+	const procedureMap = /* @__PURE__ */ new Map();
+	const subscriptionMap = /* @__PURE__ */ new Map();
+	const streamMap = /* @__PURE__ */ new Map();
+	const uploadMap = /* @__PURE__ */ new Map();
+	const kindMap = /* @__PURE__ */ new Map();
+	for (const [name, def] of Object.entries(definitions)) {
+		const kind = resolveKind(name, def);
+		kindMap.set(name, kind);
+		const contextKeys = def.context ?? [];
+		if (contextConfig && contextKeys.length > 0) {
+			for (const key of contextKeys) if (!(key in contextConfig)) throw new Error(`Procedure "${name}" references undefined context field "${key}"`);
+		}
+		if (kind === "upload") uploadMap.set(name, {
+			inputSchema: def.input._schema,
+			outputSchema: def.output._schema,
+			contextKeys,
+			handler: def.handler
+		});
+		else if (kind === "stream") streamMap.set(name, {
+			inputSchema: def.input._schema,
+			chunkOutputSchema: def.output._schema,
+			contextKeys,
+			handler: def.handler
+		});
+		else if (kind === "subscription") subscriptionMap.set(name, {
+			inputSchema: def.input._schema,
+			outputSchema: def.output._schema,
+			contextKeys,
+			handler: def.handler
+		});
+		else procedureMap.set(name, {
+			inputSchema: def.input._schema,
+			outputSchema: def.output._schema,
+			contextKeys,
+			handler: def.handler
+		});
+	}
+	return {
+		procedureMap,
+		subscriptionMap,
+		streamMap,
+		uploadMap,
+		kindMap
+	};
+}
+
+//#endregion
+//#region src/page/loader-error.ts
+function isLoaderError(value) {
+	return typeof value === "object" && value !== null && value.__error === true && typeof value.code === "string" && typeof value.message === "string";
+}
+
+//#endregion
+//#region src/page/projection.ts
+/** Set a nested field by dot-separated path, creating intermediate objects as needed. */
+function setNestedField(target, path, value) {
+	const parts = path.split(".");
+	let current = target;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const key = parts[i];
+		if (!(key in current) || typeof current[key] !== "object" || current[key] === null) current[key] = {};
+		current = current[key];
+	}
+	current[parts[parts.length - 1]] = value;
+}
+/** Get a nested field by dot-separated path. */
+function getNestedField(source, path) {
+	const parts = path.split(".");
+	let current = source;
+	for (const part of parts) {
+		if (current === null || current === void 0 || typeof current !== "object") return;
+		current = current[part];
+	}
+	return current;
+}
+/** Prune a single value according to its projected field paths. */
+function pruneValue(value, fields) {
+	const arrayFields = [];
+	const plainFields = [];
+	for (const f of fields) if (f === "$") return value;
+	else if (f.startsWith("$.")) arrayFields.push(f.slice(2));
+	else plainFields.push(f);
+	if (arrayFields.length > 0 && Array.isArray(value)) return value.map((item) => {
+		if (typeof item !== "object" || item === null) return item;
+		const pruned = {};
+		for (const field of arrayFields) {
+			const val = getNestedField(item, field);
+			if (val !== void 0) setNestedField(pruned, field, val);
+		}
+		return pruned;
+	});
+	if (plainFields.length > 0 && typeof value === "object" && value !== null) {
+		const source = value;
+		const pruned = {};
+		for (const field of plainFields) {
+			const val = getNestedField(source, field);
+			if (val !== void 0) setNestedField(pruned, field, val);
+		}
+		return pruned;
+	}
+	return value;
+}
+/** Prune data to only include projected fields. Missing projection = keep all. */
+function applyProjection(data, projections) {
+	if (!projections) return data;
+	const result = {};
+	for (const [key, value] of Object.entries(data)) {
+		if (isLoaderError(value)) {
+			result[key] = value;
+			continue;
+		}
+		const fields = projections[key];
+		if (!fields) result[key] = value;
+		else result[key] = pruneValue(value, fields);
+	}
+	return result;
+}
 
 //#endregion
 //#region src/page/handler.ts
-/** Execute loaders, returning keyed results */
-async function executeLoaders(loaders, params, procedures) {
+/** Execute loaders, returning keyed results and metadata.
+*  Each loader is wrapped in its own try-catch so a single failure
+*  does not abort sibling loaders — the page renders at 200 with partial data. */
+async function executeLoaders(loaders, params, procedures, searchParams, ctxResolver, shouldValidateInput) {
 	const entries = Object.entries(loaders);
 	const results = await Promise.all(entries.map(async ([key, loader]) => {
-		const { procedure, input } = loader(params);
-		const proc = procedures.get(procedure);
-		if (!proc) throw new SeamError("INTERNAL_ERROR", `Procedure '${procedure}' not found`);
-		return [key, await proc.handler({ input })];
+		const { procedure, input } = loader(params, searchParams);
+		try {
+			const proc = procedures.get(procedure);
+			if (!proc) throw new SeamError("INTERNAL_ERROR", `Procedure '${procedure}' not found`);
+			if (shouldValidateInput) {
+				const v = validateInput(proc.inputSchema, input);
+				if (!v.valid) throw new SeamError("VALIDATION_ERROR", `Input validation failed: ${formatValidationErrors(v.errors)}`);
+			}
+			const ctx = ctxResolver ? ctxResolver(proc) : {};
+			return {
+				key,
+				result: await proc.handler({
+					input,
+					ctx
+				}),
+				procedure,
+				input
+			};
+		} catch (err) {
+			const code = err instanceof SeamError ? err.code : "INTERNAL_ERROR";
+			const message = err instanceof Error ? err.message : "Unknown error";
+			console.error(`[seam] Loader "${key}" failed:`, err);
+			return {
+				key,
+				result: {
+					__error: true,
+					code,
+					message
+				},
+				procedure,
+				input,
+				error: true
+			};
+		}
 	}));
-	return Object.fromEntries(results);
+	return {
+		data: Object.fromEntries(results.map((r) => [r.key, r.result])),
+		meta: Object.fromEntries(results.map((r) => {
+			const entry = {
+				procedure: r.procedure,
+				input: r.input
+			};
+			if (r.error) entry.error = true;
+			return [r.key, entry];
+		}))
+	};
 }
 /** Select the template for a given locale, falling back to the default template */
 function selectTemplate(defaultTemplate, localeTemplates, locale) {
@@ -306,15 +764,20 @@ function lookupMessages(config, routePattern, locale) {
 	}
 	return config.messages[locale]?.[routeHash] ?? {};
 }
-async function handlePageRequest(page, params, procedures, i18nOpts) {
+async function handlePageRequest(page, params, procedures, i18nOpts, searchParams, ctxResolver, shouldValidateInput) {
 	try {
 		const t0 = performance.now();
 		const layoutChain = page.layoutChain ?? [];
 		const locale = i18nOpts?.locale;
-		const loaderResults = await Promise.all([...layoutChain.map((layout) => executeLoaders(layout.loaders, params, procedures)), executeLoaders(page.loaders, params, procedures)]);
+		const loaderResults = await Promise.all([...layoutChain.map((layout) => executeLoaders(layout.loaders, params, procedures, searchParams, ctxResolver, shouldValidateInput)), executeLoaders(page.loaders, params, procedures, searchParams, ctxResolver, shouldValidateInput)]);
 		const t1 = performance.now();
 		const allData = {};
-		for (const result of loaderResults) Object.assign(allData, result);
+		const allMeta = {};
+		for (const { data, meta } of loaderResults) {
+			Object.assign(allData, data);
+			Object.assign(allMeta, meta);
+		}
+		const prunedData = applyProjection(allData, page.projections);
 		let composedTemplate = selectTemplate(page.template, page.localeTemplates, locale);
 		for (let i = layoutChain.length - 1; i >= 0; i--) {
 			const layout = layoutChain[i];
@@ -322,109 +785,47 @@ async function handlePageRequest(page, params, procedures, i18nOpts) {
 		}
 		const config = {
 			layout_chain: layoutChain.map((l) => ({
-				id: l.id,
-				loader_keys: Object.keys(l.loaders)
-			})),
-			data_id: page.dataId ?? "__data",
-			head_meta: page.headMeta
-		};
-		if (page.pageAssets) config.page_assets = page.pageAssets;
-		let i18nOptsJson;
-		if (i18nOpts) {
-			const { config: i18nConfig, routePattern } = i18nOpts;
-			const messages = lookupMessages(i18nConfig, routePattern, i18nOpts.locale);
-			const routeHash = i18nConfig.routeHashes[routePattern];
-			const i18nData = {
-				locale: i18nOpts.locale,
-				default_locale: i18nConfig.default,
-				messages
-			};
-			if (i18nConfig.cache && routeHash) {
-				i18nData.hash = i18nConfig.contentHashes[routeHash]?.[i18nOpts.locale];
-				i18nData.router = i18nConfig.contentHashes;
-			}
-			i18nOptsJson = JSON.stringify(i18nData);
-		}
-		const html = renderPage(composedTemplate, JSON.stringify(allData), JSON.stringify(config), i18nOptsJson);
-		const t2 = performance.now();
-		return {
-			status: 200,
-			html,
-			timing: {
-				dataFetch: t1 - t0,
-				inject: t2 - t1
-			}
-		};
-	} catch (error) {
-		return {
-			status: 500,
-			html: `<!DOCTYPE html><html><body><h1>500 Internal Server Error</h1><p>${escapeHtml(error instanceof Error ? error.message : "Unknown error")}</p></body></html>`
-		};
-	}
-}
-
-//#endregion
-//#region src/page/route-matcher.ts
-function compileRoute(pattern) {
-	return { segments: pattern.split("/").filter(Boolean).map((seg) => {
-		if (seg.startsWith("*")) {
-			const optional = seg.endsWith("?");
-			return {
-				kind: "catch-all",
-				name: optional ? seg.slice(1, -1) : seg.slice(1),
-				optional
-			};
-		}
-		if (seg.startsWith(":")) return {
-			kind: "param",
-			name: seg.slice(1)
-		};
-		return {
-			kind: "static",
-			value: seg
-		};
-	}) };
-}
-function matchRoute(segments, pathParts) {
-	const params = {};
-	for (let i = 0; i < segments.length; i++) {
-		const seg = segments[i];
-		if (seg.kind === "catch-all") {
-			const rest = pathParts.slice(i);
-			if (rest.length === 0 && !seg.optional) return null;
-			params[seg.name] = rest.join("/");
-			return params;
-		}
-		if (i >= pathParts.length) return null;
-		if (seg.kind === "static") {
-			if (seg.value !== pathParts[i]) return null;
-		} else params[seg.name] = pathParts[i];
-	}
-	if (segments.length !== pathParts.length) return null;
-	return params;
-}
-var RouteMatcher = class {
-	routes = [];
-	add(pattern, value) {
-		this.routes.push({
-			pattern,
-			compiled: compileRoute(pattern),
-			value
-		});
-	}
-	match(path) {
-		const parts = path.split("/").filter(Boolean);
-		for (const route of this.routes) {
-			const params = matchRoute(route.compiled.segments, parts);
-			if (params) return {
-				value: route.value,
-				params,
-				pattern: route.pattern
+				id: l.id,
+				loader_keys: Object.keys(l.loaders)
+			})),
+			data_id: page.dataId ?? "__data",
+			head_meta: page.headMeta,
+			loader_metadata: allMeta
+		};
+		if (page.pageAssets) config.page_assets = page.pageAssets;
+		let i18nOptsJson;
+		if (i18nOpts) {
+			const { config: i18nConfig, routePattern } = i18nOpts;
+			const messages = lookupMessages(i18nConfig, routePattern, i18nOpts.locale);
+			const routeHash = i18nConfig.routeHashes[routePattern];
+			const i18nData = {
+				locale: i18nOpts.locale,
+				default_locale: i18nConfig.default,
+				messages
 			};
+			if (i18nConfig.cache && routeHash) {
+				i18nData.hash = i18nConfig.contentHashes[routeHash]?.[i18nOpts.locale];
+				i18nData.router = i18nConfig.contentHashes;
+			}
+			i18nOptsJson = JSON.stringify(i18nData);
 		}
-		return null;
+		const html = renderPage(composedTemplate, JSON.stringify(prunedData), JSON.stringify(config), i18nOptsJson);
+		const t2 = performance.now();
+		return {
+			status: 200,
+			html,
+			timing: {
+				dataFetch: t1 - t0,
+				inject: t2 - t1
+			}
+		};
+	} catch (error) {
+		return {
+			status: 500,
+			html: `<!DOCTYPE html><html><body><h1>500 Internal Server Error</h1><p>${escapeHtml(error instanceof Error ? error.message : "Unknown error")}</p></body></html>`
+		};
 	}
-};
+}
 
 //#endregion
 //#region src/resolve.ts
@@ -517,9 +918,13 @@ function defaultStrategies() {
 }
 
 //#endregion
-//#region src/router/index.ts
-function isSubscriptionDef(def) {
-	return "type" in def && def.type === "subscription";
+//#region src/router/helpers.ts
+/** Resolve a ValidationMode to a boolean flag */
+function resolveValidationMode(mode) {
+	const m = mode ?? "dev";
+	if (m === "always") return true;
+	if (m === "never") return false;
+	return typeof process !== "undefined" && process.env.NODE_ENV !== "production";
 }
 /** Build the resolve strategy list from options */
 function buildStrategies(opts) {
@@ -534,6 +939,7 @@ function registerI18nQuery(procedureMap, config) {
 	procedureMap.set("__seam_i18n_query", {
 		inputSchema: {},
 		outputSchema: {},
+		contextKeys: [],
 		handler: ({ input }) => {
 			const { route, locale } = input;
 			const messages = lookupI18nMessages(config, route, locale);
@@ -553,19 +959,81 @@ function lookupI18nMessages(config, routeHash, locale) {
 	}
 	return config.messages[locale]?.[routeHash] ?? {};
 }
-function createRouter(procedures, opts) {
-	const procedureMap = /* @__PURE__ */ new Map();
-	const subscriptionMap = /* @__PURE__ */ new Map();
-	for (const [name, def] of Object.entries(procedures)) if (isSubscriptionDef(def)) subscriptionMap.set(name, {
-		inputSchema: def.input._schema,
-		outputSchema: def.output._schema,
-		handler: def.handler
-	});
-	else procedureMap.set(name, {
-		inputSchema: def.input._schema,
-		outputSchema: def.output._schema,
-		handler: def.handler
+/** Collect channel metadata from channel results for manifest */
+function collectChannelMeta(channels) {
+	if (!channels || channels.length === 0) return void 0;
+	return Object.fromEntries(channels.map((ch) => {
+		const firstKey = Object.keys(ch.procedures)[0] ?? "";
+		return [firstKey.includes(".") ? firstKey.slice(0, firstKey.indexOf(".")) : firstKey, ch.channelMeta];
+	}));
+}
+/** Resolve context for a procedure, returning undefined if no context needed */
+function resolveCtxFor(map, name, rawCtx, ctxConfig) {
+	if (!rawCtx) return void 0;
+	const proc = map.get(name);
+	if (!proc || proc.contextKeys.length === 0) return void 0;
+	return resolveContext(ctxConfig, rawCtx, proc.contextKeys);
+}
+/** Resolve locale and match page route */
+async function matchAndHandlePage(pageMatcher, procedureMap, i18nConfig, strategies, hasUrlPrefix, path, headers, rawCtx, ctxConfig, shouldValidateInput) {
+	let pathLocale = null;
+	let routePath = path;
+	if (hasUrlPrefix && i18nConfig) {
+		const segments = path.split("/").filter(Boolean);
+		const localeSet = new Set(i18nConfig.locales);
+		const first = segments[0];
+		if (first && localeSet.has(first)) {
+			pathLocale = first;
+			routePath = "/" + segments.slice(1).join("/") || "/";
+		}
+	}
+	let locale;
+	if (i18nConfig) locale = resolveChain(strategies, {
+		url: headers?.url ?? "",
+		pathLocale,
+		cookie: headers?.cookie,
+		acceptLanguage: headers?.acceptLanguage,
+		locales: i18nConfig.locales,
+		defaultLocale: i18nConfig.default
 	});
+	const match = pageMatcher.match(routePath);
+	if (!match) return null;
+	let searchParams;
+	if (headers?.url) try {
+		const url = new URL(headers.url, "http://localhost");
+		if (url.search) searchParams = url.searchParams;
+	} catch {}
+	const i18nOpts = locale && i18nConfig ? {
+		locale,
+		config: i18nConfig,
+		routePattern: match.pattern
+	} : void 0;
+	const ctxResolver = rawCtx ? (proc) => {
+		if (proc.contextKeys.length === 0) return {};
+		return resolveContext(ctxConfig ?? {}, rawCtx, proc.contextKeys);
+	} : void 0;
+	return handlePageRequest(match.value, match.params, procedureMap, i18nOpts, searchParams, ctxResolver, shouldValidateInput);
+}
+/** Catch context resolution errors and return them as HandleResult */
+function resolveCtxSafe(map, name, rawCtx, ctxConfig) {
+	try {
+		return { ctx: resolveCtxFor(map, name, rawCtx, ctxConfig) };
+	} catch (err) {
+		if (err instanceof SeamError) return { error: {
+			status: err.status,
+			body: err.toJSON()
+		} };
+		throw err;
+	}
+}
+
+//#endregion
+//#region src/router/state.ts
+/** Build all shared state that createRouter methods close over */
+function initRouterState(procedures, opts) {
+	const ctxConfig = opts?.context ?? {};
+	const { procedureMap, subscriptionMap, streamMap, uploadMap, kindMap } = categorizeProcedures(procedures, Object.keys(ctxConfig).length > 0 ? ctxConfig : void 0);
+	const shouldValidateInput = resolveValidationMode(opts?.validation?.input);
 	const shouldValidateOutput = opts?.validateOutput ?? (typeof process !== "undefined" && process.env.NODE_ENV !== "production");
 	const pageMatcher = new RouteMatcher();
 	const pages = opts?.pages;
@@ -573,56 +1041,163 @@ function createRouter(procedures, opts) {
 	const i18nConfig = opts?.i18n ?? null;
 	const { strategies, hasUrlPrefix } = buildStrategies(opts);
 	if (i18nConfig) registerI18nQuery(procedureMap, i18nConfig);
-	const channelsMeta = opts?.channels && opts.channels.length > 0 ? Object.fromEntries(opts.channels.map((ch) => {
-		const firstKey = Object.keys(ch.procedures)[0] ?? "";
-		return [firstKey.includes(".") ? firstKey.slice(0, firstKey.indexOf(".")) : firstKey, ch.channelMeta];
-	})) : void 0;
 	return {
-		procedures,
-		hasPages: !!pages && Object.keys(pages).length > 0,
+		ctxConfig,
+		procedureMap,
+		subscriptionMap,
+		streamMap,
+		uploadMap,
+		kindMap,
+		shouldValidateInput,
+		shouldValidateOutput,
+		pageMatcher,
+		pages,
+		i18nConfig,
+		strategies,
+		hasUrlPrefix,
+		channelsMeta: collectChannelMeta(opts?.channels),
+		hasCtx: contextHasExtracts(ctxConfig)
+	};
+}
+/** Build request-response methods: handle, handleBatch, handleUpload */
+function buildRpcMethods(state) {
+	return {
+		async handle(procedureName, body, rawCtx) {
+			const { ctx, error } = resolveCtxSafe(state.procedureMap, procedureName, rawCtx, state.ctxConfig);
+			if (error) return error;
+			return handleRequest(state.procedureMap, procedureName, body, state.shouldValidateInput, state.shouldValidateOutput, ctx);
+		},
+		handleBatch(calls, rawCtx) {
+			const ctxResolver = rawCtx ? (name) => resolveCtxFor(state.procedureMap, name, rawCtx, state.ctxConfig) ?? {} : void 0;
+			return handleBatchRequest(state.procedureMap, calls, state.shouldValidateInput, state.shouldValidateOutput, ctxResolver);
+		},
+		async handleUpload(name, body, file, rawCtx) {
+			const { ctx, error } = resolveCtxSafe(state.uploadMap, name, rawCtx, state.ctxConfig);
+			if (error) return error;
+			return handleUploadRequest(state.uploadMap, name, body, file, state.shouldValidateInput, state.shouldValidateOutput, ctx);
+		}
+	};
+}
+/** Build all Router method implementations from shared state */
+function buildRouterMethods(state, procedures, opts) {
+	return {
+		hasPages: !!state.pages && Object.keys(state.pages).length > 0,
+		ctxConfig: state.ctxConfig,
+		hasContext() {
+			return state.hasCtx;
+		},
 		manifest() {
-			return buildManifest(procedures, channelsMeta);
+			return buildManifest(procedures, state.channelsMeta, state.ctxConfig, opts?.transportDefaults);
 		},
-		handle(procedureName, body) {
-			return handleRequest(procedureMap, procedureName, body, shouldValidateOutput);
+		...buildRpcMethods(state),
+		handleSubscription(name, input, rawCtx) {
+			const ctx = resolveCtxFor(state.subscriptionMap, name, rawCtx, state.ctxConfig);
+			return handleSubscription(state.subscriptionMap, name, input, state.shouldValidateInput, state.shouldValidateOutput, ctx);
 		},
-		handleBatch(calls) {
-			return handleBatchRequest(procedureMap, calls, shouldValidateOutput);
+		handleStream(name, input, rawCtx) {
+			const ctx = resolveCtxFor(state.streamMap, name, rawCtx, state.ctxConfig);
+			return handleStream(state.streamMap, name, input, state.shouldValidateInput, state.shouldValidateOutput, ctx);
 		},
-		handleSubscription(name, input) {
-			return handleSubscription(subscriptionMap, name, input, shouldValidateOutput);
+		getKind(name) {
+			return state.kindMap.get(name) ?? null;
 		},
-		async handlePage(path, headers) {
-			let pathLocale = null;
-			let routePath = path;
-			if (hasUrlPrefix && i18nConfig) {
-				const segments = path.split("/").filter(Boolean);
-				const localeSet = new Set(i18nConfig.locales);
-				const first = segments[0];
-				if (first && localeSet.has(first)) {
-					pathLocale = first;
-					routePath = "/" + segments.slice(1).join("/") || "/";
-				}
-			}
-			let locale;
-			if (i18nConfig) locale = resolveChain(strategies, {
-				url: headers?.url ?? "",
-				pathLocale,
-				cookie: headers?.cookie,
-				acceptLanguage: headers?.acceptLanguage,
-				locales: i18nConfig.locales,
-				defaultLocale: i18nConfig.default
-			});
-			const match = pageMatcher.match(routePath);
-			if (!match) return null;
-			const i18nOpts = locale && i18nConfig ? {
-				locale,
-				config: i18nConfig,
-				routePattern: match.pattern
-			} : void 0;
-			return handlePageRequest(match.value, match.params, procedureMap, i18nOpts);
+		handlePage(path, headers, rawCtx) {
+			return matchAndHandlePage(state.pageMatcher, state.procedureMap, state.i18nConfig, state.strategies, state.hasUrlPrefix, path, headers, rawCtx, state.ctxConfig, state.shouldValidateInput);
+		}
+	};
+}
+
+//#endregion
+//#region src/router/index.ts
+function createRouter(procedures, opts) {
+	const state = initRouterState(procedures, opts);
+	return {
+		procedures,
+		rpcHashMap: opts?.rpcHashMap,
+		...buildRouterMethods(state, procedures, opts)
+	};
+}
+
+//#endregion
+//#region src/factory.ts
+function query(def) {
+	return {
+		...def,
+		kind: "query"
+	};
+}
+function command(def) {
+	return {
+		...def,
+		kind: "command"
+	};
+}
+function subscription(def) {
+	return {
+		...def,
+		kind: "subscription"
+	};
+}
+function stream(def) {
+	return {
+		...def,
+		kind: "stream"
+	};
+}
+function upload(def) {
+	return {
+		...def,
+		kind: "upload"
+	};
+}
+
+//#endregion
+//#region src/seam-router.ts
+function createSeamRouter(config) {
+	const { context, ...restConfig } = config;
+	const define = {
+		query(def) {
+			return {
+				...def,
+				kind: "query"
+			};
+		},
+		command(def) {
+			return {
+				...def,
+				kind: "command"
+			};
+		},
+		subscription(def) {
+			return {
+				...def,
+				kind: "subscription"
+			};
+		},
+		stream(def) {
+			return {
+				...def,
+				kind: "stream"
+			};
+		},
+		upload(def) {
+			return {
+				...def,
+				kind: "upload"
+			};
 		}
 	};
+	function router(procedures, extraOpts) {
+		return createRouter(procedures, {
+			...restConfig,
+			context,
+			...extraOpts
+		});
+	}
+	return {
+		router,
+		define
+	};
 }
 
 //#endregion
@@ -661,7 +1236,7 @@ function createChannel(name, def) {
 	const channelInputSchema = def.input._schema;
 	for (const [msgName, msgDef] of Object.entries(def.incoming)) {
 		const command = {
-			type: "command",
+			kind: "command",
 			input: { _schema: mergeObjectSchemas(channelInputSchema, msgDef.input._schema) },
 			output: msgDef.output,
 			handler: msgDef.handler
@@ -671,7 +1246,7 @@ function createChannel(name, def) {
 	}
 	const unionSchema = buildOutgoingUnionSchema(def.outgoing);
 	const subscription = {
-		type: "subscription",
+		kind: "subscription",
 		input: def.input,
 		output: { _schema: unionSchema },
 		handler: def.subscribe
@@ -688,13 +1263,15 @@ function createChannel(name, def) {
 	}
 	const outgoingMeta = {};
 	for (const [eventName, node] of Object.entries(def.outgoing)) outgoingMeta[eventName] = node._schema;
+	const channelMeta = {
+		input: channelInputSchema,
+		incoming: incomingMeta,
+		outgoing: outgoingMeta
+	};
+	if (def.transport) channelMeta.transport = def.transport;
 	return {
 		procedures,
-		channelMeta: {
-			input: channelInputSchema,
-			incoming: incomingMeta,
-			outgoing: outgoingMeta
-		}
+		channelMeta
 	};
 }
 
@@ -775,6 +1352,10 @@ async function handleStaticAsset(assetPath, staticDir) {
 function sseDataEvent(data) {
 	return `event: data\ndata: ${JSON.stringify(data)}\n\n`;
 }
+/** Format an SSE data event with a sequence id (for streams) */
+function sseDataEventWithId(data, id) {
+	return `event: data\nid: ${id}\ndata: ${JSON.stringify(data)}\n\n`;
+}
 /** Format an SSE error event */
 function sseErrorEvent(code, message, transient = false) {
 	return `event: error\ndata: ${JSON.stringify({
@@ -787,16 +1368,93 @@ function sseErrorEvent(code, message, transient = false) {
 function sseCompleteEvent() {
 	return "event: complete\ndata: {}\n\n";
 }
-async function* sseStream(router, name, input) {
+function formatSseError(error) {
+	if (error instanceof SeamError) return sseErrorEvent(error.code, error.message);
+	return sseErrorEvent("INTERNAL_ERROR", error instanceof Error ? error.message : "Unknown error");
+}
+const DEFAULT_HEARTBEAT_MS$1 = 21e3;
+const DEFAULT_SSE_IDLE_MS = 3e4;
+async function* withSseLifecycle(inner, opts) {
+	const heartbeatMs = opts?.heartbeatInterval ?? DEFAULT_HEARTBEAT_MS$1;
+	const idleMs = opts?.sseIdleTimeout ?? DEFAULT_SSE_IDLE_MS;
+	const idleEnabled = idleMs > 0;
+	const queue = [];
+	let resolve = null;
+	const signal = () => {
+		if (resolve) {
+			resolve();
+			resolve = null;
+		}
+	};
+	let idleTimer = null;
+	const resetIdle = () => {
+		if (!idleEnabled) return;
+		if (idleTimer) clearTimeout(idleTimer);
+		idleTimer = setTimeout(() => {
+			queue.push({ type: "idle" });
+			signal();
+		}, idleMs);
+	};
+	const heartbeatTimer = setInterval(() => {
+		queue.push({ type: "heartbeat" });
+		signal();
+	}, heartbeatMs);
+	resetIdle();
+	(async () => {
+		try {
+			for await (const chunk of inner) {
+				queue.push({
+					type: "data",
+					value: chunk
+				});
+				resetIdle();
+				signal();
+			}
+		} catch {}
+		queue.push({ type: "done" });
+		signal();
+	})();
+	try {
+		for (;;) {
+			while (queue.length === 0) await new Promise((r) => {
+				resolve = r;
+			});
+			const item = queue.shift();
+			if (!item) continue;
+			if (item.type === "data") yield item.value;
+			else if (item.type === "heartbeat") yield ": heartbeat\n\n";
+			else if (item.type === "idle") {
+				yield sseCompleteEvent();
+				return;
+			} else return;
+		}
+	} finally {
+		clearInterval(heartbeatTimer);
+		if (idleTimer) clearTimeout(idleTimer);
+	}
+}
+async function* sseStream(router, name, input, rawCtx) {
+	try {
+		for await (const value of router.handleSubscription(name, input, rawCtx)) yield sseDataEvent(value);
+		yield sseCompleteEvent();
+	} catch (error) {
+		yield formatSseError(error);
+	}
+}
+async function* sseStreamForStream(router, name, input, signal, rawCtx) {
+	const gen = router.handleStream(name, input, rawCtx);
+	if (signal) signal.addEventListener("abort", () => {
+		gen.return(void 0);
+	}, { once: true });
 	try {
-		for await (const value of router.handleSubscription(name, input)) yield sseDataEvent(value);
+		let seq = 0;
+		for await (const value of gen) yield sseDataEventWithId(value, seq++);
 		yield sseCompleteEvent();
 	} catch (error) {
-		if (error instanceof SeamError) yield sseErrorEvent(error.code, error.message);
-		else yield sseErrorEvent("INTERNAL_ERROR", error instanceof Error ? error.message : "Unknown error");
+		yield formatSseError(error);
 	}
 }
-async function handleBatchHttp(req, router, hashToName) {
+async function handleBatchHttp(req, router, hashToName, rawCtx) {
 	let body;
 	try {
 		body = await req.body();
@@ -810,45 +1468,63 @@ async function handleBatchHttp(req, router, hashToName) {
 	}));
 	return jsonResponse(200, {
 		ok: true,
-		data: await router.handleBatch(calls)
+		data: await router.handleBatch(calls, rawCtx)
 	});
 }
+/** Resolve hash -> original name when obfuscation is active. Accepts both hashed and raw names. */
+function resolveHashName(hashToName, name) {
+	if (!hashToName) return name;
+	return hashToName.get(name) ?? name;
+}
+async function handleProcedurePost(req, router, name, rawCtx, sseOptions) {
+	let body;
+	try {
+		body = await req.body();
+	} catch {
+		return errorResponse(400, "VALIDATION_ERROR", "Invalid JSON body");
+	}
+	if (router.getKind(name) === "stream") {
+		const controller = new AbortController();
+		return {
+			status: 200,
+			headers: SSE_HEADER,
+			stream: withSseLifecycle(sseStreamForStream(router, name, body, controller.signal, rawCtx), sseOptions),
+			onCancel: () => controller.abort()
+		};
+	}
+	if (router.getKind(name) === "upload") {
+		if (!req.file) return errorResponse(400, "VALIDATION_ERROR", "Upload requires multipart/form-data");
+		const file = await req.file();
+		if (!file) return errorResponse(400, "VALIDATION_ERROR", "Upload requires file in multipart body");
+		const result = await router.handleUpload(name, body, file, rawCtx);
+		return jsonResponse(result.status, result.body);
+	}
+	const result = await router.handle(name, body, rawCtx);
+	return jsonResponse(result.status, result.body);
+}
 function createHttpHandler(router, opts) {
-	const hashToName = opts?.rpcHashMap ? new Map(Object.entries(opts.rpcHashMap.procedures).map(([n, h]) => [h, n])) : null;
+	const effectiveHashMap = opts?.rpcHashMap ?? router.rpcHashMap;
+	const hashToName = effectiveHashMap ? new Map(Object.entries(effectiveHashMap.procedures).map(([n, h]) => [h, n])) : null;
 	if (hashToName) hashToName.set("__seam_i18n_query", "__seam_i18n_query");
-	const batchHash = opts?.rpcHashMap?.batch ?? null;
+	const batchHash = effectiveHashMap?.batch ?? null;
+	const hasCtx = router.hasContext();
 	return async (req) => {
 		const url = new URL(req.url, "http://localhost");
 		const { pathname } = url;
+		const rawCtx = hasCtx ? buildRawContext(router.ctxConfig, req.header, url) : void 0;
 		if (req.method === "GET" && pathname === MANIFEST_PATH) {
-			if (opts?.rpcHashMap) return errorResponse(403, "FORBIDDEN", "Manifest disabled");
+			if (effectiveHashMap) return errorResponse(403, "FORBIDDEN", "Manifest disabled");
 			return jsonResponse(200, router.manifest());
 		}
 		if (pathname.startsWith(PROCEDURE_PREFIX)) {
-			let name = pathname.slice(17);
-			if (!name) return errorResponse(404, "NOT_FOUND", "Empty procedure name");
+			const rawName = pathname.slice(17);
+			if (!rawName) return errorResponse(404, "NOT_FOUND", "Empty procedure name");
 			if (req.method === "POST") {
-				if (name === "_batch" || batchHash && name === batchHash) return handleBatchHttp(req, router, hashToName);
-				if (hashToName) {
-					const resolved = hashToName.get(name);
-					if (!resolved) return errorResponse(404, "NOT_FOUND", "Not found");
-					name = resolved;
-				}
-				let body;
-				try {
-					body = await req.body();
-				} catch {
-					return errorResponse(400, "VALIDATION_ERROR", "Invalid JSON body");
-				}
-				const result = await router.handle(name, body);
-				return jsonResponse(result.status, result.body);
+				if (rawName === "_batch" || batchHash && rawName === batchHash) return handleBatchHttp(req, router, hashToName, rawCtx);
+				return handleProcedurePost(req, router, resolveHashName(hashToName, rawName), rawCtx, opts?.sseOptions);
 			}
 			if (req.method === "GET") {
-				if (hashToName) {
-					const resolved = hashToName.get(name);
-					if (!resolved) return errorResponse(404, "NOT_FOUND", "Not found");
-					name = resolved;
-				}
+				const name = resolveHashName(hashToName, rawName);
 				const rawInput = url.searchParams.get("input");
 				let input;
 				try {
@@ -859,7 +1535,7 @@ function createHttpHandler(router, opts) {
 				return {
 					status: 200,
 					headers: SSE_HEADER,
-					stream: sseStream(router, name, input)
+					stream: withSseLifecycle(sseStream(router, name, input, rawCtx), opts?.sseOptions)
 				};
 			}
 		}
@@ -870,7 +1546,7 @@ function createHttpHandler(router, opts) {
 				cookie: req.header("cookie") ?? void 0,
 				acceptLanguage: req.header("accept-language") ?? void 0
 			} : void 0;
-			const result = await router.handlePage(pagePath, headers);
+			const result = await router.handlePage(pagePath, headers, rawCtx);
 			if (result) return {
 				status: result.status,
 				headers: HTML_HEADER,
@@ -895,13 +1571,19 @@ async function drainStream(stream, write) {
 function toWebResponse(result) {
 	if ("stream" in result) {
 		const stream = result.stream;
+		const onCancel = result.onCancel;
 		const encoder = new TextEncoder();
-		const readable = new ReadableStream({ async start(controller) {
-			await drainStream(stream, (chunk) => {
-				controller.enqueue(encoder.encode(chunk));
-			});
-			controller.close();
-		} });
+		const readable = new ReadableStream({
+			async start(controller) {
+				await drainStream(stream, (chunk) => {
+					controller.enqueue(encoder.encode(chunk));
+				});
+				controller.close();
+			},
+			cancel() {
+				onCancel?.();
+			}
+		});
 		return new Response(readable, {
 			status: result.status,
 			headers: result.headers
@@ -915,12 +1597,16 @@ function toWebResponse(result) {
 
 //#endregion
 //#region src/page/build-loader.ts
+function normalizeParamConfig(value) {
+	return typeof value === "string" ? { from: value } : value;
+}
 function buildLoaderFn(config) {
-	return (params) => {
+	return (params, searchParams) => {
 		const input = {};
-		if (config.params) for (const [key, mapping] of Object.entries(config.params)) {
-			const raw = params[key];
-			input[key] = mapping.type === "int" ? Number(raw) : raw;
+		if (config.params) for (const [key, raw_mapping] of Object.entries(config.params)) {
+			const mapping = normalizeParamConfig(raw_mapping);
+			const raw = mapping.from === "query" ? searchParams?.get(key) ?? void 0 : params[key];
+			if (raw !== void 0) input[key] = mapping.type === "int" ? Number(raw) : raw;
 		}
 		return {
 			procedure: config.procedure,
@@ -951,42 +1637,19 @@ function loadLocaleTemplates(entry, distDir) {
 	return result;
 }
 /** Resolve parent chain for a layout, returning outer-to-inner order */
-function resolveLayoutChain(layoutId, layoutEntries, templates, localeTemplatesMap) {
+function resolveLayoutChain(layoutId, layoutEntries, getTemplates) {
 	const chain = [];
 	let currentId = layoutId;
 	while (currentId) {
 		const entry = layoutEntries[currentId];
 		if (!entry) break;
+		const { template, localeTemplates } = getTemplates(currentId, entry);
 		chain.push({
 			id: currentId,
-			template: templates[currentId] ?? "",
-			localeTemplates: localeTemplatesMap[currentId],
-			loaders: buildLoaderFns(entry.loaders ?? {})
-		});
-		currentId = entry.parent;
-	}
-	chain.reverse();
-	return chain;
-}
-/** Resolve layout chain with lazy template getters (re-read from disk on each access) */
-function resolveLayoutChainDev(layoutId, layoutEntries, distDir, defaultLocale) {
-	const chain = [];
-	let currentId = layoutId;
-	while (currentId) {
-		const entry = layoutEntries[currentId];
-		if (!entry) break;
-		const layoutTemplatePath = join(distDir, resolveTemplatePath(entry, defaultLocale));
-		const def = {
-			id: currentId,
-			template: "",
-			localeTemplates: entry.templates ? makeLocaleTemplateGetters(entry.templates, distDir) : void 0,
+			template,
+			localeTemplates,
 			loaders: buildLoaderFns(entry.loaders ?? {})
-		};
-		Object.defineProperty(def, "template", {
-			get: () => readFileSync(layoutTemplatePath, "utf-8"),
-			enumerable: true
 		});
-		chain.push(def);
 		currentId = entry.parent;
 	}
 	chain.reverse();
@@ -1019,6 +1682,22 @@ function mergeI18nKeys(route, layoutEntries) {
 	if (route.i18n_keys) keys.push(...route.i18n_keys);
 	return keys.length > 0 ? keys : void 0;
 }
+/** Load all build artifacts (pages, rpcHashMap, i18n) in one call */
+function loadBuild(distDir) {
+	return {
+		pages: loadBuildOutput(distDir),
+		rpcHashMap: loadRpcHashMap(distDir),
+		i18n: loadI18nMessages(distDir)
+	};
+}
+/** Load all build artifacts with lazy template getters (for dev mode) */
+function loadBuildDev(distDir) {
+	return {
+		pages: loadBuildOutputDev(distDir),
+		rpcHashMap: loadRpcHashMap(distDir),
+		i18n: loadI18nMessages(distDir)
+	};
+}
 /** Load the RPC hash map from build output (returns undefined when obfuscation is off) */
 function loadRpcHashMap(distDir) {
 	const hashMapPath = join(distDir, "rpc-hash-map.json");
@@ -1077,7 +1756,10 @@ function loadBuildOutput(distDir) {
 	for (const [path, entry] of Object.entries(manifest.routes)) {
 		const template = readFileSync(join(distDir, resolveTemplatePath(entry, defaultLocale)), "utf-8");
 		const loaders = buildLoaderFns(entry.loaders);
-		const layoutChain = entry.layout ? resolveLayoutChain(entry.layout, layoutEntries, layoutTemplates, layoutLocaleTemplates) : [];
+		const layoutChain = entry.layout ? resolveLayoutChain(entry.layout, layoutEntries, (id) => ({
+			template: layoutTemplates[id] ?? "",
+			localeTemplates: layoutLocaleTemplates[id]
+		})) : [];
 		const i18nKeys = mergeI18nKeys(entry, layoutEntries);
 		pages[path] = {
 			template,
@@ -1087,7 +1769,8 @@ function loadBuildOutput(distDir) {
 			headMeta: entry.head_meta,
 			dataId: manifest.data_id,
 			i18nKeys,
-			pageAssets: entry.assets
+			pageAssets: entry.assets,
+			projections: entry.projections
 		};
 	}
 	return pages;
@@ -1102,7 +1785,18 @@ function loadBuildOutputDev(distDir) {
 	for (const [path, entry] of Object.entries(manifest.routes)) {
 		const templatePath = join(distDir, resolveTemplatePath(entry, defaultLocale));
 		const loaders = buildLoaderFns(entry.loaders);
-		const layoutChain = entry.layout ? resolveLayoutChainDev(entry.layout, layoutEntries, distDir, defaultLocale) : [];
+		const layoutChain = entry.layout ? resolveLayoutChain(entry.layout, layoutEntries, (id, layoutEntry) => {
+			const tmplPath = join(distDir, resolveTemplatePath(layoutEntry, defaultLocale));
+			const def = {
+				template: "",
+				localeTemplates: layoutEntry.templates ? makeLocaleTemplateGetters(layoutEntry.templates, distDir) : void 0
+			};
+			Object.defineProperty(def, "template", {
+				get: () => readFileSync(tmplPath, "utf-8"),
+				enumerable: true
+			});
+			return def;
+		}) : [];
 		const localeTemplates = entry.templates ? makeLocaleTemplateGetters(entry.templates, distDir) : void 0;
 		const i18nKeys = mergeI18nKeys(entry, layoutEntries);
 		const page = {
@@ -1112,7 +1806,8 @@ function loadBuildOutputDev(distDir) {
 			layoutChain,
 			dataId: manifest.data_id,
 			i18nKeys,
-			pageAssets: entry.assets
+			pageAssets: entry.assets,
+			projections: entry.projections
 		};
 		Object.defineProperty(page, "template", {
 			get: () => readFileSync(templatePath, "utf-8"),
@@ -1184,7 +1879,8 @@ function fromCallback(setup) {
 
 //#endregion
 //#region src/ws.ts
-const DEFAULT_HEARTBEAT_MS = 3e4;
+const DEFAULT_HEARTBEAT_MS = 21e3;
+const DEFAULT_PONG_TIMEOUT_MS = 5e3;
 function sendError(ws, id, code, message) {
 	ws.send(JSON.stringify({
 		id,
@@ -1196,6 +1892,60 @@ function sendError(ws, id, code, message) {
 		}
 	}));
 }
+/** Validate uplink message fields and channel scope */
+function parseUplink(ws, data, channelName) {
+	let msg;
+	try {
+		msg = JSON.parse(data);
+	} catch {
+		sendError(ws, null, "VALIDATION_ERROR", "Invalid JSON");
+		return null;
+	}
+	if (!msg.id || typeof msg.id !== "string") {
+		sendError(ws, null, "VALIDATION_ERROR", "Missing 'id' field");
+		return null;
+	}
+	if (!msg.procedure || typeof msg.procedure !== "string") {
+		sendError(ws, msg.id, "VALIDATION_ERROR", "Missing 'procedure' field");
+		return null;
+	}
+	const prefix = channelName + ".";
+	if (!msg.procedure.startsWith(prefix) || msg.procedure === `${channelName}.events`) {
+		sendError(ws, msg.id, "VALIDATION_ERROR", `Procedure '${msg.procedure}' is not a command of channel '${channelName}'`);
+		return null;
+	}
+	return msg;
+}
+/** Dispatch validated uplink command through the router */
+function dispatchUplink(router, ws, msg, channelInput) {
+	const mergedInput = {
+		...channelInput,
+		...msg.input ?? {}
+	};
+	(async () => {
+		try {
+			const result = await router.handle(msg.procedure, mergedInput);
+			if (result.status === 200) {
+				const envelope = result.body;
+				ws.send(JSON.stringify({
+					id: msg.id,
+					ok: true,
+					data: envelope.data
+				}));
+			} else {
+				const envelope = result.body;
+				ws.send(JSON.stringify({
+					id: msg.id,
+					ok: false,
+					error: envelope.error
+				}));
+			}
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Unknown error";
+			sendError(ws, msg.id, "INTERNAL_ERROR", message);
+		}
+	})();
+}
 /**
 * Start a WebSocket session for a channel.
 *
@@ -1204,9 +1954,24 @@ function sendError(ws, id, code, message) {
 */
 function startChannelWs(router, channelName, channelInput, ws, opts) {
 	const heartbeatMs = opts?.heartbeatInterval ?? DEFAULT_HEARTBEAT_MS;
+	const pongTimeoutMs = opts?.pongTimeout ?? DEFAULT_PONG_TIMEOUT_MS;
 	let closed = false;
+	let pongTimer = null;
 	const heartbeatTimer = setInterval(() => {
-		if (!closed) ws.send(JSON.stringify({ heartbeat: true }));
+		if (closed) return;
+		ws.send(JSON.stringify({ heartbeat: true }));
+		if (ws.ping) {
+			ws.ping();
+			if (pongTimer) clearTimeout(pongTimer);
+			pongTimer = setTimeout(() => {
+				if (!closed) {
+					closed = true;
+					clearInterval(heartbeatTimer);
+					iter.return?.(void 0);
+					ws.close?.();
+				}
+			}, pongTimeoutMs);
+		}
 	}, heartbeatMs);
 	const iter = router.handleSubscription(`${channelName}.events`, channelInput)[Symbol.asyncIterator]();
 	(async () => {
@@ -1237,58 +2002,20 @@ function startChannelWs(router, channelName, channelInput, ws, opts) {
 	return {
 		onMessage(data) {
 			if (closed) return;
-			let msg;
-			try {
-				msg = JSON.parse(data);
-			} catch {
-				sendError(ws, null, "VALIDATION_ERROR", "Invalid JSON");
-				return;
-			}
-			if (!msg.id || typeof msg.id !== "string") {
-				sendError(ws, null, "VALIDATION_ERROR", "Missing 'id' field");
-				return;
-			}
-			if (!msg.procedure || typeof msg.procedure !== "string") {
-				sendError(ws, msg.id, "VALIDATION_ERROR", "Missing 'procedure' field");
-				return;
-			}
-			const prefix = channelName + ".";
-			if (!msg.procedure.startsWith(prefix) || msg.procedure === `${channelName}.events`) {
-				sendError(ws, msg.id, "VALIDATION_ERROR", `Procedure '${msg.procedure}' is not a command of channel '${channelName}'`);
-				return;
+			const msg = parseUplink(ws, data, channelName);
+			if (msg) dispatchUplink(router, ws, msg, channelInput);
+		},
+		onPong() {
+			if (pongTimer) {
+				clearTimeout(pongTimer);
+				pongTimer = null;
 			}
-			const mergedInput = {
-				...channelInput,
-				...msg.input ?? {}
-			};
-			(async () => {
-				try {
-					const result = await router.handle(msg.procedure, mergedInput);
-					if (result.status === 200) {
-						const envelope = result.body;
-						ws.send(JSON.stringify({
-							id: msg.id,
-							ok: true,
-							data: envelope.data
-						}));
-					} else {
-						const envelope = result.body;
-						ws.send(JSON.stringify({
-							id: msg.id,
-							ok: false,
-							error: envelope.error
-						}));
-					}
-				} catch (err) {
-					const message = err instanceof Error ? err.message : "Unknown error";
-					sendError(ws, msg.id, "INTERNAL_ERROR", message);
-				}
-			})();
 		},
 		close() {
 			if (closed) return;
 			closed = true;
 			clearInterval(heartbeatTimer);
+			if (pongTimer) clearTimeout(pongTimer);
 			iter.return?.(void 0);
 		}
 	};
@@ -1361,26 +2088,58 @@ function createStaticHandler(opts) {
 function watchReloadTrigger(distDir, onReload) {
 	const triggerPath = join(distDir, ".reload-trigger");
 	let watcher = null;
+	let closed = false;
+	let pending = [];
+	const notify = () => {
+		onReload();
+		const batch = pending;
+		pending = [];
+		for (const p of batch) p.resolve();
+	};
+	const nextReload = () => {
+		if (closed) return Promise.reject(/* @__PURE__ */ new Error("watcher closed"));
+		return new Promise((resolve, reject) => {
+			pending.push({
+				resolve,
+				reject
+			});
+		});
+	};
+	const closeAll = () => {
+		closed = true;
+		const batch = pending;
+		pending = [];
+		const err = /* @__PURE__ */ new Error("watcher closed");
+		for (const p of batch) p.reject(err);
+	};
 	try {
-		watcher = watch(triggerPath, () => onReload());
+		watcher = watch(triggerPath, () => notify());
 	} catch {
 		const dirWatcher = watch(distDir, (_event, filename) => {
 			if (filename === ".reload-trigger") {
 				dirWatcher.close();
-				watcher = watch(triggerPath, () => onReload());
-				onReload();
+				watcher = watch(triggerPath, () => notify());
+				notify();
 			}
 		});
-		return { close() {
-			dirWatcher.close();
-			watcher?.close();
-		} };
+		return {
+			close() {
+				dirWatcher.close();
+				watcher?.close();
+				closeAll();
+			},
+			nextReload
+		};
 	}
-	return { close() {
-		watcher?.close();
-	} };
+	return {
+		close() {
+			watcher?.close();
+			closeAll();
+		},
+		nextReload
+	};
 }
 
 //#endregion
-export { SeamError, createChannel, createDevProxy, createHttpHandler, createRouter, createStaticHandler, defaultStrategies, definePage, drainStream, fromAcceptLanguage, fromCallback, fromCookie, fromUrlPrefix, fromUrlQuery, loadBuildOutput, loadBuildOutputDev, loadI18nMessages, loadRpcHashMap, resolveChain, serialize, sseCompleteEvent, sseDataEvent, sseErrorEvent, startChannelWs, t, toWebResponse, watchReloadTrigger };
+export { SeamError, buildRawContext, command, contextHasExtracts, createChannel, createDevProxy, createHttpHandler, createRouter, createSeamRouter, createStaticHandler, defaultStrategies, definePage, drainStream, extract, fromAcceptLanguage, fromCallback, fromCookie, fromUrlPrefix, fromUrlQuery, isLoaderError, loadBuild, loadBuildDev, loadBuildOutput, loadBuildOutputDev, loadI18nMessages, loadRpcHashMap, parseCookieHeader, query, resolveChain, serialize, sseCompleteEvent, sseDataEvent, sseDataEventWithId, sseErrorEvent, startChannelWs, stream, subscription, t, toWebResponse, upload, watchReloadTrigger };
 //# sourceMappingURL=index.js.map