tungsten 0.7.2 → 0.8.0

package/AGENTS.md

@@ -87,7 +87,8 @@ Two consequences that cause real bugs:
 | `clientDirs` / `clientPatterns` | Sources the browser pipeline compiles. Unset, everything. |
 | `rawDirs` / `rawPatterns` | Sources the node pipeline compiles (types stripped, imports untouched) — server middleware and the like. Unset, nothing. |
 | `ignoreDirs` / `ignorePatterns` | Sources neither pipeline compiles. No default. Each pipeline compiles its selection **and not** these, so an ignored folder cannot be selected back in. `ignoreDirs: ['server']` suits an app whose own build emits its server code; to have Tungsten compile the server, narrow `clientDirs` and select it in `rawDirs` instead. |
-| `serverMiddleware` | `[file, exportName, mountPath]` — Express handlers mounted on Tungsten's own server, so a frontend and an API can share one process. Loaded from the raw pipeline's output when the file is in `rawDirs`, otherwise from `codeDir`. |
+| `serverMiddleware` | `[file, exportName, mountPath]` — Express handlers mounted on Tungsten's own server, so a frontend and an API can share one process. Loaded from the raw pipeline's output when the file is in `rawDirs`, otherwise from `codeDir`. In dev (unreleased) it is loaded once and reloaded when a `.js` file under `codeDir` changes, not on every request — so module-level state lasts until the next edit, as in prod. |
+| `serverIgnoreDirs` / `serverIgnorePatterns` | Dev: files under `codeDir` whose changes don't reload `serverMiddleware`, in the shapes of `ignoreDirs` / `ignorePatterns`. Test files never do. No default; e.g. `serverIgnoreDirs: ['client']`. |
 | `defaultCacheControl` | The `Cache-Control` of prod pages that set none themselves (see [Page caching](#page-caching)). Unset, pages are sent without one. |
 | `serverSideRouting` | 0.7.1+. Unset is `true`. `false`: the server runs none of the app's code for a page. It does no routing and fetches no data, and sends the same stub for every URL (status 200): the root component's `<html>`, `<head>` and `<body>` with nothing in them. The client then fetches the global data (or the pipeline's all-routes data) beside its first routing, with the route data, and builds the head and body. A pipeline app runs, in order: `clientInit`/`init`, then the all-routes data beside routing, then `clientPost`/`post`, then `clientAfterRouting`. A route data redirect is followed on the client before anything is built. Turns `csr` on, and needs a root component. The root's own `content` still runs on the server, and registered stores are built there with an empty context, so neither may depend on the data. Static generation writes the stub for each listed route; routes found only by following links are not found. |
 
@@ -109,6 +110,28 @@ This is correct and intentional. Do not "fix" it to `.tsx`/`.ts` or extensionles
 Typical scripts: `dev` = `tsc --watch` alongside `tungsten dev`; `build` = `tsc && tungsten build`;
 `start` = `tungsten start`.
 
+### TightScript declarations (unreleased)
+
+Tungsten also ships declarations written for TightScript, the TypeScript fork with permission
+modifiers (`rw`, `exact`, `owned`, …). The runtime code is the same either way; only the types
+differ. An app compiled with the fork opts in through an export condition in its `tsconfig.json`:
+
+```jsonc
+"compilerOptions": {
+    "customConditions": ["tightscript"],
+    "permissionModifiers": true,
+    "permissionDefaults": "read" // the default; tungsten's declarations are written for it
+}
+```
+
+Without the condition, an app gets the stock TypeScript declarations, which is what stock `tsc`
+needs: it can't parse TightScript's modifiers. TightScript's global declarations are
+`tungsten/types-ti/*`, used alongside `tungsten/types/*`.
+
+Under these declarations tungsten asks for write permission where it writes. For example, an object
+bound to an input must be writable (`rw`), so a form object declared read-only is refused at the
+`bind`.
+
 ## Components
 
 Base classes, exported from `tungsten` with both a long and a short name
@@ -164,7 +187,9 @@ export class Greeting extends StatefulComponent<Props, State> {
   page components** — the last call wins, so a nested component setting it will fight the page.
 - `this.tungsten` holds framework helpers bound to the component (0.7.1+):
   `this.tungsten.getRoutes()` gives the app's routes as this request resolved them (the function
-  form called for you), for rendering nav; `this.tungsten.fileUrl('/logo.png')` gives a site
+  form called for you), for rendering nav. Name their type to read their fields:
+  `getRoutes<typeof routes>()` (unreleased; unchecked beyond being routes, so name the app's own,
+  with `import type`). `this.tungsten.fileUrl('/logo.png')` gives a site
   file's URL with its cache-busting version (see **Styling**). `this.tungsten.instance` is this
   component's instance — the same object as `this.__instance`, under a name that is part of the
   API rather than a convention.
@@ -185,7 +210,8 @@ Each hook has a React-style name and a short alias:
 | `componentDidUnmount` | `_deleted` | |
 
 Put browser-only work (`window`, `location`, `localStorage`) in `clientInit` or a later client
-hook — never unguarded in `init`, route code, or `content`.
+hook — never unguarded in `init`, route code, or `content`. A browser-only value the *first render*
+needs (a stored theme) goes through `DocInit()` instead — see **Inline scripts and styles**.
 
 Other instance members worth knowing: `this.props`, `this.routeParams`, `this.routeData`,
 `this.globalData`, `this.triggerUpdate()` (manual re-render),
@@ -322,6 +348,13 @@ export const getRoutes = (reqRes: ReqResOrNull) => [
 
   `routesWith<Rule>()` takes the routes as separate arguments and returns them keyed by path; its
   rule applies to every route, `'404'` included.
+- **`makeRouteWith<Rule>()`** (unreleased) returns a `route()` that requires the rule's fields, so
+  a route missing one is flagged by itself instead of marking the whole list:
+
+  ```tsx
+  const appRoute = makeRouteWith<{ name: string }>()
+  appRoute({ path: '/', name: 'Home', content: <Home /> })
+  ```
 
 ### Path parameters
 
@@ -373,7 +406,59 @@ Type params with `Params<'id'>` or `ParamsFromPath<'/things/:id'>`.
 - From a `data` function, **return** `new RoutingRedirect(path)` (in-app) or
   `new WebRedirect(url)` (full browser redirect) instead of data. `RedirectCode` sets the status.
 - As content, render `<RouteRedirectComponent to="/path" />`.
+- Both in-app forms redirect under `siteBasePath` on the server, as `goto()` does (unreleased;
+  before, the server sent the bare route path).
+- Global data — classic `globalData` and the pipeline's all-routes data, on either side of a split
+  pipeline — may return the same redirects (unreleased). It wins over the route's redirect, and Post
+  does not run. It is handed the location (route path plus query) as its last argument, since no
+  route has matched yet: check it, or a redirect to `/login` redirects `/login` again.
 - `<MatchedRoute />` renders the active route; it belongs in the root component's `<body>`.
+- **A pipeline recovers to its `'error'` route** (unreleased): the route renders in the root,
+  with status 500 and `Cache-Control: no-store`, and the app keeps running. `.routes()` requires
+  one, as routing can always fail (a type error, for a returned tuple or object):
+
+  | Fails | Then |
+  | --- | --- |
+  | routing or route data | Post, then the `'error'` route |
+  | the all-routes data, with a fallback | the fallback is the data, Post, then the `'error'` route |
+  | Init; the all-routes data with no fallback; Post; the fallback; the render | the error page |
+
+  The fallback is the all-routes data function's second argument (also `serverAllRoutesData`,
+  `clientAllRoutesData`): a whole value of its type, or a function of the same arguments plus the
+  error, which may return a redirect. A static value is shared by every request, so never mutate
+  it. A redirect from the all-routes data wins over a route data throw. The route's data is
+  `{ error, message }`; in prod `message` is `'server error'`. In prod the page carries the
+  message only to the browser, as does a classic `'error'` route's; in dev it carries the error
+  too, with its stack. A client navigation recovers in place; past recovery it loads the page
+  from the server.
+
+  ```tsx
+  .allRoutesData(loadUser, (reqRes, init, location, error) =>
+      isUnauthorized(error) ? new WebRedirect(logInUrl(location)) : guestUser)
+  ...
+  .routes(() => [
+      ...,
+      { path: 'error', content: (info: TungstenErrorInfo) => <ErrorPanel message={info.message} /> },
+  ])
+  ```
+- **A pipeline's error page** (unreleased) is `.errorPage(Page)` before `.routes()`, for what
+  recovery cannot reach. `Page` extends the stage's
+  `ErrorComponent` and renders the whole document, `<html>` included: no root is around it. When a
+  request fails past recovery, after Init, the server sends it with status 500, with props
+  `{ error, message }`, Init's context and networked data (Post never ran), and
+  `this.tungsten.allRoutesData` that may be `undefined` (it may be what threw). On the prod server
+  `message` is `'server error'`, not the error's own; `error` is the thrown value either way,
+  server-side only. In prod the page carries only the message to the browser (in dev, the error
+  too), which hydrates it the same way, with client navigation off. Optional: without one, or when Init or the page itself throws,
+  the framework's error page is sent.
+
+  ```tsx
+  const withData = pipeline.server('express').init(...).allRoutesData(...)
+  class ErrorPage extends withData.ErrorComponent {
+      content = () => <html><head>…</head><body><p>{this.props.message}</p></body></html>
+  }
+  export const app = withData.post(...).errorPage(ErrorPage).routes(() => [...])
+  ```
 
 ### Page caching
 
@@ -693,18 +778,65 @@ The React idiom `<script dangerouslySetInnerHTML={{ __html: code }} />` exists b
 HTML-escapes script children; Tungsten does not, so the idiom is unnecessary — do not carry it
 over. As with any framework, the string itself must not contain `</script>`.
 
-A boot script that runs before hydration (theme, colour scheme) usually wants to set an attribute
-on `<html>` or `<body>`. **Hydration reconciles attributes to what the component rendered and
-removes any it did not** (`reconcileHydratedAttributes.ts`), so an attribute the script set on an
-element the root component renders is stripped the moment that element hydrates — reported in dev
-as a mismatch banner (`data-theme: rendered null, server sent …`), silently in prod. Deriving the
-value on the client instead (`localStorage` in `clientInit`) does not help: the hydration render
-then differs from the server's markup, which is the same mismatch from the other side, on every
-load. The server has to know the value: **keep such a preference in a cookie**, read it
-server-side (`reqRes` / global data) and render the attribute from the root component, so both
-renders agree — no boot script, no flash, no mismatch. A value the server cannot know (`'auto'`,
-i.e. `prefers-color-scheme`) should render no attribute at all, with CSS `@media
-(prefers-color-scheme: dark)` as the fallback when `data-theme` is absent.
+A hand-written boot script that sets an attribute on `<html>` or `<body>` (theme, colour scheme)
+does not survive hydration. **Hydration reconciles attributes to what the component rendered and
+removes any it did not** (`reconcileHydratedAttributes.ts`), so the attribute is stripped the moment
+that element hydrates — reported in dev as a mismatch banner (`data-theme: rendered null, server
+sent …`), silently in prod. Deriving the value in `clientInit` does not help either: the first
+client render then differs from the server's markup. Two ways to make the renders agree:
+
+- **The server knows the value** — keep the preference in a cookie or the database, read it
+  server-side (`reqRes` / global data) and render the attribute from the root component. No script
+  needed.
+- **Only the browser knows it** (`localStorage`, `prefers-color-scheme`) — use
+  [`DocInit()`](#docinit--code-that-runs-before-body), which runs the script for you and hands the
+  same value to the client render.
+
+### `DocInit()` — code that runs before `<body>`
+
+`DocInit` is an ambient global, like `Sass` — no import. Its function is inlined into the document
+head as a synchronous script, so it runs on every full page load before `<body>` exists, before
+first paint and before the app bundle. The call evaluates to that function's return value on the
+client, and to the second argument on the server:
+
+```tsx
+export class Root extends SimpleStoreComponent {
+    theme = DocInit(() => {
+        const theme = localStorage.getItem('theme') ?? 'light'
+        document.documentElement.dataset.theme = theme
+        return theme
+    }, 'light')   // what the server sees; DocInit(() => { … }) alone is the void form
+
+    content = () =>
+        <html data-theme={this.theme}>…</html>
+}
+```
+
+**Render whatever the script changed from the value it returned**, as above. Hydration compares the
+client render with the live DOM, so the attribute the head script set and the attribute the client
+render produces agree, and nothing is stripped. Markup rendered from the server value that the
+script did *not* also change is still a mismatch.
+
+The rules, enforced at build by `BabelTransformDocInit` with a code frame:
+
+- **The function must be self-contained.** Only browser globals (`document`, `localStorage`, …)
+  exist in the head. A module import, an outer variable, `this` from the class, a named function
+  passed by reference, parameters, `async` and generators are all build errors. Write helpers
+  inline in the function.
+- **Only a direct call of the global is recognised.** An alias (`const D = DocInit`) or a wrapper is
+  not rewritten, and reaches a stand-in global that throws naming the cause. A local binding named
+  `DocInit` is left alone.
+- **A throw halts the page — there is no fallback** to the server value. The error appears in the
+  console where it happened, a read of the value throws, and in dev a red banner names the call
+  site. Guard what can fail (`localStorage` throws when site data is blocked) inside the function.
+- **The value is fixed for the page load.** It is not reactive; copy it into state or the store in
+  `init` if it can change later, and update the DOM yourself when it does.
+- **An HMR edit to a module using `DocInit` falls back to a full reload**, since the head script
+  only runs on a full load.
+
+Tests run compiled output without the build transform, so the global is the throwing stand-in.
+Call `installTestDocInit()` from `tungsten/testing/installTestDocInit.js` in the test setup: it runs
+the function where a `document` exists and returns the server value where it does not.
 
 ## Form binding
 
@@ -827,6 +959,13 @@ page does, then runs the client stages and hydrates. A component whose store or
 the pipeline's context needs these: `createTestApp()` and `hydrateTestApp()` run no pipeline, so its
 context is empty.
 
+`routesOf(app, reqRes | null)` (unreleased, same import) gives a pipeline app's routes as `host()`'s
+`routes` option takes them, for a component that reads the route table (a nav): it runs the app's
+Init for the side `isServer` says this is - the server's needs a request, and throws on `null` -
+and calls the routes function with its result. `routesOf(app, initResult)` skips Init and uses the
+result given, typed as the routes function's `init` parameter:
+`host(Nav, {}, { location: '/', routes: routesOf(app, { context }) })`.
+
 Stores are created independently per test app; initialize one with `testStore()` before the root
 component starts. Component tests that need the application's env globals opt in by calling
 `loadEnv({ buildLocation })` once from the test runner `setup` hook, where `buildLocation` is the

package/dist/.build-complete

@@ -1 +1 @@
-1791130589286
+1792235388722

package/dist/Components.d.ts

@@ -141,6 +141,8 @@ export declare abstract class TungstenBaseComponent<Props extends TungstenCompon
     shouldStoreComponentUpdate?: (key: Key, data: unknown) => boolean;
     static tagName?: string;
     static displayName?: string;
+    static render?: ComponentRenderInfo;
+    static noEscape?: boolean;
     static __opaque?: boolean;
     constructor(pkg: ConstructPackage<Props, RouteData>);
     get globalData(): GlobalData;
@@ -176,7 +178,7 @@ export declare abstract class TungstenSimpleComponent<Props extends TungstenComp
     componentDidRender?: ((prevProps: Props) => void | Promise<void>) | (() => void | Promise<void>);
     _rendered?: ((prevProps: Props) => void | Promise<void>) | (() => void | Promise<void>);
     __init: () => Promise<void>;
-    __initialContent: () => ContentNode | Promise<ContentNode>;
+    __initialContent: () => Promise<ContentNode> | ContentNode;
     __runUpdate: () => Promise<UpdateResult>;
     __updateAndReturnContent: () => Promise<{
         content: ContentNode;
@@ -204,7 +206,7 @@ export declare abstract class TungstenComponent<Props extends TungstenComponentP
     static displayName?: string;
     constructor(pkg: ConstructPackage<Props, RouteData>);
     __init: () => Promise<void>;
-    __initialContent: () => ContentNode | Promise<ContentNode>;
+    __initialContent: () => Promise<ContentNode> | ContentNode;
     __runUpdate: () => Promise<UpdateResult>;
     __handleTitle: () => void;
     setState: (stateUpdates: State) => void;
@@ -230,7 +232,7 @@ export declare abstract class TungstenStatefulComponent<Props extends TungstenCo
     static displayName?: string;
     constructor(pkg: ConstructPackage<Props, RouteData>);
     __init: () => Promise<void>;
-    __initialContent: () => ContentNode | Promise<ContentNode>;
+    __initialContent: () => Promise<ContentNode> | ContentNode;
     __runUpdate: () => Promise<UpdateResult>;
     __updateAndReturnContent: () => Promise<{
         content: ContentNode;
@@ -271,7 +273,7 @@ export declare abstract class TungstenSignalsComponent<Props extends TungstenCom
     static displayName?: string;
     constructor(pkg: ConstructPackage<Props, RouteData>);
     __init: () => Promise<void>;
-    __initialContent: () => ContentNode | Promise<ContentNode>;
+    __initialContent: () => Promise<ContentNode> | ContentNode;
     __runUpdate: () => Promise<UpdateResult>;
     __updateAndReturnContent: () => Promise<{
         content: ContentNode;

package/dist/Components.js

@@ -342,6 +342,8 @@ export class TungstenBaseComponent {
 }
 _defineProperty(TungstenBaseComponent, "tagName", void 0);
 _defineProperty(TungstenBaseComponent, "displayName", void 0);
+_defineProperty(TungstenBaseComponent, "render", void 0);
+_defineProperty(TungstenBaseComponent, "noEscape", void 0);
 // rendered once, then owns its dom: the parent never re-renders it (see updateClassComponent)
 _defineProperty(TungstenBaseComponent, "__opaque", void 0);
 export class TungstenSimpleComponent extends TungstenBaseComponent {

package/dist/Framework.js

@@ -169,9 +169,9 @@ export class Framework {
       // dev only: only tungsten build sets quiet, so this check cannot fire yet
       if (!this.quiet) cliOut(`Creating dev server`);
       // TS define requires a var to exist or not, so we will initialize it to undefined to satisfy this expectation
-      global.tungstenPublicEnv = {};
+      globalThis.tungstenPublicEnv = {};
       // should we default the debug value? we'd have issues if they set DEBUG to undef
-      global.tungstenPrivateEnv = {/*TUNGSTEN_SERVER_PORT: -999*/};
+      globalThis.tungstenPrivateEnv = {/*TUNGSTEN_SERVER_PORT: -999*/};
       //cliOut(`Try Load Env`)
       //this.loadEnv()
       if (this.config === undefined) throwError('Framework.createDevServer()', 'config is undefined');
@@ -201,9 +201,9 @@ export class Framework {
     For validators, load env, pass to validators, receive result and write
     */
     // TS global var definition requires a var to exist or not, so we will initialize it to undefined to satisfy this expectation
-    global.tungstenPublicEnv = {};
+    globalThis.tungstenPublicEnv = {};
     // should we default the debug value? we'd have issues if they set DEBUG to undef
-    global.tungstenPrivateEnv = {/*TUNGSTEN_SERVER_PORT: -999*/};
+    globalThis.tungstenPrivateEnv = {/*TUNGSTEN_SERVER_PORT: -999*/};
     // Load schemas
     const envSchemas = await getEnvSchemas(config);
     let someEnvLoaded = false;
@@ -265,7 +265,7 @@ export class Framework {
       if (!coreResult.success) {
         throwError('Framework.createEnvProd()', 'Your private environment variables don\'t meet the Tungsten requirements\n' + coreResult.problems);
       }
-      global.tungstenPrivateEnv = coreResult.value;
+      globalThis.tungstenPrivateEnv = coreResult.value;
       if (!this.quiet) cliOut('tungsten private env loaded and passed schema validation'); // save this so that we can show all messages about loading .env files first
     }
     if ('publicEnvSchema' in envSchemas) {
@@ -289,10 +289,10 @@ export class Framework {
       if (!coreResult.success) {
         throwError('Framework.createEnvProd()', 'Your public environment variables don\'t meet the Tungsten requirements\n' + coreResult.problems);
       }
-      global.tungstenPublicEnv = coreResult.value;
+      globalThis.tungstenPublicEnv = coreResult.value;
       // save to public env file
       const clientContents = readFileSync(join(projectDir, bundleFolder, 'client.js'), 'utf-8');
-      const publicEnvContent = windowGlobalEnvStatement('tungstenPublicEnv', global.tungstenPublicEnv);
+      const publicEnvContent = windowGlobalEnvStatement('tungstenPublicEnv', globalThis.tungstenPublicEnv);
       const clientWithEnvHandle = openSync(join(projectDir, bundleFolder, 'clientWithEnv.js'), 'w');
       writeFileSync(clientWithEnvHandle, publicEnvContent);
       writeFileSync(clientWithEnvHandle, clientContents);

package/dist/FrameworkConfig.d.ts

@@ -36,6 +36,8 @@ export type FrameworkConfigBase = {
     skipPackageCompilation?: string | string[];
     sourceMaps?: boolean;
     serverMiddleware?: ServerMiddlewareInfo;
+    serverIgnoreDirs?: string | string[];
+    serverIgnorePatterns?: string | string[];
     apiRoutes?: string;
     apiPath?: string;
     suppressNoHeadWarning?: boolean;
@@ -43,7 +45,6 @@ export type FrameworkConfigBase = {
     suppressEnvOverwriteWarnings?: boolean;
     hmr?: boolean | 'reload';
     csr?: boolean;
-    serverSideRouting?: boolean;
     defaultCacheControl?: CacheControl;
     registration?: Registration;
 };
@@ -51,9 +52,11 @@ export type Registration = 'register' | 'pipeline';
 export type FrameworkConfigWithRootComponent = FrameworkConfigBase & {
     useRootComponent?: true;
     rootComponent: string;
+    serverSideRouting?: boolean;
 };
 export type FrameworkConfigWithoutRootComponent = FrameworkConfigBase & {
     useRootComponent: false;
+    serverSideRouting?: true;
 };
 export type FrameworkConfig = FrameworkConfigWithRootComponent | FrameworkConfigWithoutRootComponent;
 export type FrameworkConfigCompleteBase = {
@@ -89,6 +92,8 @@ export type FrameworkConfigCompleteBase = {
     skipPackageCompilation?: string | string[];
     sourceMaps?: boolean;
     serverMiddleware?: ServerMiddlewareInfo;
+    serverIgnoreDirs?: string | string[];
+    serverIgnorePatterns?: string | string[];
     apiRoutes?: string;
     apiPath: string;
     suppressNoHeadWarning: boolean;
@@ -97,16 +102,17 @@ export type FrameworkConfigCompleteBase = {
     warnOnFrameworkChange: boolean;
     hmr: boolean | 'reload';
     csr: boolean;
-    serverSideRouting?: boolean;
     defaultCacheControl?: CacheControl;
     registration?: Registration;
 };
 export type FrameworkConfigCompleteWithRootComponent = FrameworkConfigCompleteBase & {
     useRootComponent: true;
     rootComponent: string;
+    serverSideRouting?: boolean;
 };
 export type FrameworkConfigCompleteWithoutRootComponent = FrameworkConfigCompleteBase & {
     useRootComponent: false;
+    serverSideRouting?: true;
 };
 export type FrameworkConfigComplete = FrameworkConfigCompleteWithRootComponent | FrameworkConfigCompleteWithoutRootComponent;
 export type FrameworkConfigOverrides = Pick<FrameworkConfigCompleteBase, 'ignoreDirs' | 'ignorePatterns' | 'sourceMaps'>;

package/dist/Instance/Instance.d.ts

@@ -11,6 +11,7 @@ import type { ClientRuntimeContext } from './ClientRuntimeContext.js';
 import type { RouteKey } from '../routing/RouteTypes.js';
 import type { ClientRoute } from '../pipeline/pipelineDefinition.js';
 import type { BrandedContext, BrandedGlobalData, BrandedNetworkedData } from '../Brands.js';
+import { type TungstenErrorInfo } from '../routing/TungstenErrorInfo.js';
 type DisposableComponent = {
     __delete: () => void;
     __deleted: () => void;
@@ -19,7 +20,8 @@ export type NavigationCause = 'navigate' | 'history';
 export type InstancePipeline = {
     routingContext: BrandedContext;
     routingNetworkedData: BrandedNetworkedData;
-    allRoutesData: (() => Promise<BrandedGlobalData>) | undefined;
+    allRoutesData: ((location: string) => Promise<BrandedGlobalData>) | undefined;
+    allRoutesDataFallback?: ((location: string, error: unknown) => Promise<BrandedGlobalData>) | undefined;
     afterRouting: ((route: ClientRoute, allRoutesData: object) => Promise<BrandedContext>) | undefined;
 };
 export declare class Instance {
@@ -49,6 +51,7 @@ export declare class Instance {
         url: string;
         code: RedirectCode;
     } | undefined;
+    errorInfo: TungstenErrorInfo | undefined;
     pipeline: InstancePipeline | undefined;
     pipelineNetworked: object;
     constructor(location: string, instanceConfig: InstanceConfig, reqRes: ReqRes | null, appRoutes: AppRoutes<any>, routes: Routes<any>, internalStore: InternalStore, stores: TrueStore<any>[], storeSubscriptions: StoreSubscriptionsMap, globalData: BrandedGlobalData, matchedRouteInfo: MatchedRouteInfo, runtimeContext?: ClientRuntimeContext);
@@ -63,6 +66,8 @@ export declare class Instance {
         cause?: NavigationCause;
     }) => Promise<void>;
     redirect: (url: string, code?: RedirectCode) => void;
+    private routeClassic;
+    private routePipeline;
     httpTo: (url: string) => void;
     httpReload: () => void;
     setDefaultTitle: (defaultTitle: string) => void;

package/dist/Instance/Instance.js

@@ -14,8 +14,9 @@ import { globalDataFunc } from '../routing/registerGlobalData.js';
 import { tAssert } from '../assert.js';
 import { throwError } from '../throwError.js';
 import { clientRoute } from '../pipeline/pipelineDefinition.js';
+import { settleRouting } from '../pipeline/settleRouting.js';
 export class Instance {
-  constructor(_location, instanceConfig, reqRes, appRoutes, routes,
+  constructor(_location, instanceConfig, reqRes, appRoutes, _routes,
   //globalData: GlobalData,
   //matchedRouteInfo: MatchedRouteInfo
   internalStore, stores, storeSubscriptions, _globalData, _matchedRouteInfo, runtimeContext) {
@@ -56,6 +57,8 @@ export class Instance {
     _defineProperty(this, "registeredComponents", []);
     // set when the server has answered the request with a redirect, so it sends nothing more
     _defineProperty(this, "redirected", undefined);
+    // set when the page is the pipeline's error page: written into it, for hydration to know it
+    _defineProperty(this, "errorInfo", undefined);
     // the pipeline's, set by hydratePipeline(): client navigation routes with Init's context, as
     // the server did, and reruns the all-routes data. Unset, goto() takes the classic path
     _defineProperty(this, "pipeline", undefined);
@@ -103,32 +106,19 @@ export class Instance {
       navigating.set(true);
       // get route data
       try {
-        let matchedRouteInfo;
-        // global data runs before any route renders, here as before SSR; beside routing, as there
-        let globalData = this.globalData;
         const pipeline = this.pipeline;
-        try {
-          [matchedRouteInfo, globalData] = await Promise.all([pipeline === undefined ? routing(path, this.getRoutes(), this.context, this.networkedData) : routing(path, this.getRoutes(), pipeline.routingContext, pipeline.routingNetworkedData), pipeline === undefined ? globalDataFunc.value?.(null, this.context, this.networkedData) ?? globalData : pipeline.allRoutesData?.() ?? globalData]);
-        } catch (error) {
-          errorOut(`Tungsten client navigation to '${path}' failed while loading route data:`, error);
-          const errorRoute = this.routes.error;
-          // Without an app-defined error route there's nothing better to show; at
-          // least this is now a logged, caught rejection rather than a silent
-          // unhandled one that left the previous page frozen with no feedback.
-          if (errorRoute === undefined) return;
-          matchedRouteInfo = {
-            key: 'error',
-            params: {},
-            content: errorRoute.content,
-            data: makeTungstenErrorInfo(error)
-          };
-        }
+        const routed = pipeline === undefined ? await this.routeClassic(path) : await this.routePipeline(pipeline, path);
+        if (routed === undefined) return;
+        const {
+          matchedRouteInfo,
+          globalData
+        } = routed;
         //console.log('matchedRouteInfo', location, matchedRouteInfo)
         //console.log('matched route info', this.matchedRouteInfo)
         if (i !== navigationIndex.get()) return; // another nav has taken over
         // A redirect to a URL leaves the app: on the server redirect() writes an HTTP redirect;
         // in the browser it replaces the location
-        const redirection = redirectOf(matchedRouteInfo);
+        const redirection = redirectOf(matchedRouteInfo, globalData);
         if (redirection !== undefined) {
           // awaited, so goto() settles when the navigation it started has
           if ('route' in redirection) await this.goto(redirection.route);else this.redirect(redirection.url, redirection.code);
@@ -184,6 +174,56 @@ export class Instance {
         runtimeWindow.location.replace(url);
       }
     });
+    // goto()'s routing, with the global data beside it, as before SSR. Undefined: nothing to show
+    _defineProperty(this, "routeClassic", async path => {
+      try {
+        const [matchedRouteInfo, globalData] = await Promise.all([routing(path, this.getRoutes(), this.context, this.networkedData), globalDataFunc.value?.(null, this.context, this.networkedData, path) ?? this.globalData]);
+        return {
+          matchedRouteInfo,
+          globalData
+        };
+      } catch (error) {
+        errorOut(`Tungsten client navigation to '${path}' failed while loading route data:`, error);
+        const errorRoute = this.routes.error;
+        // Without an app-defined error route there's nothing better to show; at
+        // least this is now a logged, caught rejection rather than a silent
+        // unhandled one that left the previous page frozen with no feedback.
+        if (errorRoute === undefined) return undefined;
+        const matchedRouteInfo = {
+          key: 'error',
+          params: {},
+          content: errorRoute.content,
+          data: makeTungstenErrorInfo(error)
+        };
+        return {
+          matchedRouteInfo,
+          globalData: this.globalData
+        };
+      }
+    });
+    // A pipeline's, recovering to the 'error' route where it can. Past that the server renders its
+    // error page: undefined, as the page loads from the server
+    _defineProperty(this, "routePipeline", async (pipeline, path) => {
+      const routes = this.getRoutes();
+      const getAllRoutesData = pipeline.allRoutesData;
+      const fallback = pipeline.allRoutesDataFallback;
+      const current = this.globalData;
+      try {
+        const settled = await settleRouting(routes, async () => routing(path, routes, pipeline.routingContext, pipeline.routingNetworkedData), async () => getAllRoutesData === undefined ? current : getAllRoutesData(path), fallback && (async error => fallback(path, error)), makeTungstenErrorInfo);
+        if (settled.recoveredFrom !== undefined) {
+          errorOut(`Tungsten client navigation to '${path}' failed, showing the error route:`, settled.recoveredFrom);
+        }
+        const globalData = settled.allRoutesData; // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion -- the framework brands what it builds
+        return {
+          matchedRouteInfo: settled.matchedRouteInfo,
+          globalData
+        };
+      } catch (error) {
+        errorOut(`Tungsten client navigation to '${path}' failed while loading route data:`, error);
+        this.httpTo(this.routeKeyToUrl(path));
+        return undefined;
+      }
+    });
     _defineProperty(this, "httpTo", url => {
       if (!isClient) {
         throwError('gotoHttp', 'Cannot modify window location on the server');
@@ -255,7 +295,7 @@ export class Instance {
     this.stores = stores;
     this.storeSubscriptions = storeSubscriptions;
     this.appRoutes = appRoutes;
-    this.routes = routes;
+    this.routes = _routes;
     this.globalData = _globalData;
     this.matchedRouteInfo = _matchedRouteInfo;
     this.config = instanceConfig; // createInstanceConfig(appConfig)

package/dist/Servers/DevServer.d.ts

@@ -20,15 +20,17 @@ export declare class DevServer extends TungstenServer {
     apiRoutes?: ApiRoutes;
     apiPath?: string;
     server?: Server;
-    reqId: number;
     firstRender: boolean;
     iterationCount: number;
     serverIterationCount: number;
     private liveReloadClients;
     private unsubscribeReload;
+    private watchedMiddleware;
     private bootId;
     constructor(framework: Framework, config: FrameworkConfigComplete, compilationInfo: CompilationInfo, initialProcessEnv?: Record<string, string>);
     private addServerMiddleware;
+    private addWatchedServerMiddleware;
+    private addPerRequestServerMiddleware;
     private handleLiveReloadStream;
     private reloadDebounceTimer;
     private pendingReloadKind;
@@ -36,13 +38,14 @@ export declare class DevServer extends TungstenServer {
     private static readonly reloadDebounceMs;
     private broadcastReloadEvent;
     private sourceFileToUrlPath;
-    private pipelineHandler;
     private handleRequestApi;
     private handleRequest;
+    private handleRequestPipeline;
+    private renderPipelinePage;
     private tryRenderErrorRoute;
-    getGlobalData: (func: BrandedGlobalDataFunction, reqRes: ReqRes, context: BrandedContext, networkedData: BrandedNetworkedData) => Promise<BrandedGlobalData>;
-    errorLog: (error: unknown) => void;
-    errorPage: (error: unknown, errorTrack: string[]) => string;
+    getGlobalData: (func: BrandedGlobalDataFunction, reqRes: ReqRes, context: BrandedContext, networkedData: BrandedNetworkedData, location: string) => Promise<BrandedGlobalData>;
+    printError: (error: unknown, errorSites?: string[]) => void;
+    errorPage: (error: unknown, errorSites: string[]) => string;
     start: () => Promise<{
         localOrigin: string;
         publicOrigin: string;