@timber-js/app 0.2.0-alpha.54 → 0.2.0-alpha.55

package/dist/client/link-pending-store.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Link Pending Store — module-level singleton for per-link pending state.
+ *
+ * Tracks which link instance is currently navigating so that only the
+ * clicked link shows pending. All other links remain unaffected — zero
+ * wasted re-renders.
+ *
+ * The store holds:
+ * - A reference to the currently navigating link's state setter
+ * - A navigation counter to guard against stale clears (race condition
+ *   when the user clicks Link B before Link A's navigation completes)
+ *
+ * Flow:
+ * 1. Link click handler: setLinkForCurrentNavigation(instance) →
+ *    resets previous link (urgent), sets new link pending (urgent),
+ *    stores setter + increments navId
+ * 2. TransitionRoot startTransition: captures navId, does async work
+ * 3. TransitionRoot commit: resetLinkPending(capturedNavId) →
+ *    calls setter(IDLE) inside the transition (batched, atomic with tree)
+ *    Only clears if navId matches (prevents stale T1 from clearing T2's link)
+ *
+ * SINGLETON GUARANTEE: Uses `globalThis` via `Symbol.for` keys (same
+ * pattern as NavigationContext) because the RSC client bundler can
+ * duplicate this module across chunks. Module-level variables would
+ * create separate instances per chunk.
+ *
+ * See design/19-client-navigation.md §"Per-Link Pending State"
+ */
+import type { LinkStatus } from './use-link-status.js';
+export interface LinkPendingInstance {
+    setLinkStatus: (status: LinkStatus) => void;
+}
+/** Status object indicating link is pending — shared reference */
+export declare const PENDING_LINK_STATUS: LinkStatus;
+/** Status object indicating link is idle — shared reference */
+export declare const IDLE_LINK_STATUS: LinkStatus;
+/**
+ * Register the link instance that initiated the current navigation.
+ *
+ * Called from <Link>'s click handler before router.navigate().
+ * - Resets the previous pending link to IDLE (urgent update, immediate)
+ * - Does NOT set the new link to PENDING here — the Link's click handler
+ *   calls setLinkStatus(PENDING) directly for the eager show
+ * - Increments the navId counter for stale-clear protection
+ *
+ * Pass `null` to clear (e.g., for programmatic navigations).
+ */
+export declare function setLinkForCurrentNavigation(link: LinkPendingInstance | null): void;
+/**
+ * Get the current navigation ID. Called at the start of the transition
+ * to capture the ID before async work begins.
+ */
+export declare function getCurrentNavId(): number;
+/**
+ * Reset the current link's pending state to IDLE, but only if the navId
+ * matches. Called inside TransitionRoot's startTransition after the async
+ * work completes — the setter call is a transition update, so it commits
+ * atomically with the new tree.
+ *
+ * The navId guard prevents stale transitions from clearing a newer
+ * navigation's pending state. Scenario:
+ *   Click A → navId=1, T1 starts
+ *   Click B → navId=2, A reset to IDLE, T2 starts
+ *   T1 completes → resetLinkPending(1) → navId is 2, skip ✓
+ *   T2 completes → resetLinkPending(2) → navId is 2, clear ✓
+ */
+export declare function resetLinkPending(forNavId: number): void;
+/**
+ * Clean up the link pending store entirely. Safety net for error paths.
+ */
+export declare function clearLinkPendingSetter(): void;
+/**
+ * Unmount a link instance from navigation tracking. Called when a Link
+ * component unmounts while it is the current navigation link. Prevents
+ * calling setState on an unmounted component.
+ */
+export declare function unmountLinkForCurrentNavigation(link: LinkPendingInstance): void;
+//# sourceMappingURL=link-pending-store.d.ts.map

package/dist/client/link-pending-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-pending-store.d.ts","sourceRoot":"","sources":["../../src/client/link-pending-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvD,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;CAC7C;AAMD,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,EAAE,UAA8B,CAAC;AAEjE,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,EAAE,UAA+B,CAAC;AAmB/D;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,GAAG,IAAI,CAWlF;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAMvD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAK/E"}

package/dist/client/link.d.ts

@@ -1,4 +1,4 @@
-import type { AnchorHTMLAttributes, ReactNode } from 'react';
+import { type AnchorHTMLAttributes, type ReactNode } from 'react';
 import type { SearchParamsDefinition } from '#/search-params/define.js';
 export type OnNavigateEvent = {
     preventDefault: () => void;

package/dist/client/link.d.ts.map

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

package/dist/client/navigation-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-context.d.ts","sourceRoot":"","sources":["../../src/client/navigation-context.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAuCD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,IAAI,CAM7D;AAMD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,GACT,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,CAO9C;AA6BD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AA6BD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAKvD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GAAG,KAAK,CAAC,YAAY,CAMrB"}
+{"version":3,"file":"navigation-context.d.ts","sourceRoot":"","sources":["../../src/client/navigation-context.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAuCD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,IAAI,CAM7D;AAMD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,GACT,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,CAO9C;AA6BD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AA8BD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAKvD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GAAG,KAAK,CAAC,YAAY,CAMrB"}

package/dist/client/transition-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transition-root.d.ts","sourceRoot":"","sources":["../../src/client/transition-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzF,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAqBlE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,GAAG,SAAS,CAgDZ;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C"}
+{"version":3,"file":"transition-root.d.ts","sourceRoot":"","sources":["../../src/client/transition-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzF,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAsBlE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,GAAG,SAAS,CA2DZ;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C"}

package/dist/server/html-injectors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html-injectors.d.ts","sourceRoot":"","sources":["../../src/server/html-injectors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,wBAA6B,GACrC,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAgEzC;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAuChF;AA8ED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,EAAE,MAAM,GAClB,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAiC5B;AAmHD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAiB5B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;CACtB;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,OAAO,CAAA;KAAE,CAAC;IACjE,GAAG,EAAE,OAAO,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;CAC7D,GAAG,qBAAqB,CA8DxB"}
+{"version":3,"file":"html-injectors.d.ts","sourceRoot":"","sources":["../../src/server/html-injectors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,wBAA6B,GACrC,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAgEzC;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAuChF;AA8ED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,EAAE,MAAM,GAClB,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAiC5B;AAmID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAiB5B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;CACtB;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,OAAO,CAAA;KAAE,CAAC;IACjE,GAAG,EAAE,OAAO,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;CAC7D,GAAG,qBAAqB,CA8DxB"}

package/dist/server/node-stream-transforms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-stream-transforms.d.ts","sourceRoot":"","sources":["../../src/server/node-stream-transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,SAAS,CAgDjG;AAqBD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,IAAI,SAAS,CAwCzD;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA+ClE;AAID;;;;;;;;;;;;;;;GAeG;AACH;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,OAAO,CAAC,EAAE,yBAAyB,GAClC,SAAS,CA2IX;AAOD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAwBtE;AAoBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,OAAO,GACvB,SAAS,GAAG,IAAI,CA8BlB"}
+{"version":3,"file":"node-stream-transforms.d.ts","sourceRoot":"","sources":["../../src/server/node-stream-transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,SAAS,CAgDjG;AAqBD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,IAAI,SAAS,CAwCzD;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA+ClE;AAID;;;;;;;;;;;;;;;GAeG;AACH;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,OAAO,CAAC,EAAE,yBAAyB,GAClC,SAAS,CAgJX;AAOD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAwBtE;AAoBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,OAAO,GACvB,SAAS,GAAG,IAAI,CA8BlB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.54",
+  "version": "0.2.0-alpha.55",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -83,11 +83,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.6.1",
@@ -126,5 +121,9 @@
   },
   "engines": {
     "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/client/link-pending-store.ts

@@ -0,0 +1,136 @@
+/**
+ * Link Pending Store — module-level singleton for per-link pending state.
+ *
+ * Tracks which link instance is currently navigating so that only the
+ * clicked link shows pending. All other links remain unaffected — zero
+ * wasted re-renders.
+ *
+ * The store holds:
+ * - A reference to the currently navigating link's state setter
+ * - A navigation counter to guard against stale clears (race condition
+ *   when the user clicks Link B before Link A's navigation completes)
+ *
+ * Flow:
+ * 1. Link click handler: setLinkForCurrentNavigation(instance) →
+ *    resets previous link (urgent), sets new link pending (urgent),
+ *    stores setter + increments navId
+ * 2. TransitionRoot startTransition: captures navId, does async work
+ * 3. TransitionRoot commit: resetLinkPending(capturedNavId) →
+ *    calls setter(IDLE) inside the transition (batched, atomic with tree)
+ *    Only clears if navId matches (prevents stale T1 from clearing T2's link)
+ *
+ * SINGLETON GUARANTEE: Uses `globalThis` via `Symbol.for` keys (same
+ * pattern as NavigationContext) because the RSC client bundler can
+ * duplicate this module across chunks. Module-level variables would
+ * create separate instances per chunk.
+ *
+ * See design/19-client-navigation.md §"Per-Link Pending State"
+ */
+
+import type { LinkStatus } from './use-link-status.js';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+export interface LinkPendingInstance {
+  setLinkStatus: (status: LinkStatus) => void;
+}
+
+// ─── Singleton Storage ───────────────────────────────────────────
+
+const LINK_PENDING_KEY = Symbol.for('__timber_link_pending');
+
+/** Status object indicating link is pending — shared reference */
+export const PENDING_LINK_STATUS: LinkStatus = { pending: true };
+
+/** Status object indicating link is idle — shared reference */
+export const IDLE_LINK_STATUS: LinkStatus = { pending: false };
+
+interface LinkPendingState {
+  /** The link instance that initiated the current navigation, or null */
+  current: LinkPendingInstance | null;
+  /** Monotonically increasing counter — guards against stale clears */
+  navId: number;
+}
+
+function getStore(): LinkPendingState {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[LINK_PENDING_KEY]) {
+    g[LINK_PENDING_KEY] = { current: null, navId: 0 };
+  }
+  return g[LINK_PENDING_KEY] as LinkPendingState;
+}
+
+// ─── Public API ──────────────────────────────────────────────────
+
+/**
+ * Register the link instance that initiated the current navigation.
+ *
+ * Called from <Link>'s click handler before router.navigate().
+ * - Resets the previous pending link to IDLE (urgent update, immediate)
+ * - Does NOT set the new link to PENDING here — the Link's click handler
+ *   calls setLinkStatus(PENDING) directly for the eager show
+ * - Increments the navId counter for stale-clear protection
+ *
+ * Pass `null` to clear (e.g., for programmatic navigations).
+ */
+export function setLinkForCurrentNavigation(link: LinkPendingInstance | null): void {
+  const store = getStore();
+  const prev = store.current;
+
+  // Reset previous pending link to idle (urgent update — shows immediately)
+  if (prev && prev !== link) {
+    prev.setLinkStatus(IDLE_LINK_STATUS);
+  }
+
+  store.current = link;
+  store.navId++;
+}
+
+/**
+ * Get the current navigation ID. Called at the start of the transition
+ * to capture the ID before async work begins.
+ */
+export function getCurrentNavId(): number {
+  return getStore().navId;
+}
+
+/**
+ * Reset the current link's pending state to IDLE, but only if the navId
+ * matches. Called inside TransitionRoot's startTransition after the async
+ * work completes — the setter call is a transition update, so it commits
+ * atomically with the new tree.
+ *
+ * The navId guard prevents stale transitions from clearing a newer
+ * navigation's pending state. Scenario:
+ *   Click A → navId=1, T1 starts
+ *   Click B → navId=2, A reset to IDLE, T2 starts
+ *   T1 completes → resetLinkPending(1) → navId is 2, skip ✓
+ *   T2 completes → resetLinkPending(2) → navId is 2, clear ✓
+ */
+export function resetLinkPending(forNavId: number): void {
+  const store = getStore();
+  if (store.navId === forNavId && store.current) {
+    store.current.setLinkStatus(IDLE_LINK_STATUS);
+    store.current = null;
+  }
+}
+
+/**
+ * Clean up the link pending store entirely. Safety net for error paths.
+ */
+export function clearLinkPendingSetter(): void {
+  const store = getStore();
+  store.current = null;
+}
+
+/**
+ * Unmount a link instance from navigation tracking. Called when a Link
+ * component unmounts while it is the current navigation link. Prevents
+ * calling setState on an unmounted component.
+ */
+export function unmountLinkForCurrentNavigation(link: LinkPendingInstance): void {
+  const store = getStore();
+  if (store.current === link) {
+    store.current = null;
+  }
+}

package/src/client/link.tsx

@@ -18,12 +18,26 @@
 // - params and fully-resolved string href are mutually exclusive
 // - searchParams and inline query string are mutually exclusive
 
-import type { AnchorHTMLAttributes, ReactNode, MouseEvent as ReactMouseEvent } from 'react';
+import {
+  useState,
+  useEffect,
+  useRef,
+  type AnchorHTMLAttributes,
+  type ReactNode,
+  type MouseEvent as ReactMouseEvent,
+} from 'react';
 import type { SearchParamsDefinition } from '#/search-params/define.js';
-import { LinkStatusProvider } from './link-status-provider.js';
+import { LinkStatusContext } from './use-link-status.js';
 import { getRouterOrNull } from './router-ref.js';
 import { getSsrData } from './ssr-data.js';
 import { mergePreservedSearchParams } from '#/shared/merge-search-params.js';
+import {
+  setLinkForCurrentNavigation,
+  unmountLinkForCurrentNavigation,
+  IDLE_LINK_STATUS,
+  PENDING_LINK_STATUS,
+  type LinkPendingInstance,
+} from './link-pending-store.js';
 
 // ─── Current Search Params ────────────────────────────────────────
 
@@ -353,6 +367,38 @@ export function Link({
 }: LinkProps) {
   const { href: baseHref } = buildLinkProps({ href, params: segmentParams, searchParams });
 
+  // ─── Per-link pending state (useState) ────────────────────────
+  // Each Link has its own pending state. Only the clicked link's
+  // setter is invoked during navigation — zero other links re-render.
+  //
+  // Eager show: click handler calls setLinkStatus(PENDING) directly (urgent).
+  // Atomic clear: TransitionRoot calls resetLinkPending(navId) inside
+  // startTransition — batched with the new tree commit.
+  //
+  // See design/19-client-navigation.md §"Per-Link Pending State"
+  const [linkStatus, setLinkStatus] = useState(IDLE_LINK_STATUS);
+
+  // Build the link instance ref for the pending store.
+  // The ref is stable across renders — we update the setter on each
+  // render to keep it current.
+  const linkInstanceRef = useRef<LinkPendingInstance | null>(null);
+  if (!linkInstanceRef.current) {
+    linkInstanceRef.current = { setLinkStatus };
+  } else {
+    linkInstanceRef.current.setLinkStatus = setLinkStatus;
+  }
+
+  // Clean up if this link unmounts while it's the current navigation link.
+  // Prevents calling setOptimistic on an unmounted component.
+  useEffect(() => {
+    const instance = linkInstanceRef.current;
+    return () => {
+      if (instance) {
+        unmountLinkForCurrentNavigation(instance);
+      }
+    };
+  }, []);
+
   // Preserve search params from the current URL when requested.
   // useSearchParams() works during both SSR (reads from request context)
   // and on the client (reads from window.location, reactive to URL changes).
@@ -401,6 +447,16 @@ export function Link({
         const navHref = preserveSearchParams
           ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
           : resolvedHref;
+
+        // Eagerly show pending state on this link (urgent update, immediate).
+        // Only this Link re-renders — all other Links are unaffected.
+        setLinkStatus(PENDING_LINK_STATUS);
+
+        // Register this link in the pending store so TransitionRoot can
+        // reset it to IDLE inside startTransition (atomic with new tree).
+        // Also resets any previous pending link to IDLE.
+        setLinkForCurrentNavigation(linkInstanceRef.current);
+
         void router.navigate(navHref, { scroll: shouldScroll });
       }
     : userOnClick; // External links — just pass through user's onClick
@@ -423,7 +479,7 @@ export function Link({
 
   return (
     <a {...rest} href={resolvedHref} onClick={handleClick} onMouseEnter={handleMouseEnter}>
-      <LinkStatusProvider href={resolvedHref}>{children}</LinkStatusProvider>
+      <LinkStatusContext.Provider value={linkStatus}>{children}</LinkStatusContext.Provider>
     </a>
   );
 }

package/src/client/navigation-context.ts

@@ -63,7 +63,7 @@ export interface NavigationState {
  * variables) because the ESM bundler can duplicate this module across
  * chunks. Module-level variables would create separate instances per
  * chunk — the provider in TransitionRoot (index chunk) would use
- * context A while the consumer in LinkStatusProvider (shared chunk)
+ * context A while the consumer in useNavigationPending (shared chunk)
  * reads from context B. globalThis guarantees a single instance.
  *
  * See design/27-chunking-strategy.md §"Singleton Safety"
@@ -168,8 +168,9 @@ export function getNavigationState(): NavigationState {
 
 /**
  * Separate context for the in-flight navigation URL. Provided by
- * TransitionRoot (urgent useState), consumed by LinkStatusProvider
- * and useNavigationPending.
+ * TransitionRoot (urgent useState), consumed by useNavigationPending
+ * and TopLoader. Per-link pending state uses useOptimistic instead
+ * (see link-pending-store.ts).
  *
  * Uses globalThis via Symbol.for for the same reason as NavigationContext
  * above — the bundler may duplicate this module across chunks, and module-

package/src/client/transition-root.tsx

@@ -25,6 +25,7 @@
 import { useState, useTransition, createElement, Fragment, type ReactNode } from 'react';
 import { PendingNavigationProvider } from './navigation-context.js';
 import { TopLoader, type TopLoaderConfig } from './top-loader.js';
+import { getCurrentNavId, resetLinkPending } from './link-pending-store.js';
 
 // ─── Module-level functions ──────────────────────────────────────
 
@@ -88,20 +89,31 @@ export function TransitionRoot({
   // both apply in the same React commit — making the pending→active transition
   // atomic (no frame where pending is false but the old tree is still visible).
   _navigateTransition = (url: string, perform: () => Promise<ReactNode>) => {
-    // Urgent: show pending state immediately
+    // Urgent: show pending state immediately (for TopLoader / useNavigationPending)
     setPendingUrl(url);
 
     return new Promise<void>((resolve, reject) => {
       startTransition(async () => {
+        // Capture the current nav ID before async work begins.
+        // Used to guard against stale clears when a newer navigation
+        // supersedes this one.
+        const navId = getCurrentNavId();
         try {
           const newElement = await perform();
           setElement(newElement);
           // Clear pending inside the transition — commits atomically with new tree
           setPendingUrl(null);
+          // Reset per-link pending state. The navId guard ensures a stale
+          // transition (T1) doesn't clear a newer navigation's (T2) link.
+          // The setter call is a transition update — batched with setElement
+          // and setPendingUrl, so pending clears atomically with new tree.
+          // See design/19-client-navigation.md §"Per-Link Pending State"
+          resetLinkPending(navId);
           resolve();
         } catch (err) {
           // Clear pending on error too
           setPendingUrl(null);
+          resetLinkPending(navId);
           reject(err);
         }
       });

package/src/server/html-injectors.ts

@@ -351,8 +351,14 @@ function createFlightInjectionTransform(
   let pullPromise: Promise<void> | null = null;
 
   // RSC script chunks waiting to be drained at a safe boundary.
+  // pullLoop buffers here; transform(), flush(), and pullLoop's
+  // post-yield drain all consume from this buffer.
   const pending: Uint8Array[] = [];
 
+  // Controller reference — set on first transform() call so pullLoop
+  // can drain pending scripts between HTML chunks (after yielding).
+  let _controller: TransformStreamDefaultController<Uint8Array> | null = null;
+
   async function pullLoop(): Promise<void> {
     // Yield once so the first HTML shell chunk flows through
     // transform() before we start reading RSC data.
@@ -376,6 +382,14 @@ function createFlightInjectionTransform(
         // Once flush() fires, drain without yielding.
         if (!isHtmlDone(machine.state)) {
           await new Promise<void>((r) => setImmediate(r));
+          // After yielding, drain pending scripts. This ensures RSC
+          // flight data reaches the client at shell-flush time — without
+          // this, hydration blocks waiting for data stuck in pending[].
+          // Safe because the upstream buffered transform (TIM-528)
+          // guarantees chunks end at tag boundaries.
+          if (pending.length > 0 && _controller) {
+            drainPending(_controller);
+          }
         }
       }
     } catch (err) {
@@ -398,6 +412,8 @@ function createFlightInjectionTransform(
 
   return new TransformStream<Uint8Array, Uint8Array>({
     transform(chunk, controller) {
+      _controller = controller;
+
       if (machine.state.phase === 'init') {
         machine.send({ type: 'FIRST_CHUNK' });
         pullPromise = pullLoop();

package/src/server/node-stream-transforms.ts

@@ -285,16 +285,10 @@ export function createNodeFlightInjector(
 
   // RSC script chunks waiting to be drained at a safe boundary.
   // pullLoop buffers here; transform() and flush() drain.
-  // Scripts are NEVER pushed directly from pullLoop — they are only
-  // emitted from transform() (after a complete HTML chunk) or flush().
-  // This guarantees scripts never land mid-tag. See TIM-527/TIM-529.
+  // RSC script chunks waiting to be drained at a safe boundary.
+  // pullLoop buffers here; transform(), flush(), and pullLoop's
+  // post-yield drain all consume from this buffer.
   const pending: Buffer[] = [];
-
-  // pullLoop reads RSC chunks and buffers them as <script> tags in
-  // pending[]. It does NOT push directly to the transform output —
-  // that would cause scripts to interleave at arbitrary byte
-  // boundaries within HTML chunks (TIM-527). Pending scripts are
-  // drained only from transform() or flush().
   async function pullLoop(): Promise<void> {
     // Yield once so the first transform() call can process the shell
     // HTML chunk before we start reading RSC data.
@@ -315,13 +309,24 @@ export function createNodeFlightInjector(
         }
         const decoded = decoder.decode(value, { stream: true });
         const scriptBuf = Buffer.from(flightChunkScript(decoded), 'utf-8');
-        // Buffer the script — drained by the next transform() or flush().
+        // Buffer the script — drained by the next transform() call,
+        // flush(), or by the scheduled drain below.
         pending.push(scriptBuf);
-        // Yield between reads so HTML chunks get a chance to flow
-        // through transform() first — but only while HTML is still
-        // streaming. Once flush() fires, drain without yielding.
+        // Yield between reads so HTML chunks get priority in the event
+        // loop — but only while HTML is still streaming. Once flush()
+        // fires, read without yielding to drain remaining RSC data.
         if (!isHtmlDone(machine.state)) {
           await new Promise<void>((r) => setImmediate(r));
+          // After yielding, if no transform() call drained the buffer
+          // (i.e., no new HTML chunk arrived), drain now. This ensures
+          // RSC flight data reaches the client at shell-flush time —
+          // without this, hydration blocks on createFromReadableStream
+          // waiting for data that's stuck in pending[].
+          // This is safe: we're between event loop ticks, so no
+          // transform() call is mid-execution (no mid-tag risk).
+          if (pending.length > 0) {
+            drainPending();
+          }
         }
       }
     } catch (err) {

package/dist/client/link-status-provider.d.ts

@@ -1,11 +0,0 @@
-import type { ReactNode } from 'react';
-/**
- * Client component that reads the pending URL from PendingNavigationContext
- * and provides a scoped LinkStatusContext to children. Renders no extra DOM —
- * just a context provider around children.
- */
-export declare function LinkStatusProvider({ href, children }: {
-    href: string;
-    children?: ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=link-status-provider.d.ts.map

package/dist/client/link-status-provider.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"link-status-provider.d.ts","sourceRoot":"","sources":["../../src/client/link-status-provider.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAOvC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,2CAK5F"}

package/src/client/link-status-provider.tsx

@@ -1,30 +0,0 @@
-'use client';
-
-// LinkStatusProvider — client component that provides per-link pending status
-// via React context. Used inside <Link> to power useLinkStatus().
-//
-// Reads pendingUrl from PendingNavigationContext (provided by TransitionRoot).
-// The pending URL is set as an URGENT update at navigation start (shows
-// immediately) and cleared inside startTransition when the new tree commits
-// (atomic with params/pathname). This eliminates both:
-// 1. The delay before showing the spinner (urgent update, not deferred)
-// 2. The gap between spinner disappearing and active state updating (same commit)
-
-import type { ReactNode } from 'react';
-import { LinkStatusContext, type LinkStatus } from './use-link-status.js';
-import { usePendingNavigationUrl } from './navigation-context.js';
-
-const NOT_PENDING: LinkStatus = { pending: false };
-const IS_PENDING: LinkStatus = { pending: true };
-
-/**
- * Client component that reads the pending URL from PendingNavigationContext
- * and provides a scoped LinkStatusContext to children. Renders no extra DOM —
- * just a context provider around children.
- */
-export function LinkStatusProvider({ href, children }: { href: string; children?: ReactNode }) {
-  const pendingUrl = usePendingNavigationUrl();
-  const status = pendingUrl === href ? IS_PENDING : NOT_PENDING;
-
-  return <LinkStatusContext.Provider value={status}>{children}</LinkStatusContext.Provider>;
-}