@ultimat3/render 25.2.0 → 26.1.0

package/src/navigation.ts

@@ -10,25 +10,29 @@
  * over instead of letting `fetch` follow it, and a POST is never re-submitted — after a failed
  * one, only the server knows what landed.
  *
- * Loaded as one deferred classic script (`@ultimat3/cli` builds it to `/_x/navigation/<hash>.js`)
- * on documents whose surface opted in (`navigation: { client: [...] }` in `app.config.ts`).
+ * Loaded as one deferred classic script (`@ultimat3/cli` builds it to
+ * `/_x/assets/navigation/<hash>.js`) on documents whose surface opted in (`navigation: { client:
+ * [...] }` in `app.config.ts`).
  */
 
-import { CLIENT_BUILD_META, CLIENT_SCOPE_META } from '@ultimat3/core/page';
 import { navigationCache } from './navigation-cache';
 import {
   anchorOf,
   announcer,
   focusMain,
-  formAction,
-  formFields,
-  formPairs,
   handOver,
+  intentUrl,
   linkFacts,
-  type RunningTransition,
+  submitFacts,
   transition,
 } from './navigation-dom';
-import { type Answer, fetchDocument, metaOf } from './navigation-fetch';
+import {
+  type Answer,
+  fetchDocument,
+  heldOrFetched,
+  metaOf,
+  responseFactsOf,
+} from './navigation-fetch';
 import {
   type EntryState,
   entryOf,
@@ -36,25 +40,22 @@ import {
   scrollAfter,
   withoutFragment,
 } from './navigation-history';
+import { modalController } from './navigation-modal';
+import { addressOf, modalAddress, modalHistory } from './navigation-modal-rules';
+import { pressTracker } from './navigation-press';
 import {
   answerMovesTab,
-  type FormFacts,
   formVerdict,
   linkVerdict,
-  mayPrefetch,
   NAVIGATE_EVENT,
   NAVIGATED_EVENT,
   NAVIGATING_ATTRIBUTE,
   NAVIGATION_ERROR_EVENT,
   NAVIGATION_MAX_HOPS,
   NAVIGATION_META,
-  NAVIGATION_NO_PREFETCH_ATTRIBUTE,
   NAVIGATION_PREFETCH_DELAY_MS,
   NAVIGATION_PROGRESS_DELAY_MS,
-  NAVIGATION_RELOAD_ATTRIBUTE,
-  type ResponseFacts,
   responseVerdict,
-  reusable,
 } from './navigation-rules';
 import { scrollKeeper } from './navigation-scroll';
 import {
@@ -74,11 +75,19 @@ export interface NavigateOptions {
   readonly history?: 'push' | 'replace' | 'none';
   /** Redirects already followed for this navigation. */
   readonly hops?: number;
+  /** The URL's hash addressed it: a modal, or nothing — never a page (`presentation`). */
+  readonly fromHash?: boolean;
 }
 
 export interface NavigationRouter {
   navigate(url: string, options?: NavigateOptions): Promise<void>;
   prefetch(url: string): void;
+  /** The page on screen, fetched again and swapped in where it is scrolled. */
+  refresh(): Promise<void>;
+  /** `path` as the modal over this page (`#<path>`); anything but a modal of this tab: nothing. */
+  openModal(path: string): Promise<void>;
+  /** As Escape: Back through the router's own entry, else the hash dropped in place. */
+  closeModal(): void;
   stop(): void;
 }
 
@@ -104,15 +113,11 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   let rendered = withoutFragment(win.location.href);
   /** The URL a navigation in flight is fetching: a prefetch never asks for it a second time. */
   let navigatingTo: string | undefined;
-  /** The view transition still animating — skipped only for a click it swallowed (`onClick`). */
-  let animating: RunningTransition | undefined;
-  /** Between a press and its click: the focus the press gives a link is not a hover. */
-  let pressed = false;
-  /** The press landed while a transition was painting over the page (see `onClick`). */
-  let pressedOverTransition = false;
+  const press = pressTracker(doc);
   /** The pending prefetch of a hover, cancelled by anything that navigates. */
   let intent: number | undefined;
   let untrusted = false;
+  let backing = false; // a Back this router started is traversing: the URL is still the one left
   let inflight: AbortController | undefined;
   const live = announcer(doc);
   const owned = documentHead(doc);
@@ -120,6 +125,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   const tabs = tabSync(win, () => cache.clear());
   const forget = tabs.forget;
   const scroll = scrollKeeper(win, () => rendered);
+  const modal = modalController(win, () => rendered, ran, owned);
 
   const request = (url: string, purpose: 'soft' | 'prefetch', init?: RequestInit) =>
     fetchDocument(win, doc, url, purpose, init);
@@ -138,7 +144,11 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   const failed = (url: string, method: string, reason: string): void => {
     const detail = { url, method, reason };
     const event = new CustomEvent(NAVIGATION_ERROR_EVENT, { detail, cancelable: true });
-    if (doc.dispatchEvent(event)) win.location.assign(win.location.href);
+    if (!doc.dispatchEvent(event)) return;
+    // Under a modal the URL differs only by its hash, which `assign` merely scrolls to: reloaded,
+    // the page and its modal are both asked for again (the entry is the router's own GET).
+    if (modal.address === undefined) win.location.assign(win.location.href);
+    else win.location.reload();
   };
 
   const answerFor = (
@@ -154,22 +164,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
       const body = options.body === undefined ? {} : { body: options.body };
       return request(url, 'soft', { method, ...body, signal }).finally(forget);
     }
-    const held = cache.peek(url);
-    cache.delete(url);
-    if (held === undefined) return request(url, 'soft', { signal });
-    return held.value.then(
-      (answer) =>
-        reusable({
-          status: answer.status,
-          html: answer.html !== null,
-          location: answer.location,
-          noStore: answer.noStore,
-          ageMs: held.ageMs,
-        })
-          ? answer
-          : request(url, 'soft', { signal }),
-      () => request(url, 'soft', { signal }),
-    );
+    return heldOrFetched(cache, url, () => request(url, 'soft', { signal }));
   };
 
   const navigate = async (url: string, options: NavigateOptions = {}): Promise<void> => {
@@ -183,7 +178,8 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     // After an answer for another principal or build was shown in place, this tab is no longer
     // trusted to swap: every navigation is a real load (`answerMovesTab`).
     if (untrusted && method === 'GET') {
-      win.location.assign(url);
+      if (options.fromHash === true) modal.clear();
+      else win.location.assign(url);
       return;
     }
     const detail = { url, method };
@@ -212,22 +208,20 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
       if (mine.signal.aborted) return;
       const next =
         answer.html === null ? null : new DOMParser().parseFromString(answer.html, 'text/html');
-      const facts: ResponseFacts = {
+      const facts = responseFactsOf(doc, next, answer, { method, requested: url, hops });
+      const verdict = responseVerdict(facts);
+      const landed = `${withoutFragment(url)}${new URL(url).hash}`;
+      const shown = modal.presentationOf(next, landed, {
+        fromHash: options.fromHash === true,
         method,
-        requested: url,
+        verdict: verdict.kind,
         status: answer.status,
-        opaqueRedirect: answer.opaqueRedirect,
-        location: answer.location,
-        contentType: answer.contentType,
-        hops,
-        surface: metaOf(doc, NAVIGATION_META),
-        nextSurface: next === null ? null : metaOf(next, NAVIGATION_META),
-        build: metaOf(doc, CLIENT_BUILD_META),
-        nextBuild: answer.build ?? (next === null ? null : metaOf(next, CLIENT_BUILD_META)),
-        scope: metaOf(doc, CLIENT_SCOPE_META),
-        nextScope: next === null ? null : metaOf(next, CLIENT_SCOPE_META),
-      };
-      const verdict = responseVerdict(facts);
+        movesTab: answerMovesTab(facts),
+      });
+      if (shown === 'degrade') {
+        modal.clear();
+        return;
+      }
       switch (verdict.kind) {
         case 'stay':
           return;
@@ -242,7 +236,8 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
           return;
         case 'follow':
           await navigate(verdict.url, {
-            history: options.history === 'none' ? 'replace' : 'push',
+            // Out of a modal, a redirect's target takes the modal's entry: Back never reopens it.
+            history: options.history === 'none' || modal.address !== undefined ? 'replace' : 'push',
             hops: hops + 1,
           });
           return;
@@ -253,18 +248,26 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
           break;
       }
       if (next === null) return;
-      const landed = `${withoutFragment(url)}${new URL(url).hash}`;
+      // A page answered while a modal is open: the modal goes, and so does its history entry.
+      const leave = shown === 'page' ? modal.leaveFor(options.history, landed) : undefined;
+      const history = leave === undefined ? options.history : leave === 'back' ? 'none' : leave;
       try {
         // Owned from the moment they are appended: a navigation aborted after this point left its
         // sheets in the head for good, styling every page after it — the next swap retires an
         // owned sheet its page does not link.
         await loadStylesheets(doc, missingStylesheets(doc, next), owned);
         if (mine.signal.aborted) return;
+        if (shown === 'modal') {
+          await modal.present(next, addressOf(landed), landed, modalHistory(method, history));
+          doc.dispatchEvent(new CustomEvent(NAVIGATED_EVENT, { detail: { url: landed } }));
+          return;
+        }
+        if (leave === 'back') {
+          backing = true;
+          win.history.back();
+        }
+        modal.dismiss();
         let swapped: ReturnType<typeof swapDocument> | undefined;
-        const track = (running: RunningTransition, finished: boolean): void => {
-          if (!finished) animating = running;
-          else if (animating === running) animating = undefined;
-        };
         await transition(
           win,
           () => {
@@ -275,16 +278,16 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
             live.textContent = '';
             swapped.body.append(live);
             rendered = withoutFragment(landed);
-            if (options.history !== 'none') {
-              const same = landed === win.location.href || options.history === 'replace';
+            if (history !== 'none') {
+              const same = landed === win.location.href || history === 'replace';
               const state = { [STATE_KEY]: { scroll: [0, 0], doc: rendered } satisfies EntryState };
               if (same) win.history.replaceState(state, '', landed);
               else win.history.pushState(state, '', landed);
             }
             // Inside the swap, so a view transition's "after" frame is already where the page lands.
-            scrollAfter(win, doc, landed, options.history);
+            scrollAfter(win, doc, landed, history);
           },
-          track,
+          press.track,
         );
         const done = swapped;
         if (done === undefined) return;
@@ -302,6 +305,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
         focusMain(doc);
         live.textContent = doc.title;
         doc.dispatchEvent(new CustomEvent(NAVIGATED_EVENT, { detail: { url: landed } }));
+        reconcile();
       } catch {
         // A swap that failed part-way leaves a page nobody rendered: a GET is loaded for real; a
         // POST's answer cannot be asked for again, so the visitor is told and shown this page.
@@ -319,64 +323,30 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   };
 
   const onPress = (): void => {
-    pressed = true;
-    pressedOverTransition = animating !== undefined;
+    press.onPress();
     // A press is not a hover: the click it becomes navigates, and a guess on its heels is a
-    // second request for the same page. A press alone never skips the running transition — that
-    // snapped every named element to its end mid-glide (#621); only the click below may.
+    // second request for the same page.
     win.clearTimeout(intent);
   };
-  const onRelease = (): void => {
-    pressed = false;
-  };
 
   const onClick = (event: MouseEvent): void => {
     win.clearTimeout(intent);
-    // While a view transition paints, the browser hit-tests every press to `<html>` — Chrome does
-    // so whatever `pointer-events` the `::view-transition` overlay has — so the click reached
-    // nothing: the visitor's first click after a swap was lost. It is given to the element under
-    // the pointer, whatever it is: a link, a submit button, an island's own control. Only a
-    // skipped transition hit-tests the page, so the skip happens HERE, at the click, never at
-    // the press; when the animation already ended between the two, there is nothing to skip.
-    if (pressedOverTransition && event.target === doc.documentElement) {
-      pressedOverTransition = false;
-      animating?.skipTransition?.();
-      const hit = doc.elementFromPoint(event.clientX, event.clientY);
-      if (hit !== null && hit !== doc.documentElement && hit instanceof HTMLElement) hit.click();
-      return;
-    }
+    if (press.overlayClick(event)) return;
     const anchor = anchorOf(event.target);
     if (anchor === null) return;
     const verdict = linkVerdict(linkFacts(win, anchor, event));
     if (verdict.kind !== 'soft') return;
     event.preventDefault();
-    void navigate(verdict.url);
+    // A link to the page beneath an open modal (its Cancel) closes the modal: nothing is fetched.
+    if (modal.address !== undefined && withoutFragment(verdict.url) === rendered) modal.close();
+    else void navigate(verdict.url);
   };
 
   const onSubmit = (event: SubmitEvent): void => {
     const form = event.target;
     // An untrusted tab (`answerMovesTab`) leaves every form to the browser.
     if (!(form instanceof HTMLFormElement) || untrusted) return;
-    const submitter = event.submitter;
-    const fields = formFields(form, submitter);
-    const say = (attr: string, fallback: string): string =>
-      submitter?.getAttribute(`form${attr}`) ?? form.getAttribute(attr) ?? fallback;
-    const facts: FormFacts = {
-      action: formAction(say('action', ''), win.location.href, doc.baseURI),
-      current: win.location.href,
-      method: say('method', 'get').toLowerCase(),
-      enctype: say('enctype', 'application/x-www-form-urlencoded').toLowerCase(),
-      target: say('target', ''),
-      defaultPrevented: event.defaultPrevented,
-      reload:
-        form.hasAttribute(NAVIGATION_RELOAD_ATTRIBUTE) ||
-        submitter?.hasAttribute(NAVIGATION_RELOAD_ATTRIBUTE) === true,
-      // `unknown`: a browser yields a `File` for a file input, whatever a server-side type says.
-      hasFile: [...fields.values()].some(
-        (value: unknown) => value instanceof File && value.name !== '',
-      ),
-      fields: formPairs(fields),
-    };
+    const { facts, fields } = submitFacts(win, form, event.submitter, event.defaultPrevented);
     const verdict = formVerdict(facts);
     if (verdict.kind === 'native') return;
     event.preventDefault();
@@ -393,27 +363,12 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
 
   const onIntent = (event: Event): void => {
     // The focus a press gives a link: its click is a moment away, and it navigates.
-    if (event.type === 'focusin' && pressed) return;
-    const anchor = anchorOf(event.target);
-    if (anchor === null) return;
-    const verdict = linkVerdict(linkFacts(win, anchor));
-    const connection = (
-      win.navigator as { connection?: { saveData?: boolean; effectiveType?: string } }
-    ).connection;
-    if (
-      verdict.kind !== 'soft' ||
-      !mayPrefetch({
-        url: verdict.url,
-        noPrefetch: anchor.hasAttribute(NAVIGATION_NO_PREFETCH_ATTRIBUTE),
-        saveData: connection?.saveData,
-        effectiveType: connection?.effectiveType,
-      })
-    ) {
-      return;
-    }
+    if (event.type === 'focusin' && press.pressed()) return;
+    const url = intentUrl(win, event.target);
+    if (url === undefined) return;
     win.clearTimeout(intent);
     const delay = event.type === 'pointerover' ? NAVIGATION_PREFETCH_DELAY_MS : 0;
-    intent = win.setTimeout(() => prefetch(verdict.url), delay);
+    intent = win.setTimeout(() => prefetch(url), delay);
   };
   const onLeave = (): void => win.clearTimeout(intent);
 
@@ -424,7 +379,10 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
    */
   const onPop = (event: PopStateEvent): void => {
     scroll.cancel();
-    const url = win.location.href;
+    backing = false;
+    // The page is the PATH: a modal's hash is the modal's (`reconcile`), never the page's fragment.
+    const at = win.location.href;
+    const url = modalAddress(new URL(at).hash, at) === null ? at : withoutFragment(at);
     const entry = entryOf(event.state);
     const wanted = entry?.doc ?? withoutFragment(url);
     const same =
@@ -442,40 +400,76 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
         behavior: 'instant' as ScrollBehavior,
       });
     }
+    reconcile();
   };
 
+  /**
+   * The modal follows the URL's hash, once the page on screen is the URL's: opened (fetched, as a
+   * hash address, so a stale one degrades), kept, or dismissed. On start, on Back/Forward, on a
+   * typed hash, and after every page swap — a Back onto a modal's entry swaps its page first.
+   */
+  function reconcile(): void {
+    // Until that Back lands, the hash still names the modal just left: it would be opened again.
+    if (backing) return;
+    const at = win.location.href;
+    if (withoutFragment(at) !== rendered) return;
+    const wanted = modalAddress(new URL(at).hash, at);
+    if (wanted === null) modal.dismiss();
+    else if (wanted !== modal.address) {
+      void navigate(new URL(wanted, at).href, { history: 'none', fromHash: true });
+    }
+  }
+
   // `window`, bubble phase: after every handler on the page — Solid delegates to `document` — has
   // had its chance to `preventDefault`, which the rules then honour.
-  win.addEventListener('click', onClick);
-  win.addEventListener('submit', onSubmit);
-  doc.addEventListener('pointerover', onIntent, { passive: true });
-  doc.addEventListener('pointerout', onLeave, { passive: true });
-  doc.addEventListener('focusin', onIntent);
-  doc.addEventListener('touchstart', onIntent, { passive: true });
-  win.addEventListener('popstate', onPop);
-  doc.addEventListener('pointerdown', onPress, { capture: true, passive: true });
-  doc.addEventListener('pointerup', onRelease, { capture: true, passive: true });
-  doc.addEventListener('pointercancel', onRelease, { capture: true, passive: true });
+  const passive = { passive: true };
+  const pressing = { capture: true, passive: true };
+  const listeners: readonly (readonly [EventTarget, string, EventListener, object?])[] = [
+    [win, 'click', onClick as EventListener],
+    [win, 'submit', onSubmit as EventListener],
+    [doc, 'pointerover', onIntent, passive],
+    [doc, 'pointerout', onLeave, passive],
+    [doc, 'focusin', onIntent],
+    [doc, 'touchstart', onIntent, passive],
+    [win, 'popstate', onPop as EventListener],
+    [win, 'hashchange', reconcile],
+    [doc, 'pointerdown', onPress, pressing],
+    [doc, 'pointerup', press.onRelease, pressing],
+    [doc, 'pointercancel', press.onRelease, pressing],
+  ];
+  for (const [target, type, listener, options] of listeners) {
+    target.addEventListener(type, listener, options);
+  }
 
   const router: NavigationRouter = {
     navigate,
     prefetch,
+    refresh() {
+      // A fresh answer for the page on screen, landing where the visitor is scrolled.
+      cache.delete(rendered);
+      scroll.save();
+      return navigate(rendered, { history: 'none' });
+    },
+    openModal(path) {
+      const address = modalAddress(`#${path}`, win.location.href);
+      if (address === null) return Promise.resolve();
+      return navigate(new URL(address, win.location.href).href, {
+        fromHash: true,
+        history: 'push',
+      });
+    },
+    closeModal: () => modal.close(),
     stop() {
-      win.removeEventListener('click', onClick);
-      win.removeEventListener('submit', onSubmit);
-      doc.removeEventListener('pointerover', onIntent);
-      doc.removeEventListener('pointerout', onLeave);
-      doc.removeEventListener('focusin', onIntent);
-      doc.removeEventListener('touchstart', onIntent);
-      win.removeEventListener('popstate', onPop);
-      doc.removeEventListener('pointerdown', onPress, { capture: true });
-      doc.removeEventListener('pointerup', onRelease, { capture: true });
-      doc.removeEventListener('pointercancel', onRelease, { capture: true });
+      for (const [target, type, listener, options] of listeners) {
+        target.removeEventListener(type, listener, options);
+      }
+      modal.dismiss();
       scroll.stop();
       tabs.stop();
       delete win.__xNavigation;
     },
   };
   win.__xNavigation = router;
+  reconcile();
   return router;
 }

package/src/registry.ts

@@ -1,6 +1,6 @@
 /**
  * The route table — the single source of route truth. File path → URL conventions for
- * `site/`, `app/` and `api/`, plus `describePages()`, the serializable projection that
+ * `site/` and `app/`, plus `describePages()`, the serializable projection that
  * `x.manifest.json`, the `/_x` routes panel, the sitemap and `sw.js` are all generated
  * from. Nothing downstream may keep its own list of routes.
  */
@@ -31,40 +31,31 @@ import { isRouteConfig, routeTagKeys } from './route';
 import type { RouteComponent } from './route-component';
 import type { CompiledPattern } from './route-pattern';
 import { compilePattern } from './route-pattern';
-import type { Surface } from './surfaces';
+import type { RouteSurface, Surface } from './surfaces';
 import { locateSurface } from './surfaces';
 
 /**
- * The one filename a route may carry, per surface. `shared/` is `Exclude`d rather than merely
- * absent: it is a leaf of helpers with no URL, so a route file there has nowhere to resolve to —
- * and stating that in the key type makes the other three MANDATORY. `Partial<Record<Surface, …>>`
- * said the same thing about `shared` and let any of the three go missing, which only three
- * registration tests would have caught. A dropped `api` row is not a crash: `assertRouteFilename`
- * reads `undefined` as "this file is under shared/", so every `api/` route author would have been
- * told their file is a leaf of helpers.
+ * The one filename a route may carry, per route surface. Keyed by `RouteSurface`, so both rows are
+ * MANDATORY: a dropped row would read as `undefined` in `assertRouteFilename`.
  */
-export const ROUTE_FILENAME = Object.freeze<Record<Exclude<Surface, 'shared'>, string>>({
+export const ROUTE_FILENAME = Object.freeze<Record<RouteSurface, string>>({
   site: 'page.tsx',
   app: 'page.tsx',
-  api: 'route.ts',
 });
 
 /** Stems that already meant "this directory", so the repair is a rename in place, not a new folder. */
 const DIRECTORY_STEMS = new Set(['index', 'page', 'route']);
 
-const API_PREFIX = '/api';
-
 export interface RouteEntry<TData = RouteData> {
   readonly file: string;
   readonly path: string;
-  readonly surface: Surface;
+  readonly surface: RouteSurface;
   readonly config: RouteConfig<TData>;
   readonly suspenseBoundaries: number;
   readonly islands: readonly string[];
   readonly pattern: CompiledPattern;
   /**
-   * The module's page component. Absent for `api/` routes and for a module that exports none —
-   * a `spa` shell is the mode that legitimately has no server-rendered body.
+   * The module's page component. Absent for a module that exports none.
    */
   readonly component?: RouteComponent;
 }
@@ -119,9 +110,8 @@ export type { MountedRouteInput, RouteMount, RouteMountInput } from './mounted-r
  * | `site/blog/[slug]/page.tsx` | `/blog/:slug` |
  * | `site/docs/[...path]/page.tsx` | `/docs/*path` |
  * | `app/dashboard/page.tsx` | `/dashboard` |
- * | `api/posts/route.ts` | `/api/posts` |
  */
-export function routePathFromFile(file: string): { surface: Surface; path: string } {
+export function routePathFromFile(file: string): { surface: RouteSurface; path: string } {
   const normalized = file.replace(/\\/g, '/').replace(/^\.\//, '');
   // One reader of the surface segment, and it answers WHERE as well as WHICH. Slicing at
   // `indexOf('app/')` instead matched inside `myapp/`, so `apps/myapp/app/page.tsx` resolved to
@@ -130,10 +120,10 @@ export function routePathFromFile(file: string): { surface: Surface; path: strin
   if (located === null) {
     throw new SurfaceBoundaryError(
       `${file} is not inside a surface directory, so it has no URL and no bundle graph`,
-      `move ${file} under site/, app/ or api/`,
+      `move ${file} under site/ or app/, named page.tsx`,
     );
   }
-  const surface = located.surface;
+  const surface = routeSurfaceOf(normalized, located.surface);
 
   const rawSegments = located.rest.split('/').filter((s) => s.length > 0);
   assertRouteFilename(normalized, surface, rawSegments[rawSegments.length - 1]);
@@ -143,8 +133,7 @@ export function routePathFromFile(file: string): { surface: Surface; path: strin
     .filter((s) => !(s.startsWith('(') && s.endsWith(')')))
     .map(toUrlSegment);
 
-  const base = surface === 'api' ? API_PREFIX : '';
-  const path = `${base}/${urlSegments.join('/')}`.replace(/\/+$/, '') || '/';
+  const path = `/${urlSegments.join('/')}`.replace(/\/+$/, '') || '/';
   return { surface, path };
 }
 
@@ -156,20 +145,37 @@ export function routePathFromFile(file: string): { surface: Surface; path: strin
 const shellQuote = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`;
 
 /**
- * Enforced rather than documented (axiom 3): a convention that is not a build error is not a
- * convention. The fix is the move that makes the file a route, spelled out — the directory the
- * author already meant, plus the one filename that surface accepts.
+ * Only `site/` and `app/` hold route files. `shared/` is a leaf of helpers with no URL; `api/` is
+ * the action and query projections `defineApi()` collects — a wire format an action cannot speak
+ * is a plain HTTP route in the `routes` runtime override, never a file under `api/`.
  */
-function assertRouteFilename(file: string, surface: Surface, basename: string | undefined): void {
-  // `shared` is the one surface with no filename, and the key type now says so — which is why
-  // this is a comparison rather than an `undefined` check on the lookup.
-  const expected = surface === 'shared' ? undefined : ROUTE_FILENAME[surface];
-  if (expected === undefined) {
+function routeSurfaceOf(file: string, surface: Surface): RouteSurface {
+  if (surface === 'shared') {
     throw new RouteFileInvalidError(
       `${file} is under shared/, which is a leaf of helpers with no URL — a route cannot live there`,
-      `move ${file} under site/, app/ or api/, named page.tsx (site/, app/) or route.ts (api/)`,
+      `move ${file} under site/ or app/, named page.tsx`,
     );
   }
+  if (surface === 'api') {
+    throw new RouteFileInvalidError(
+      `${file} is under api/, which holds no route file: api/ is the actions and queries defineApi() collects`,
+      `JSON in and out: replace ${file} with an action (x g action <name>) collected by defineApi() in api/index.ts. Another wire format (a webhook, an OAuth endpoint): delete ${file} and add a plain HTTP route to the routes array exported as runtime from apps/<app>/runtime.ts`,
+    );
+  }
+  return surface;
+}
+
+/**
+ * Enforced rather than documented (axiom 3): a convention that is not a build error is not a
+ * convention. The fix is the move that makes the file a route, spelled out — the directory the
+ * author already meant, plus the one filename that surface accepts.
+ */
+function assertRouteFilename(
+  file: string,
+  surface: RouteSurface,
+  basename: string | undefined,
+): void {
+  const expected = ROUTE_FILENAME[surface];
   if (basename === expected) return;
 
   // The directory the author meant is the file's own path minus its extension: `site/pricing.tsx`

package/src/route.ts

@@ -191,11 +191,19 @@ export type RouteCache = 'no-store' | Omit<CacheHint, 'tags'>;
  * in on a click, never fetched before one. `'prefetch'`: may also be fetched on intent — only for a
  * page whose GET does nothing but render. `'document'`: always a real document load, the route run
  * once by the browser — for a GET that records something (an open, a download, a token consumed).
- * The server enforces both before `load` (`@ultimat3/http`'s navigation gate).
+ * `'modal'`: presented OVER the page a visitor came from, addressed by the hash
+ * (`/runs#/runs/new`) — a create form, a confirmation; a full load of its own URL is still the
+ * whole page. Never fetched before a click. The server enforces all three before `load`
+ * (`@ultimat3/http`'s navigation gate) and names a modal in its document
+ * (`NAVIGATION_PRESENTATION_META`).
  */
-export type RouteNavigationMode = 'prefetch' | 'document';
+export type RouteNavigationMode = 'prefetch' | 'document' | 'modal';
 
-export const ROUTE_NAVIGATION_MODES: readonly RouteNavigationMode[] = ['prefetch', 'document'];
+export const ROUTE_NAVIGATION_MODES: readonly RouteNavigationMode[] = [
+  'prefetch',
+  'document',
+  'modal',
+];
 
 /** The input shape of `defineRoute` — exactly the contract's twelve keys, nothing else. */
 export interface RouteDefinition<TData = RouteData> {

package/src/surfaces.ts

@@ -11,6 +11,12 @@ import { SurfaceBoundaryError } from './errors';
 
 export type Surface = 'site' | 'app' | 'api' | 'shared';
 
+/**
+ * The two surfaces a route file lives on. `api/` is a surface for the import boundary only: it holds
+ * the action and query projections `defineApi()` collects, and no route file.
+ */
+export type RouteSurface = Exclude<Surface, 'api' | 'shared'>;
+
 export const SURFACES = ['site', 'app', 'api', 'shared'] as const;
 
 export interface SurfaceSpec {