@rangojs/router 0.0.0-experimental.151 → 0.0.0-experimental.152

package/dist/vite/index.js

@@ -2520,7 +2520,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.151",
+  version: "0.0.0-experimental.152",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.151",
+  "version": "0.0.0-experimental.152",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/ppr/SKILL.md

@@ -184,6 +184,22 @@ opt-out. Use that for routes where the shell depends on runtime-only auth,
 cookies, or side-effectful SDK calls. A skipped build shell can still be owned
 later by runtime capture when runtime middleware does not call `ctx.dynamic()`.
 
+`ctx.dynamic()` also **re-permits handler header/cookie writes** (issue #735).
+The header doctrine below forbids handler writes on a ppr route because they
+ride MISSes and vanish on HITs — but a `dynamic()` render never HITs, so its
+write is deterministic. Calling `ctx.dynamic()` clears the header latch for the
+rest of the render, so the SAME handler can write its control-flow header
+directly (no middleware relay). Ordering is a contract: call `dynamic()` BEFORE
+the write — a write before it still throws.
+
+```ts
+function catalogPage(ctx) {
+  ctx.dynamic(); // declare live -> refuses capture AND clears the header latch
+  ctx.headers.set("x-rango-sfra-proxy", "catalog");
+  return <Catalog />;
+}
+```
+
 ## Verifying it works
 
 The header exists on DOCUMENT responses only. A bare `curl` gets the HTML
@@ -345,7 +361,9 @@ Four hard edges (each e2e/unit-pinned):
   HIT); loaders are live but settle AFTER the response headers flushed with
   the shell (dead letters). Move the write into route middleware — it runs
   on every request, including HITs, and its headers/cookies merge into every
-  response.
+  response. The one exception: a handler that calls `ctx.dynamic()` FIRST
+  re-permits its own header/cookie write (#735) — a dynamic() render never
+  HITs, so the write is deterministic (see "Opting out per request").
 - **Identity refuses.** `cookies()`/`headers()` inside a bake-lane loader
   throws during capture and the capture REFUSES (deterministic, once-per-key
   warned) — identity can never bake into the shared shell. Give that loader's

package/src/server/context.ts

@@ -903,14 +903,47 @@ export function latchPprHeaderScopeForEntries(
   }
 }
 
+/**
+ * Clear the ppr header-write latch for the remainder of this render (issue
+ * #735). Called by ctx.dynamic(): a dynamic() render opts off the SHELL axis
+ * (rsc-rendering.ts skips both the HIT commit and the MISS capture on
+ * `_dynamic`), so it is ALWAYS live — every request re-runs the handler and its
+ * header write lands identically each time. The guard's reason to forbid it
+ * (MISS/HIT divergence) evaporates, so the write is re-permitted.
+ *
+ * ONLY the ppr (shell) axis is dropped — dynamic() does NOT opt off the CACHE
+ * axis. Two cases:
+ * - Pure ppr funnel (no cache() boundary): clear the latch → writes re-permit.
+ * - ppr route nested under a cache() boundary: fresh.ts latches "ppr" at the
+ *   funnel top (first-wins), which MASKS the positional cache() latch, but the
+ *   handler still runs inside the cache scope (`insideCacheScope`). A cache()
+ *   HIT skips that handler, so the write is still non-deterministic — UNMASK to
+ *   "cache" instead of clearing, so the guard keeps throwing (accurate cache()
+ *   wording). This is why the check keys off `insideCacheScope`, not just kind.
+ *
+ * A subsequent cache() entered AFTER dynamic() on a pure-ppr funnel re-latches
+ * "cache" via latchCachedHeaderScope's `!store.cachedHeaderScope` guard (the
+ * field is undefined again once cleared). No-op when there is no funnel store or
+ * no ppr latch (dynamic() from middleware runs outside the funnel Store.run
+ * scope, so nothing is latched — the middleware exemption is unchanged).
+ */
+export function clearPprHeaderScope(): void {
+  const store = RangoContext.getStore();
+  if (store?.cachedHeaderScope?.kind !== "ppr") return;
+  store.cachedHeaderScope = store.insideCacheScope
+    ? { kind: "cache", routeKey: store.cachedHeaderScope.routeKey }
+    : undefined;
+}
+
 /**
  * RULE (issue #713): in any cached scenario ONLY MIDDLEWARE writes response
  * headers — handler and loader writes throw while a scope is latched; the one
  * exemption is DSL (registered) loaders under plain cache(). A handler-invoked
  * loader body (ctx.use from a handler, never registered with loader()) is
  * skipped with its handler on a HIT and throws like a handler write (#725).
- * Full layer rules and rationale: docs/design/ppr-shell-resume.md "The header
- * doctrine".
+ * A ctx.dynamic() render clears the ppr latch (clearPprHeaderScope, #735) so
+ * its always-live handler header writes are re-permitted. Full layer rules and
+ * rationale: docs/design/ppr-shell-resume.md "The header doctrine".
  */
 export function assertCachedHeaderWriteAllowed(
   surface: string,

package/src/server/request-context.ts

@@ -59,6 +59,7 @@ import type { LocationStateEntry } from "../browser/react/location-state-shared.
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import {
   assertCachedHeaderWriteAllowed,
+  clearPprHeaderScope,
   isInsideCacheScope,
 } from "./context.js";
 import {
@@ -979,6 +980,11 @@ export function createRequestContext<TEnv>(
     build,
     dynamic(): void {
       ctx._dynamic = true;
+      // A dynamic() render is always live (never a shell HIT), so its handler
+      // header writes are deterministic — clear the ppr latch to re-permit them
+      // (#735). No-op from middleware (outside the funnel scope) or on non-ppr
+      // routes; cache() latches are left alone.
+      clearPprHeaderScope();
     },
     _dynamic: false,
     get: ((keyOrVar: any) => {