Skip to content

fix(fresh/navigation): region requests outside root /partials/ count as page navigations, so a region tap drains an in-flight deferred body #2625

Open

Description

@rickylabs

Summary

installPartialNavigationCoordinator() (@netscript/fresh/navigation, 0.0.9) treats a request as a region request only when its path is /partials or starts with /partials/ (isPartialPath). An app whose region routes sit under a page's own path (for example /items/[id]/partials/list), and any anchor click, are classified as page navigations. Each page navigation bumps the generation and drains every older in-flight partial response.

The result: tap a region link (<a f-partial>) while a DeferPage body is still loading, and the deferred body is drained ("Superseded Fresh partial response was drained"). Only the tapped region updates, and every other deferred region stays on its fallback until the next full navigation.

Where

src/runtime/navigation/coordinator.ts:

  • onClick stages { kind: 'page', actualUrl } for every client-nav anchor, including anchors that carry f-partial.
  • onSubmit stages a region intent only when isNamedRegion holds, which requires isPartialPath(partialUrl), i.e. a root /partials/ path.
  • interceptFetch: an un-staged fresh-partial fetch is 'region' only when isPartialPath(url).
  • invalidReason: a page lease is valid only while lease.generation === this.requestedGeneration, so any newer page intent drains older responses.
function isPartialPath(url: URL): boolean {
  return url.pathname === '/partials' || url.pathname.startsWith('/partials/');
}

Reproducer

A page that defers its body to a region route under its own path, with region links inside the body:

// routes/items.tsx
export default function Items() {
  return (
    <body f-client-nav>
      <DeferPage
        name="items-body"
        action="/items"
        partial="/items/partials/body"
        fallback={<p>loading…</p>}
      />
      {/* a region link that exists before the body lands */}
      <a href="/items?tab=done" f-partial="/items/partials/list?tab=done">Done</a>
      <Partial name="items-list"><p>list</p></Partial>
    </body>
  );
}
// routes/items/partials/body.tsx answers `items-body` (slow, e.g. 800 ms);
// routes/items/partials/list.tsx answers `items-list` (fast).
  1. Load /items. The DeferComponent submits /items/partials/body (classified as a page navigation, generation 1).
  2. Before it answers, click "Done". The anchor click stages a page intent, so generation 2 fetches /items/partials/list.
  3. The body's response arrives, is now superseded, and is drained.
  4. Result: items-list shows the Done tab, but items-body stays on "loading…".

Verified in Chromium with the real coordinator bundled from 0.0.9. Four cases:

Case Result
A script's in-page fetch(…?fresh-partial=true) during the deferred load the page's own deferred body is drained
A page navigation tap during the load the body is drained and the new page applies (expected)
A region link tap during the load the body is drained and the page keeps its fallbacks (the bug)
The same region tap after the body landed applied, nothing drained

Expected

A region request must not supersede the page's in-flight deferred regions. Either of these would do:

  1. Classify by intent, not path: an anchor or form with f-partial (and the DeferComponent's form) stages { kind: 'region' }, wherever the region route lives. Only navigations that replace the page boundary bump the page generation.
  2. Or make the region route prefix configurable (or derive it from the app's partial routes), and document that region routes outside it count as page navigations.

A test in the coordinator suite: a deferred body in flight plus a region link tap leaves both applied.

Workaround in apps today

Make sure no deferred document offers a region-only control before its body lands (only page navigations), and never fetch partials from page scripts. That keeps users from hitting it, but it is an invariant the framework does not state.

Activity

  1. rickylabs commented on Nov 16, 2026

    @rickylabs
    OwnerAuthor

    Clarification after reading the 0.0.9 docs: pages/web-layer/partials places partial routes at the root (routes/partials/…, URL /partials/…). That is exactly what isPartialPath recognises, so an app that keeps its region routes there gets region intents.

    Two points still hold:

    1. The dependency is not documented. Neither the partials page nor the navigation reference says the coordinator classifies requests by that prefix. An app that nests its region routes under a page path (for example /items/[id]/partials/list, natural for per-tenant routes) silently gets page-navigation semantics, so its deferred bodies can be drained.
    2. Anchor clicks stage a page intent regardless of path (onClick). Even a root /partials/… link (<a f-partial>) bumps the page generation and drains an in-flight DeferPage body. Only the GET-form path (onSubmit with isNamedRegion) and un-staged fetches get the region classification.

    Suggested resolution, either:

    • Document it: region routes must live under root /partials/, and an f-partial anchor still counts as a page navigation.
    • Classify by intent: treat f-partial on the clicked anchor or form, plus the DeferComponent's form, as a region intent, wherever the route lives.
  2. rickylabs commented on Nov 17, 2026

    @rickylabs
    OwnerAuthor

    Additional consumer reproducer for the deferred-region lifecycle case (NetScript0.0.9, Fresh2.3.3, Deno2.9.7), observed before the consumer switched to an eager selected-day fallback.

    This is consistent with the nested-region classification limitation already described above; I have not proved a failure with root /partials/… routes. The important extra case is that the eagerly useful body has already rendered, so hiding all controls until that body lands does not avoid it.

    Minimal sequence using public native APIs only:

    // Canonical page /items. An eager selected-day list remains useful while more days load.
    <DeferPage
      name="items-body"
      action="/items"
      partial="/items/partials/body?days=week"
      fallback={<SelectedDayWithPendingOtherDays />}
    />
    <KeyedPartial name="item-drawer" />
    
    // A selected-day row opens a URL-hosted native Sheet, targeting only the drawer boundary:
    <a href="/items?item=one" f-partial="/items/partials/drawer?item=one">Open</a>
    // Drawer close:
    <a href="/items" f-partial="/items/partials/drawer">Close</a>
    1. Hold the slow days=week GET response in a browser route interceptor.
    2. Click the eager selected-day row. Its drawer-only reply opens the native Sheet.
    3. Release the older week reply. It contains items-body and shell regions, deliberately no drawer boundary: it must not replace a current command form or key.
    4. Close the Sheet through the native drawer partial, which answers an empty item-drawer.
    5. The other-day fallbacks remain pending. The startup report says “Superseded Fresh partial response was drained”; no resumed body request follows close.

    Observed at375 px in all four light/dark × normal/reduced-motion cases, with no browser pageerror and no command/effect. Consumer evidence source rickylabs/garage-booking@497f219ab8c0d0b69c65e9bb4f2ac104cc665011; the first served fallback is garage-booking#532.

    A useful qualification would cover this exact overlay-open/release/close order and verify either preserved deferred application or a documented native re-request policy. Latest-intent ordering must still protect the new drawer and its current command identity; applying an obsolete whole page is not an acceptable fix.

    Current public PartialNavigationCoordinator exports navigate, subscribe, dispose; the0.0.9 reference does not document a deferred resumption hook. The app ships a selected-day eager list with ordinary typed day navigation, and will restore seven eager days using a backend range read. It adds no parallel fetch/cache/history/resumption layer.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions