@tyndall/core 0.0.1

package/dist/props.d.ts

@@ -0,0 +1,2 @@
+export declare const serializeProps: (props: Record<string, unknown>) => string;
+//# sourceMappingURL=props.d.ts.map

package/dist/props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../src/props.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAO/D,CAAC"}

package/dist/props.js

@@ -0,0 +1,14 @@
+const escapeJson = (value) => value
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+export const serializeProps = (props) => {
+    const json = JSON.stringify(props);
+    if (json === undefined) {
+        return "null";
+    }
+    // Important: escape characters that can break out of a script tag.
+    return escapeJson(json);
+};

package/dist/render-policy.d.ts

@@ -0,0 +1,8 @@
+export type AppBuildMode = "ssg" | "ssr";
+export type PolicyRenderMode = "csr" | "ssr" | "auto";
+export interface RenderPolicyDecision {
+    mode: "csr" | "ssr";
+    warnings: string[];
+}
+export declare const evaluateRenderPolicy: (appMode: AppBuildMode, policyRender?: PolicyRenderMode) => RenderPolicyDecision;
+//# sourceMappingURL=render-policy.d.ts.map

package/dist/render-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-policy.d.ts","sourceRoot":"","sources":["../src/render-policy.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,CAAC;AACzC,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,oBAAoB,GAC/B,SAAS,YAAY,EACrB,eAAc,gBAAyB,KACtC,oBAcF,CAAC"}

package/dist/render-policy.js

@@ -0,0 +1,12 @@
+export const evaluateRenderPolicy = (appMode, policyRender = "auto") => {
+    const warnings = [];
+    if (policyRender === "auto") {
+        return { mode: appMode === "ssg" ? "csr" : "ssr", warnings };
+    }
+    if (appMode === "ssg" && policyRender === "ssr") {
+        // Important: SSG builds cannot satisfy SSR policy; fall back to CSR and warn.
+        warnings.push("SSR policy requested for SSG build; falling back to CSR.");
+        return { mode: "csr", warnings };
+    }
+    return { mode: policyRender, warnings };
+};

package/dist/resolver-fallback.d.ts

@@ -0,0 +1,49 @@
+import { type MatchResult, type RouteGraph } from "./router.js";
+import { type AppBuildMode, type PolicyRenderMode } from "./render-policy.js";
+export interface ResolverFallbackPolicy {
+    dynamicRoutePrefixes?: string[];
+    forceDynamic?: boolean;
+}
+export type DynamicManifestResolver = (pathname: string) => Promise<unknown | null>;
+export type RouteFallbackResult = {
+    type: "file";
+    match: MatchResult;
+} | {
+    type: "dynamic";
+    envelope: unknown;
+} | {
+    type: "notfound";
+};
+export type DynamicPolicyRenderMode = PolicyRenderMode | "redirect";
+export interface DynamicFallbackPolicy {
+    render?: DynamicPolicyRenderMode;
+    redirect?: string;
+}
+export type RoutePolicyFallbackResult = {
+    type: "file";
+    match: MatchResult;
+} | {
+    type: "dynamic";
+    envelope: unknown;
+    mode: "csr" | "ssr";
+    warnings: string[];
+} | {
+    type: "redirect";
+    envelope: unknown;
+    location: string;
+} | {
+    type: "notfound";
+};
+export interface ResolveRouteWithFallbackOptions {
+    pathname: string;
+    routeGraph?: RouteGraph;
+    dynamicResolver?: DynamicManifestResolver;
+    policy?: ResolverFallbackPolicy;
+}
+export interface ResolveRouteWithPolicyFallbackOptions extends ResolveRouteWithFallbackOptions {
+    appMode?: AppBuildMode;
+}
+export declare const shouldForceDynamicFallback: (pathname: string, policy?: ResolverFallbackPolicy) => boolean;
+export declare const resolveRouteWithFallback: (options: ResolveRouteWithFallbackOptions) => Promise<RouteFallbackResult>;
+export declare const resolveRouteWithPolicyFallback: (options: ResolveRouteWithPolicyFallbackOptions) => Promise<RoutePolicyFallbackResult>;
+//# sourceMappingURL=resolver-fallback.d.ts.map

package/dist/resolver-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver-fallback.d.ts","sourceRoot":"","sources":["../src/resolver-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,sBAAsB;IACrC,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,uBAAuB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;AAEpF,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAEzB,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAEpE,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAC/E;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAEzB,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,eAAe,CAAC,EAAE,uBAAuB,CAAC;IAC1C,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC;AAED,MAAM,WAAW,qCACf,SAAQ,+BAA+B;IACvC,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAuBD,eAAO,MAAM,0BAA0B,GACrC,UAAU,MAAM,EAChB,SAAS,sBAAsB,KAC9B,OAUF,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,SAAS,+BAA+B,KACvC,OAAO,CAAC,mBAAmB,CAkB7B,CAAC;AA4BF,eAAO,MAAM,8BAA8B,GACzC,SAAS,qCAAqC,KAC7C,OAAO,CAAC,yBAAyB,CA6BnC,CAAC"}

package/dist/resolver-fallback.js

@@ -0,0 +1,99 @@
+import { matchRoute } from "./router.js";
+import { evaluateRenderPolicy, } from "./render-policy.js";
+const normalizePathname = (value) => {
+    const trimmed = value.split("?")[0].split("#")[0];
+    if (!trimmed.startsWith("/")) {
+        return `/${trimmed}`;
+    }
+    return trimmed;
+};
+const matchesPrefix = (pathname, prefix) => {
+    if (!prefix) {
+        return false;
+    }
+    if (prefix === "/") {
+        return true;
+    }
+    if (!prefix.startsWith("/")) {
+        prefix = `/${prefix}`;
+    }
+    return pathname === prefix || pathname.startsWith(`${prefix}/`);
+};
+export const shouldForceDynamicFallback = (pathname, policy) => {
+    if (!policy) {
+        return false;
+    }
+    if (policy.forceDynamic) {
+        return true;
+    }
+    const prefixes = policy.dynamicRoutePrefixes ?? [];
+    const normalized = normalizePathname(pathname);
+    return prefixes.some((prefix) => matchesPrefix(normalized, prefix));
+};
+export const resolveRouteWithFallback = async (options) => {
+    const pathname = normalizePathname(options.pathname);
+    const match = options.routeGraph ? matchRoute(pathname, options.routeGraph) : null;
+    const forceDynamic = shouldForceDynamicFallback(pathname, options.policy);
+    // Important: forced dynamic bypasses file matches to honor policy overrides.
+    if (match && !forceDynamic) {
+        return { type: "file", match };
+    }
+    if (options.dynamicResolver) {
+        const envelope = await options.dynamicResolver(pathname);
+        if (envelope) {
+            return { type: "dynamic", envelope };
+        }
+    }
+    return { type: "notfound" };
+};
+const POLICY_RENDER_VALUES = new Set([
+    "auto",
+    "csr",
+    "ssr",
+    "redirect",
+]);
+const readDynamicFallbackPolicy = (envelope) => {
+    if (!envelope || typeof envelope !== "object") {
+        return {};
+    }
+    const candidate = envelope;
+    if (!candidate.policy || typeof candidate.policy !== "object") {
+        return {};
+    }
+    const policy = candidate.policy;
+    const normalized = {};
+    if (typeof policy.render === "string" && POLICY_RENDER_VALUES.has(policy.render)) {
+        normalized.render = policy.render;
+    }
+    if (typeof policy.redirect === "string" && policy.redirect.length > 0) {
+        normalized.redirect = policy.redirect;
+    }
+    return normalized;
+};
+export const resolveRouteWithPolicyFallback = async (options) => {
+    const resolved = await resolveRouteWithFallback(options);
+    if (resolved.type !== "dynamic") {
+        return resolved;
+    }
+    const policy = readDynamicFallbackPolicy(resolved.envelope);
+    const warnings = [];
+    if (policy.render === "redirect") {
+        if (policy.redirect) {
+            return {
+                type: "redirect",
+                envelope: resolved.envelope,
+                location: policy.redirect,
+            };
+        }
+        // Mirror router semantics: redirect without target falls back to auto.
+        warnings.push("Redirect policy missing target; falling back to auto.");
+    }
+    const policyRender = policy.render && policy.render !== "redirect" ? policy.render : "auto";
+    const decision = evaluateRenderPolicy(options.appMode ?? "ssg", policyRender);
+    return {
+        type: "dynamic",
+        envelope: resolved.envelope,
+        mode: decision.mode,
+        warnings: [...warnings, ...decision.warnings],
+    };
+};

package/dist/route-graph.d.ts

@@ -0,0 +1,9 @@
+import type { RouteGraph } from "./router.js";
+export interface RouteGraphOptions {
+    routesDir: string;
+    extensions?: string[];
+    routeMeta?: boolean;
+    nestedLayouts?: boolean;
+}
+export declare const createRouteGraph: (options: RouteGraphOptions) => Promise<RouteGraph>;
+//# sourceMappingURL=route-graph.d.ts.map

package/dist/route-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-graph.d.ts","sourceRoot":"","sources":["../src/route-graph.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAA0C,MAAM,aAAa,CAAC;AAKtF,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAuED,eAAO,MAAM,gBAAgB,GAAU,SAAS,iBAAiB,KAAG,OAAO,CAAC,UAAU,CA0GrF,CAAC"}

package/dist/route-graph.js

@@ -0,0 +1,157 @@
+import { readdir } from "node:fs/promises";
+import { extname, join, relative, sep } from "node:path";
+import { HyperError } from "./errors.js";
+import { loadRouteMeta, mergeRoutePolicies } from "./route-meta.js";
+import { collectRouteLayouts } from "./layouts.js";
+const defaultExtensions = [".tsx", ".ts", ".jsx", ".js"];
+const isGroupSegment = (segment) => segment.startsWith("(") && segment.endsWith(")") && segment.length > 2;
+const parseSegment = (segment) => {
+    if (isGroupSegment(segment)) {
+        return null;
+    }
+    if (segment.startsWith("[...") && segment.endsWith("]")) {
+        const name = segment.slice(4, -1).trim();
+        if (!name) {
+            throw new HyperError("ROUTE_INVALID", "Catch-all segment name is required.", {
+                segment,
+            });
+        }
+        return { type: "catchAll", name };
+    }
+    if (segment.startsWith("[") && segment.endsWith("]")) {
+        const name = segment.slice(1, -1).trim();
+        if (!name) {
+            throw new HyperError("ROUTE_INVALID", "Dynamic segment name is required.", {
+                segment,
+            });
+        }
+        return { type: "dynamic", name };
+    }
+    return { type: "static", value: segment };
+};
+const segmentsToId = (segments) => {
+    if (segments.length === 0) {
+        return "/";
+    }
+    return ("/" +
+        segments
+            .map((segment) => {
+            if (segment.type === "static") {
+                return segment.value;
+            }
+            if (segment.type === "dynamic") {
+                return `:${segment.name}`;
+            }
+            return `*${segment.name}`;
+        })
+            .join("/"));
+};
+const walkFiles = async (dir) => {
+    const entries = await readdir(dir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await walkFiles(fullPath)));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+};
+export const createRouteGraph = async (options) => {
+    const extensionList = options.extensions ?? defaultExtensions;
+    const extensions = new Set(extensionList);
+    const enableRouteMeta = options.routeMeta ?? true;
+    const enableNestedLayouts = options.nestedLayouts ?? false;
+    const files = await walkFiles(options.routesDir);
+    const routes = [];
+    const seenIds = new Set();
+    const routeMetaFiles = new Map();
+    const routeMetaCache = new Map();
+    const extensionRank = (extension) => {
+        const index = extensionList.indexOf(extension);
+        return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+    };
+    const loadCachedRouteMeta = async (filePath) => {
+        if (routeMetaCache.has(filePath)) {
+            return routeMetaCache.get(filePath) ?? null;
+        }
+        const policy = await loadRouteMeta(filePath);
+        routeMetaCache.set(filePath, policy);
+        return policy;
+    };
+    for (const filePath of files) {
+        const extension = extname(filePath);
+        if (!extensions.has(extension)) {
+            continue;
+        }
+        const relativePath = relative(options.routesDir, filePath);
+        const parts = relativePath.split(sep);
+        const fileName = parts.pop();
+        if (!fileName) {
+            continue;
+        }
+        const baseName = fileName.slice(0, -extension.length);
+        if (baseName === "_route") {
+            const dirKey = parts.join(sep);
+            const rank = extensionRank(extension);
+            const existing = routeMetaFiles.get(dirKey);
+            if (!existing || rank < existing.rank) {
+                routeMetaFiles.set(dirKey, { filePath, rank });
+            }
+            continue;
+        }
+        if (baseName.startsWith("_")) {
+            continue;
+        }
+        const segments = [];
+        for (const part of parts) {
+            const segment = parseSegment(part);
+            if (segment) {
+                segments.push(segment);
+            }
+        }
+        if (baseName !== "index") {
+            const segment = parseSegment(baseName);
+            if (segment) {
+                segments.push(segment);
+            }
+        }
+        const id = segmentsToId(segments);
+        // Important: duplicate routes indicate ambiguous behavior and must be rejected.
+        if (seenIds.has(id)) {
+            throw new HyperError("ROUTE_DUPLICATE", `Duplicate route detected: ${id}`, { id });
+        }
+        seenIds.add(id);
+        let policy;
+        if (enableRouteMeta && routeMetaFiles.size > 0) {
+            const policies = [];
+            for (let index = 0; index <= parts.length; index += 1) {
+                const dirKey = parts.slice(0, index).join(sep);
+                const metaEntry = routeMetaFiles.get(dirKey);
+                if (!metaEntry) {
+                    continue;
+                }
+                const metaPolicy = await loadCachedRouteMeta(metaEntry.filePath);
+                if (metaPolicy) {
+                    policies.push(metaPolicy);
+                }
+            }
+            if (policies.length > 0) {
+                policy = mergeRoutePolicies(policies);
+            }
+        }
+        const record = { id, filePath, segments, policy };
+        if (enableNestedLayouts) {
+            const resolution = collectRouteLayouts(filePath, options.routesDir, extensionList);
+            record.layoutFiles = resolution.layoutFiles;
+        }
+        routes.push(record);
+    }
+    // Deterministic ordering ensures stable route ids and reproducible builds.
+    routes.sort((a, b) => a.id.localeCompare(b.id));
+    return { routes };
+};

package/dist/route-meta.d.ts

@@ -0,0 +1,4 @@
+import type { RoutePolicy } from "./router.js";
+export declare const mergeRoutePolicies: (policies: RoutePolicy[]) => RoutePolicy;
+export declare const loadRouteMeta: (filePath: string) => Promise<RoutePolicy | null>;
+//# sourceMappingURL=route-meta.d.ts.map

package/dist/route-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-meta.d.ts","sourceRoot":"","sources":["../src/route-meta.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA6B/C,eAAO,MAAM,kBAAkB,GAAI,UAAU,WAAW,EAAE,KAAG,WAM5D,CAAC;AAEF,eAAO,MAAM,aAAa,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAyBhF,CAAC"}

package/dist/route-meta.js

@@ -0,0 +1,48 @@
+import { pathToFileURL } from "node:url";
+import { HyperError } from "./errors.js";
+const isPlainObject = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+const mergeObjects = (base, override) => {
+    const next = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (value === undefined) {
+            continue;
+        }
+        const previous = next[key];
+        if (isPlainObject(previous) && isPlainObject(value)) {
+            next[key] = mergeObjects(previous, value);
+        }
+        else {
+            next[key] = value;
+        }
+    }
+    return next;
+};
+export const mergeRoutePolicies = (policies) => {
+    // Important: merge root→leaf so deeper routes override parents.
+    return policies.reduce((acc, policy) => mergeObjects(acc, policy), {});
+};
+export const loadRouteMeta = async (filePath) => {
+    try {
+        const module = await import(pathToFileURL(filePath).href);
+        const policy = module.route ?? module.default;
+        if (policy === undefined || policy === null) {
+            return null;
+        }
+        if (!isPlainObject(policy)) {
+            throw new HyperError("ROUTE_META_INVALID", "Route meta must export a plain object as `route`.", { filePath });
+        }
+        return policy;
+    }
+    catch (error) {
+        if (error instanceof HyperError) {
+            throw error;
+        }
+        throw new HyperError("ROUTE_META_LOAD_FAILED", "Failed to load route meta module.", { filePath, cause: error instanceof Error ? error.message : String(error) });
+    }
+};

package/dist/router.d.ts

@@ -0,0 +1,27 @@
+export type RouteSegment = {
+    type: "static";
+    value: string;
+} | {
+    type: "dynamic";
+    name: string;
+} | {
+    type: "catchAll";
+    name: string;
+};
+export type RoutePolicy = Record<string, unknown>;
+export interface RouteRecord {
+    id: string;
+    filePath: string;
+    segments: RouteSegment[];
+    policy?: RoutePolicy;
+    layoutFiles?: string[];
+}
+export interface RouteGraph {
+    routes: RouteRecord[];
+}
+export interface MatchResult {
+    route: RouteRecord;
+    params: Record<string, string | string[]>;
+}
+export declare const matchRoute: (pathname: string, routeGraph: RouteGraph) => MatchResult | null;
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;CAC3C;AAwFD,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,EAAE,YAAY,UAAU,KAAG,WAAW,GAAG,IAanF,CAAC"}

package/dist/router.js

@@ -0,0 +1,83 @@
+const normalizePathname = (pathname) => {
+    const clean = pathname.split("?")[0]?.split("#")[0] ?? "";
+    if (!clean) {
+        return "/";
+    }
+    const withSlash = clean.startsWith("/") ? clean : `/${clean}`;
+    if (withSlash.length > 1 && withSlash.endsWith("/")) {
+        return withSlash.slice(0, -1);
+    }
+    return withSlash;
+};
+const splitPath = (pathname) => normalizePathname(pathname)
+    .split("/")
+    .filter((segment) => segment.length > 0);
+const routePriority = (route) => {
+    let hasDynamic = false;
+    let hasCatchAll = false;
+    for (const segment of route.segments) {
+        if (segment.type === "catchAll") {
+            hasCatchAll = true;
+        }
+        if (segment.type === "dynamic") {
+            hasDynamic = true;
+        }
+    }
+    const tier = hasCatchAll ? 2 : hasDynamic ? 1 : 0;
+    return { tier, length: route.segments.length, id: route.id };
+};
+const compareRoutes = (left, right) => {
+    const a = routePriority(left);
+    const b = routePriority(right);
+    if (a.tier !== b.tier) {
+        return a.tier - b.tier;
+    }
+    if (a.length !== b.length) {
+        return b.length - a.length;
+    }
+    return a.id.localeCompare(b.id);
+};
+const matchSegments = (segments, pathnameSegments) => {
+    const params = {};
+    let index = 0;
+    for (const segment of segments) {
+        if (segment.type === "catchAll") {
+            // Important: catch-all requires at least one segment (non-optional catch-all).
+            const rest = pathnameSegments.slice(index);
+            if (rest.length === 0) {
+                return null;
+            }
+            params[segment.name] = rest;
+            return { params };
+        }
+        const value = pathnameSegments[index];
+        if (!value) {
+            return null;
+        }
+        if (segment.type === "static") {
+            if (segment.value !== value) {
+                return null;
+            }
+        }
+        if (segment.type === "dynamic") {
+            params[segment.name] = value;
+        }
+        index += 1;
+    }
+    if (index !== pathnameSegments.length) {
+        return null;
+    }
+    return { params };
+};
+export const matchRoute = (pathname, routeGraph) => {
+    // Critical: normalize and apply stable priority order to avoid mismatched routing.
+    const segments = splitPath(pathname);
+    const orderedRoutes = [...routeGraph.routes].sort(compareRoutes);
+    for (const route of orderedRoutes) {
+        const result = matchSegments(route.segments, segments);
+        if (result) {
+            return { route, params: result.params };
+        }
+    }
+    return null;
+};

package/dist/ui-adapter.d.ts

@@ -0,0 +1,67 @@
+import type { HeadDescriptor, RouteParams } from "./page-api.js";
+import type { RouteGraph } from "./router.js";
+export type EntrySpec = string;
+export interface UIAdapterEntryContext {
+    routeId?: string;
+    routeGraph?: RouteGraph;
+    basePath?: string;
+    rootDir?: string;
+    entryDir?: string;
+    routeRoot?: string;
+    chunks?: Record<string, unknown>;
+    ssrAdapter?: string;
+    uiOptions?: Record<string, unknown>;
+    adapterOptions?: Record<string, unknown>;
+}
+export interface UIAdapterRenderContext {
+    routeId: string;
+    params?: RouteParams;
+    props: Record<string, unknown>;
+}
+export interface UIAdapterRenderResult {
+    html: string;
+    head?: HeadDescriptor;
+    status?: number;
+    headers?: Record<string, string>;
+}
+export interface UIAdapterStreamTarget {
+    write: (chunk: string | Uint8Array) => void;
+    end: () => void;
+}
+export interface UIAdapterStream {
+    pipe: (target: UIAdapterStreamTarget, options?: {
+        end?: boolean;
+    }) => void;
+    on?: (event: string, listener: (...args: unknown[]) => void) => void;
+    once?: (event: string, listener: (...args: unknown[]) => void) => void;
+    off?: (event: string, listener: (...args: unknown[]) => void) => void;
+    removeListener?: (event: string, listener: (...args: unknown[]) => void) => void;
+}
+export interface UIAdapterRenderStreamResult {
+    stream: UIAdapterStream;
+    head?: HeadDescriptor;
+    status?: number;
+    headers?: Record<string, string>;
+    abort?: (reason?: unknown) => void;
+}
+export interface UIAdapter {
+    name: string;
+    createClientEntry?: (ctx: UIAdapterEntryContext) => EntrySpec;
+    createServerEntry?: (ctx: UIAdapterEntryContext) => EntrySpec;
+    renderToHtml?: (ctx: UIAdapterRenderContext) => Promise<UIAdapterRenderResult> | UIAdapterRenderResult;
+    renderToStream?: (ctx: UIAdapterRenderContext) => Promise<UIAdapterRenderStreamResult> | UIAdapterRenderStreamResult;
+    serializeProps?: (props: Record<string, unknown>) => string;
+    getHead?: (ctx: UIAdapterRenderContext) => HeadDescriptor;
+    hmrIntegration?: HmrIntegration;
+}
+export type UIAdapterFactory = (options: Record<string, unknown>) => UIAdapter;
+export type UIAdapterRegistry = Record<string, UIAdapterFactory>;
+export type HmrRefreshBoundary = (...args: unknown[]) => unknown;
+export type HmrOverlayHandler = (...args: unknown[]) => unknown;
+export interface HmrIntegration {
+    refreshBoundary?: HmrRefreshBoundary;
+    overlay?: HmrOverlayHandler;
+}
+export declare const resolveUIAdapter: (adapter: string | UIAdapterFactory, options?: Record<string, unknown>, registry?: UIAdapterRegistry) => UIAdapter;
+export declare const resolveHmrIntegration: (adapter?: Pick<UIAdapter, "hmrIntegration">) => HmrIntegration;
+//# sourceMappingURL=ui-adapter.d.ts.map

package/dist/ui-adapter.d.ts.map

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

package/dist/ui-adapter.js

@@ -0,0 +1,27 @@
+import { HyperError } from "./errors.js";
+const assertValidAdapter = (adapter, source) => {
+    if (!adapter || typeof adapter !== "object") {
+        throw new HyperError("CONFIG_INVALID", `UI adapter factory must return an object (${source}).`);
+    }
+    if (!adapter.name) {
+        throw new HyperError("CONFIG_INVALID", `UI adapter must declare a name (${source}).`);
+    }
+};
+export const resolveUIAdapter = (adapter, options = {}, registry = {}) => {
+    if (typeof adapter === "function") {
+        const resolved = adapter(options);
+        assertValidAdapter(resolved, "factory");
+        return resolved;
+    }
+    const factory = registry[adapter];
+    if (!factory) {
+        throw new HyperError("CONFIG_INVALID", `Unknown UI adapter: ${adapter}`, {
+            adapter,
+            available: Object.keys(registry),
+        });
+    }
+    const resolved = factory(options);
+    assertValidAdapter(resolved, adapter);
+    return resolved;
+};
+export const resolveHmrIntegration = (adapter) => adapter?.hmrIntegration ?? {};