@real-router/svelte 0.10.1 → 0.11.0

package/dist/composables/useDeferred.svelte.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Read a deferred promise published by `defer({ deferred: { <key>: Promise } })`
+ * inside an SSR data loader. Returns the Promise — feed straight into Svelte's
+ * native `{#await}` block, or use `<Await name="key">` (this package) for the
+ * cross-adapter shape.
+ *
+ * ```svelte
+ * <script>
+ *   import { useDeferred } from "@real-router/svelte/ssr";
+ *   const reviewsPromise = useDeferred("reviews");
+ * </script>
+ *
+ * {#await reviewsPromise}
+ *   <Spinner />
+ * {:then reviews}
+ *   <ReviewList items={reviews} />
+ * {/await}
+ * ```
+ *
+ * Returns a forever-pending promise when the key is missing — surfaces
+ * loader/consumer key drift as a visible {#await} loading state rather than
+ * a silent runtime error.
+ */
+export declare function useDeferred<T = unknown>(key: string): Promise<T>;

package/dist/composables/useDeferred.svelte.js

@@ -0,0 +1,34 @@
+import { useRoute } from "./useRoute.svelte";
+const NEVER_PROMISE = new Promise(() => {
+    // Intentionally never resolves — surfaces a forever-pending {#await} block
+    // when a key is requested that the loader never declared.
+});
+/**
+ * Read a deferred promise published by `defer({ deferred: { <key>: Promise } })`
+ * inside an SSR data loader. Returns the Promise — feed straight into Svelte's
+ * native `{#await}` block, or use `<Await name="key">` (this package) for the
+ * cross-adapter shape.
+ *
+ * ```svelte
+ * <script>
+ *   import { useDeferred } from "@real-router/svelte/ssr";
+ *   const reviewsPromise = useDeferred("reviews");
+ * </script>
+ *
+ * {#await reviewsPromise}
+ *   <Spinner />
+ * {:then reviews}
+ *   <ReviewList items={reviews} />
+ * {/await}
+ * ```
+ *
+ * Returns a forever-pending promise when the key is missing — surfaces
+ * loader/consumer key drift as a visible {#await} loading state rather than
+ * a silent runtime error.
+ */
+export function useDeferred(key) {
+    const { route } = useRoute();
+    const context = route.current.context;
+    const deferred = context.ssrDataDeferred;
+    return (deferred?.[key] ?? NEVER_PROMISE);
+}

package/dist/composables/useRoute.svelte.d.ts

@@ -1,7 +1,14 @@
 import type { RouteContext } from "../types";
 import type { Params, State } from "@real-router/core";
-export declare const useRoute: <P extends Params = Params>() => Omit<RouteContext<P>, "route"> & {
+/**
+ * `useRoute()`'s return type: same shape as `RouteContext<P>` but with
+ * `route.current` narrowed to non-nullable `State<P>` (the composable's
+ * `if (!ctx.route.current) throw` guard makes this safe).
+ */
+type ActiveRouteContext<P extends Params> = Omit<RouteContext<P>, "route"> & {
     route: {
         readonly current: State<P>;
     };
 };
+export declare const useRoute: <P extends Params = Params>() => ActiveRouteContext<P>;
+export {};

package/dist/context.d.ts

@@ -1,4 +1,5 @@
 export declare const ROUTER_KEY = "real-router:router";
 export declare const NAVIGATOR_KEY = "real-router:navigator";
 export declare const ROUTE_KEY = "real-router:route";
+export declare const HTTP_STATUS_KEY = "real-router:http-status-sink";
 export declare function getContextOrThrow<T>(key: string, consumerName: string): T;

package/dist/context.js

@@ -2,6 +2,7 @@ import { getContext } from "svelte";
 export const ROUTER_KEY = "real-router:router";
 export const NAVIGATOR_KEY = "real-router:navigator";
 export const ROUTE_KEY = "real-router:route";
+export const HTTP_STATUS_KEY = "real-router:http-status-sink";
 // The type parameter is used by the caller to narrow the return type.
 // ESLint's no-unnecessary-type-parameters sees only a single textual use of T
 // (the return type) — but each call site supplies a different T, so it is not

package/dist/dom-utils/__test-helpers/expected-fragment.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Test helper: mirror of `encodeFragmentInline` from `link-utils.ts` used by
+ * property tests in every adapter (`packages/{vue,preact,react,solid}/tests/
+ * property/linkUtils.properties.ts` and `packages/svelte/tests/property/
+ * buildHref.properties.ts`).
+ *
+ * Why a mirror, not an import of the real function: a property test that uses
+ * the production implementation to compute its own expected value is a
+ * tautology — any regression in `encodeFragmentInline` would be invisible.
+ * We hand-roll the same algorithm so the test asserts an independent
+ * derivation. Drift between this mirror and `encodeFragmentInline` is exactly
+ * the signal property tests are supposed to surface.
+ *
+ * This file lives under `__test-helpers/` so the sync-dom-utils script can
+ * exclude it from the Angular copy (it ships no production code), and so
+ * bundlers (tsdown, svelte-package) tree-shake it out — nothing in
+ * `src/index.ts` of any adapter imports from this directory.
+ */
+/**
+ * Compute the expected fragment portion of an href for a given raw hash input.
+ *
+ * Mirrors the contract of `encodeFragmentInline`:
+ *  1. If input contains `%XX`, try `decodeURIComponent` → `encodeURI` (idempotent
+ *     re-encoding so consumers can copy-paste `location.hash` back in without
+ *     `%20` becoming `%2520`).
+ *  2. If `decodeURIComponent` throws (malformed `%XX`), fall through to plain
+ *     `encodeURI` on the original input.
+ *  3. Defensive `#` → `%23` (encodeURI does not encode `#`).
+ */
+export declare function computeExpectedFragment(rawHash: string): string;

package/dist/dom-utils/__test-helpers/expected-fragment.js

@@ -0,0 +1,43 @@
+/**
+ * Test helper: mirror of `encodeFragmentInline` from `link-utils.ts` used by
+ * property tests in every adapter (`packages/{vue,preact,react,solid}/tests/
+ * property/linkUtils.properties.ts` and `packages/svelte/tests/property/
+ * buildHref.properties.ts`).
+ *
+ * Why a mirror, not an import of the real function: a property test that uses
+ * the production implementation to compute its own expected value is a
+ * tautology — any regression in `encodeFragmentInline` would be invisible.
+ * We hand-roll the same algorithm so the test asserts an independent
+ * derivation. Drift between this mirror and `encodeFragmentInline` is exactly
+ * the signal property tests are supposed to surface.
+ *
+ * This file lives under `__test-helpers/` so the sync-dom-utils script can
+ * exclude it from the Angular copy (it ships no production code), and so
+ * bundlers (tsdown, svelte-package) tree-shake it out — nothing in
+ * `src/index.ts` of any adapter imports from this directory.
+ */
+const PERCENT_ESCAPE_PROBE = /%[\dA-Fa-f]{2}/;
+/**
+ * Compute the expected fragment portion of an href for a given raw hash input.
+ *
+ * Mirrors the contract of `encodeFragmentInline`:
+ *  1. If input contains `%XX`, try `decodeURIComponent` → `encodeURI` (idempotent
+ *     re-encoding so consumers can copy-paste `location.hash` back in without
+ *     `%20` becoming `%2520`).
+ *  2. If `decodeURIComponent` throws (malformed `%XX`), fall through to plain
+ *     `encodeURI` on the original input.
+ *  3. Defensive `#` → `%23` (encodeURI does not encode `#`).
+ */
+export function computeExpectedFragment(rawHash) {
+    let roundtrip = rawHash;
+    if (PERCENT_ESCAPE_PROBE.test(rawHash)) {
+        try {
+            roundtrip = decodeURIComponent(rawHash);
+        }
+        catch {
+            // Malformed %XX — encodeFragmentInline falls through to plain
+            // encodeURI on the original input, so do the same here.
+        }
+    }
+    return encodeURI(roundtrip).replaceAll("#", "%23");
+}

package/dist/dom-utils/__test-helpers/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Test-only barrel. Intentionally NOT re-exported from
+ * `shared/dom-utils/index.ts` so the helpers don't leak into adapters'
+ * public API surface. Property tests import from this path directly:
+ *
+ *   import { computeExpectedFragment } from "../../src/dom-utils/__test-helpers";
+ */
+export { computeExpectedFragment } from "./expected-fragment.js";

package/dist/dom-utils/__test-helpers/index.js

@@ -0,0 +1,8 @@
+/**
+ * Test-only barrel. Intentionally NOT re-exported from
+ * `shared/dom-utils/index.ts` so the helpers don't leak into adapters'
+ * public API surface. Property tests import from this path directly:
+ *
+ *   import { computeExpectedFragment } from "../../src/dom-utils/__test-helpers";
+ */
+export { computeExpectedFragment } from "./expected-fragment.js";

package/dist/dom-utils/link-utils.d.ts

@@ -18,5 +18,28 @@ export declare function buildHref(router: Router, routeName: string, routeParams
 }): string | undefined;
 export declare function navigateWithHash(router: Router, routeName: string, routeParams: Params, hash: string | undefined, extraOptions?: NavigationOptions): Promise<State>;
 export declare function buildActiveClassName(isActive: boolean, activeClassName: string | undefined, baseClassName: string | undefined): string | undefined;
+/**
+ * One-level structural equality using `Object.is` per key.
+ *
+ * **String-keyed properties only (Mini-sprint E.3 — audit-5 §4.2 #3).**
+ * Implementation walks `Object.keys()` which by spec returns only
+ * enumerable own STRING keys. Symbol-keyed properties — created via
+ * `obj[Symbol("brand")] = value` or `{ [Symbol(...)]: value }` — are
+ * NOT compared. Two records that differ only in a Symbol-keyed value
+ * will compare as equal.
+ *
+ * This is intentional: route params and Link options are documented as
+ * string-keyed primitives (string | number | boolean) — Symbol-keyed
+ * metadata (e.g. brand markers, private state) doesn't belong in a
+ * cache-key comparison. Switching to `Reflect.ownKeys()` would extend
+ * the contract to symbols at the cost of one extra allocation per call
+ * (Reflect.ownKeys composes string-keys + symbol-keys arrays). If a
+ * consumer relies on symbol-keyed metadata for navigation
+ * disambiguation, they should encode it into a string key instead.
+ *
+ * Mirrors React's `shallowEqual` (packages/shared/shallowEqual.js) in
+ * both the string-keys-only semantics and the `hasOwnProperty` guard
+ * below.
+ */
 export declare function shallowEqual(prev: object | undefined, next: object | undefined): boolean;
 export declare function applyLinkA11y(element: HTMLElement | null | undefined): void;

package/dist/dom-utils/link-utils.js

@@ -5,14 +5,39 @@ export function shouldNavigate(evt) {
         !evt.ctrlKey &&
         !evt.shiftKey);
 }
+// Matches a single percent-escape triple (`%` + two hex digits). Used as
+// the "already-encoded" probe in `encodeFragmentInline` below — see the
+// idempotency rationale there.
+const PERCENT_ESCAPE_PROBE = /%[\dA-Fa-f]{2}/;
 /**
  * RFC 3986 fragment encoding: preserve sub-delims (`&`, `=`, `?`, `:`),
  * encode space, `%`, control chars, non-ASCII via encodeURI; defensively
  * escape `#` (encodeURI does not). Mirrors `encodeHashFragment` in
  * `shared/browser-env/url-context.ts` — duplicated here because the
  * shared/dom-utils symlink graph does not reach shared/browser-env.
+ *
+ * **Idempotency for pre-encoded input (audit-2026-05-17 §5 MEDIUM E.1).**
+ * The doc-comment on `<Link hash>` says the value is a "decoded fragment
+ * without leading #". But realistic consumers copy hashes out of
+ * `location.hash` (which is percent-encoded) and pass them back, so the
+ * naive `encodeURI("%20")` would double-encode into `"%2520"` and break
+ * anchor lookup. We detect a percent-escape triple in the input and, if
+ * present, decode + re-encode for idempotency. Malformed `%XX` (e.g.
+ * `"%2"` or `"%ZZ"`) makes `decodeURIComponent` throw — in that case we
+ * fall through to plain `encodeURI`, which never throws.
  */
 function encodeFragmentInline(decoded) {
+    if (PERCENT_ESCAPE_PROBE.test(decoded)) {
+        try {
+            const roundtrip = decodeURIComponent(decoded);
+            return encodeURI(roundtrip).replaceAll("#", "%23");
+        }
+        catch {
+            // Malformed `%XX` — fall through to the plain encoding path.
+            // encodeURI does not throw on malformed escapes; it treats the
+            // `%` as a literal and percent-encodes it (`%2` → `%252`).
+        }
+    }
     return encodeURI(decoded).replaceAll("#", "%23");
 }
 /**
@@ -38,11 +63,28 @@ export function buildHref(router, routeName, routeParams, options) {
         const buildUrl = router.buildUrl;
         if (buildUrl) {
             const url = buildUrl(routeName, routeParams, normHash === undefined ? undefined : { hash: normHash });
-            if (url !== undefined) {
+            // Accept only non-empty strings. The BuildUrlFn type contract is
+            // `string | undefined`, but defensive against:
+            //   - `""` (empty string) → would render `<a href="">`, which resolves
+            //     to the current page URL → silent self-navigation on click.
+            //   - `null` (type-contract violation) → would render `<a href={null}>`,
+            //     stringified to `"null"` in some renderers.
+            // Either case falls through to the `router.buildPath` fallback below.
+            if (typeof url === "string" && url.length > 0) {
                 return url;
             }
         }
         const path = router.buildPath(routeName, routeParams);
+        // Symmetric to the buildUrl guard above (#S1 audit, Invariant 12).
+        // `router.buildPath` is typed `string`, but defends against:
+        //   - `""` (empty string) — would render `<a href="">`, which resolves
+        //     to the current page URL → silent self-navigation on click.
+        //   - non-string type-contract violations from custom path-matchers.
+        // Both yield `undefined` (renderer drops the attribute) with a warning.
+        if (typeof path !== "string" || path.length === 0) {
+            console.error(`[real-router] Route "${routeName}" yielded an empty path. The element will render without an href attribute.`);
+            return undefined;
+        }
         return normHash ? `${path}#${encodeFragmentInline(normHash)}` : path;
     }
     catch {
@@ -68,8 +110,25 @@ export function navigateWithHash(router, routeName, routeParams, hash, extraOpti
     }
     return router.navigate(routeName, routeParams, opts);
 }
+// Match-any-whitespace regex shared across calls. RegExp literals at
+// call-site recompile in some engines; lifting it avoids that microcost
+// for the slow-path branch.
+const WHITESPACE_PROBE = /\s/;
+const WHITESPACE_SPLIT = /\S+/g;
 function parseTokens(value) {
-    return value ? (value.match(/\S+/g) ?? []) : [];
+    if (!value) {
+        return [];
+    }
+    // Hot-path fast-path (audit-2026-05-17 §8b #1): >99% of active-class
+    // inputs at `<Link>` emit are single-token strings like `"active"` or
+    // `"is-current"` — no whitespace, no leading/trailing pad. Skip the
+    // regex match and Array result allocation: a literal `[value]` works
+    // because the slow-path `match(/\S+/g)` would return exactly `[value]`
+    // for the same input. PBT lock: linkUtils.properties.ts Invariant 13.
+    if (!WHITESPACE_PROBE.test(value)) {
+        return [value];
+    }
+    return value.match(WHITESPACE_SPLIT) ?? [];
 }
 export function buildActiveClassName(isActive, activeClassName, baseClassName) {
     if (isActive && activeClassName) {
@@ -92,6 +151,29 @@ export function buildActiveClassName(isActive, activeClassName, baseClassName) {
     }
     return baseClassName ?? undefined;
 }
+/**
+ * One-level structural equality using `Object.is` per key.
+ *
+ * **String-keyed properties only (Mini-sprint E.3 — audit-5 §4.2 #3).**
+ * Implementation walks `Object.keys()` which by spec returns only
+ * enumerable own STRING keys. Symbol-keyed properties — created via
+ * `obj[Symbol("brand")] = value` or `{ [Symbol(...)]: value }` — are
+ * NOT compared. Two records that differ only in a Symbol-keyed value
+ * will compare as equal.
+ *
+ * This is intentional: route params and Link options are documented as
+ * string-keyed primitives (string | number | boolean) — Symbol-keyed
+ * metadata (e.g. brand markers, private state) doesn't belong in a
+ * cache-key comparison. Switching to `Reflect.ownKeys()` would extend
+ * the contract to symbols at the cost of one extra allocation per call
+ * (Reflect.ownKeys composes string-keys + symbol-keys arrays). If a
+ * consumer relies on symbol-keyed metadata for navigation
+ * disambiguation, they should encode it into a string key instead.
+ *
+ * Mirrors React's `shallowEqual` (packages/shared/shallowEqual.js) in
+ * both the string-keys-only semantics and the `hasOwnProperty` guard
+ * below.
+ */
 export function shallowEqual(prev, next) {
     if (Object.is(prev, next)) {
         return true;
@@ -106,7 +188,11 @@ export function shallowEqual(prev, next) {
     const prevRecord = prev;
     const nextRecord = next;
     for (const key of prevKeys) {
-        if (!Object.is(prevRecord[key], nextRecord[key])) {
+        // hasOwnProperty guard: without it, a key missing in `next` reads as
+        // `undefined` and falsely matches `prev[key] === undefined`. Same shape
+        // as React's shallowEqual (packages/shared/shallowEqual.js).
+        if (!Object.prototype.hasOwnProperty.call(next, key) ||
+            !Object.is(prevRecord[key], nextRecord[key])) {
             return false;
         }
     }
@@ -116,8 +202,23 @@ export function applyLinkA11y(element) {
     if (!element) {
         return;
     }
-    if (element instanceof HTMLAnchorElement ||
-        element instanceof HTMLButtonElement) {
+    // Cross-realm safety (audit-2026-05-17 §5 HIGH #4):
+    // `instanceof HTMLAnchorElement` compares against the constructor from
+    // the CURRENT realm. An element created in a different window (iframe
+    // contentDocument, micro-frontend, embedded widget) fails the check
+    // even when it IS a real anchor — the helper would then inject
+    // role="link" + tabindex="0" on top of native anchor semantics,
+    // breaking screen reader output ("link link") and focus order.
+    //
+    // tagName is realm-agnostic and is uppercase for HTML-namespaced
+    // elements in any document. SVG `<a>` has lowercase tagName plus a
+    // different prototype (SVGAElement) — skipping it here is wrong by
+    // accident: SVG anchors don't have keyboard activation semantics the
+    // helper would add. But they also don't reach this helper in
+    // practice (router Link components emit HTML anchors). Lock the
+    // uppercase compare to keep the contract narrow.
+    const tag = element.tagName;
+    if (tag === "A" || tag === "BUTTON") {
         return;
     }
     if (!element.hasAttribute("role")) {

package/dist/dom-utils/route-announcer.js

@@ -3,7 +3,24 @@ const SAFARI_READY_DELAY = 100;
 const ANNOUNCER_ATTR = "data-real-router-announcer";
 const INTERNAL_ROUTE_PREFIX = "@@";
 const VISUALLY_HIDDEN = "position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);clip-path:inset(50%);white-space:nowrap;border:0";
+const NOOP_INSTANCE = Object.freeze({
+    destroy: () => {
+        /* no-op */
+    },
+});
 export function createRouteAnnouncer(router, options) {
+    // Defensive SSR / non-browser guard: in SSR (Node.js) or non-DOM
+    // environments, `document` is undefined and the announcer cannot
+    // attach its aria-live region. Return a frozen NOOP_INSTANCE — same
+    // pattern as `createDirectionTracker`, `createScrollRestoration`, and
+    // `createViewTransitions`. Without this guard, `NavigationAnnouncer`
+    // component construction would throw `ReferenceError: document is not
+    // defined` under `@angular/ssr` rendering, tearing down the whole SSR
+    // bootstrap. Closes review-2026-05-10 §5.10 ⛔ "NavigationAnnouncer
+    // SSR mode" MED.
+    if (typeof document === "undefined") {
+        return NOOP_INSTANCE;
+    }
     const prefix = options?.prefix ?? "Navigated to ";
     const getCustomText = options?.getAnnouncementText;
     let isInitialNavigation = true;
@@ -84,7 +101,19 @@ function getOrCreateAnnouncer() {
     element.setAttribute("aria-live", "assertive");
     element.setAttribute("aria-atomic", "true");
     element.setAttribute(ANNOUNCER_ATTR, "");
-    document.body.prepend(element);
+    // Defensive SSR / pre-`<body>` guard: in some environments (early
+    // injection, deferred-body documents, certain SSR rehydration paths)
+    // `document.body` can be null when the announcer is constructed.
+    // `document.body.prepend(...)` would throw `TypeError: Cannot read
+    // properties of null`, tearing down the consumer's RouterProvider /
+    // NavigationAnnouncer mount. Fallback to `documentElement` keeps the
+    // announcer working for SR users; visual-hidden styling means there is
+    // no visible artifact regardless of mount point.
+    //
+    // TS dom lib types `document.body` as `HTMLElement` (non-null), but
+    // runtime can return null per spec. The `as` cast narrows the type to
+    // include null so the `??` short-circuit is type-safe.
+    (document.body ?? document.documentElement).prepend(element);
     return element;
 }
 function removeAnnouncer() {
@@ -92,7 +121,27 @@ function removeAnnouncer() {
 }
 function resolveText(route, prefix, getCustomText, h1) {
     if (getCustomText) {
-        return getCustomText(route);
+        try {
+            const customText = getCustomText(route);
+            // Mini-sprint E.4 (audit-5 §4.2 #4) — empty-string fallback.
+            // A consumer pattern like
+            //   getAnnouncementText: (route) => myMap[route.name] ?? ""
+            // returns `""` for routes outside the map. The subscribe loop
+            // then sees an empty text and silently no-announces — screen
+            // readers stay quiet without any signal to the developer. Treat
+            // a falsy custom result (`""` / `null` / `undefined`) as
+            // "consumer doesn't have a name for this route" and fall through
+            // to the default resolution chain (h1 → title → route name).
+            if (customText) {
+                return customText;
+            }
+        }
+        catch (error) {
+            // A throwing consumer callback inside the router's subscribe loop
+            // would tear down sibling listeners — log and fall through to the
+            // built-in resolution chain so the announcer keeps working.
+            console.error("[real-router] getAnnouncementText threw; falling back to default resolution.", error);
+        }
     }
     const h1Text = (h1?.textContent ?? "").trim();
     const routeName = route.name.startsWith(INTERNAL_ROUTE_PREFIX)

package/dist/dom-utils/scroll-restore.d.ts

@@ -1,4 +1,4 @@
-import type { Router } from "@real-router/core";
+import type { Router, State } from "@real-router/core";
 export type ScrollRestorationMode = "restore" | "top" | "native";
 export interface ScrollRestorationOptions {
     mode?: ScrollRestorationMode | undefined;
@@ -29,3 +29,40 @@ export interface ScrollRestorationOptions {
 export declare function createScrollRestoration(router: Router, options?: ScrollRestorationOptions): {
     destroy: () => void;
 };
+export declare function keyOf(state: State): string;
+/**
+ * Stable JSON serializer with sorted object keys.
+ *
+ * **Exported for testing only — not part of the public API** (intentionally
+ * excluded from `index.ts` barrel). Adapter property tests import it via
+ * the direct path to lock the key-order-insensitive property
+ * (`canonicalJson({a:1,b:2}) === canonicalJson({b:2,a:1})`).
+ *
+ * ## Divergence from `@real-router/sources/canonicalJson` — by design
+ *
+ * Two independent implementations live in the monorepo:
+ *
+ * - **`shared/dom-utils/scroll-restore.canonicalJson`** (this file) — scroll
+ *   cache key builder. Uses `localeCompare` and a plain-object accumulator;
+ *   tolerates `__proto__`-keyed inputs only insofar as `JSON.stringify`'s
+ *   replacer happens to sort them; relies on `JSON.stringify`'s native cycle
+ *   detector. Designed to be cheap on the navigation hot path. The
+ *   surrounding [[safeKeyOf]] wrapper catches the two crash inputs (`BigInt`,
+ *   cyclic) and skips the offending capture/restore.
+ *
+ * - **`@real-router/sources/canonicalJson`** — sources cache key builder.
+ *   Uses byte-order compare (`< / >`) for locale-independence, a
+ *   `Object.create(null)` accumulator to prevent prototype pollution, and a
+ *   bespoke path-based cycle detector (the native one cannot see the cloned
+ *   graph). Throws eagerly on `Map`/`Set`/`RegExp`/cycles — the caller falls
+ *   back to a non-cached source.
+ *
+ * **They are intentionally NOT interchangeable.** Aligning them would either
+ * regress scroll-restore performance (byte-order + recursive clone is heavier
+ * per call) or weaken the sources cache (locale dependence breaks
+ * deterministic cache keys across machines). No cross-package equivalence
+ * test exists or should be added; the relationship is "different invariants,
+ * different costs, different consumers." Audit-2 / audit-2026-05-17 §2
+ * documents the choice.
+ */
+export declare function canonicalJson(value: unknown): string;