@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.186

package/dist/server/children-interception.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Children-path interception — the sibling layout swap (TIM-1280).
+ *
+ * The second shape interception has. An intercepting directory that is a
+ * direct child of an ordinary segment or route group renders *in place of*
+ * `children` for that directory's own layout chain:
+ *
+ * ```
+ * app/(landing)/layout.tsx
+ * app/(landing)/[artistSlug]/[year]/[month]/[day]/page.tsx      ← hard nav
+ * app/(browse)/layout.tsx
+ * app/(browse)/(...)[artistSlug]/[year]/[month]/[day]/page.tsx  ← soft nav from (browse)
+ * ```
+ *
+ * There is no overlay, no slot, and no `default.tsx`. Nothing is re-matched
+ * either — and that is the point. The modal shape re-matches
+ * `interceptingPrefix`, a URL, and route groups contribute nothing to a URL,
+ * so an owner like `app/(browse)/` serializes to "/" and re-matching it
+ * resolves through whichever group owns the canonical page. This resolver
+ * addresses the owner by **tree path** instead, which never collapses.
+ *
+ * The result is an ordinary `RouteMatch` whose chain runs
+ * `[…owner ancestors, interceptingNode, …its matched descendants]`. Every
+ * consumer downstream — `tree-builder.ts`, the element builder, access gates,
+ * middleware — sees a segment chain and needs to know nothing about
+ * interception. That is why this feature adds no rendering path: the chain
+ * *is* the feature.
+ *
+ * See design/07-routing.md §"Intercepting Routes".
+ */
+import type { RouteMatch } from './pipeline.js';
+import { type ManifestSegmentNode } from './route-matcher.js';
+/**
+ * Resolve a children-path interception to a complete route match.
+ *
+ * `interceptingScope` is the rewrite's own build-time field — the tree path of
+ * the directory that owns the interception. The pipeline has already
+ * established that the client's rendered tree passes through it; this
+ * translates it into the chain to render.
+ *
+ * Returns null when the scope names no directory in this manifest, or when no
+ * intercepting child of that directory matches the target. Both are fail-safe:
+ * the caller keeps the canonical target match, so the page the user gets is
+ * the one a hard navigation would have produced.
+ */
+export type InterceptedRouteMatcher = (targetPathname: string, interceptingScope: string) => RouteMatch | null;
+/** Build a children-path interception resolver over a runtime manifest. */
+export declare function createInterceptedRouteMatcher(root: ManifestSegmentNode): InterceptedRouteMatcher;
+//# sourceMappingURL=children-interception.d.ts.map

package/dist/server/children-interception.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"children-interception.d.ts","sourceRoot":"","sources":["../../src/server/children-interception.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAItF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,uBAAuB,GAAG,CACpC,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,KACtB,UAAU,GAAG,IAAI,CAAC;AAEvB,2EAA2E;AAC3E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,mBAAmB,GAAG,uBAAuB,CA4BhG"}

package/dist/server/default-status-page.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Framework default status page — the terminal fallback of the deny chain.
+ *
+ * design/10-error-handling.md §"Fallback Chain" ends every 4xx/5xx chain in a
+ * "framework default page". Before TIM-1258 that terminal did not exist: an app
+ * with no `404.tsx` / `4xx.tsx` / `error.tsx` got `Response(null, { status })` —
+ * a correct status code with an empty body. Browsers render that as a blank
+ * page, and static generation had nothing to write to `404.html`.
+ *
+ * This page is a plain HTML string rather than a React component on purpose:
+ * it is the *last* fallback, so it must not depend on the RSC → SSR pipeline
+ * (the machinery that may already have failed by the time we get here), and it
+ * must be renderable from the static build where no render environment exists.
+ * One builder is the single source of truth for both surfaces.
+ *
+ * Security: the page interpolates nothing but the status code, and the code is
+ * clamped to a plain integer before it reaches the markup. No request URL, no
+ * error message, no stack — see design/13-security.md principle 4.
+ */
+/** HTML content type used for every framework default page response. */
+export declare const DEFAULT_STATUS_PAGE_CONTENT_TYPE = "text/html; charset=utf-8";
+/** Human-readable phrase for a status code. Never caller-supplied text. */
+export declare function statusReasonPhrase(status: number): string;
+/**
+ * Build the framework default page for a status code as a full HTML document.
+ *
+ * The document is self-contained: no scripts, no external resources, no client
+ * JavaScript. It renders identically in `server` mode, in `static` mode's
+ * generated `404.html`, and with `clientJavascript: false`.
+ */
+export declare function defaultStatusPageHtml(status: number): string;
+/**
+ * Build the framework default page as an HTTP `Response`.
+ *
+ * `responseHeaders` carries whatever middleware/proxy already set (cookies,
+ * cache directives); the content type is overwritten because the body is
+ * always HTML regardless of what the route would have produced.
+ *
+ * The body is unconditional. HEAD is not this function's problem: the pipeline
+ * strips HEAD bodies at its single exit for every response shape, so a
+ * `method` parameter here would be one renderer's private copy of a rule that
+ * now holds framework-wide (TIM-1324).
+ */
+export declare function defaultStatusPageResponse(status: number, responseHeaders: Headers): Response;
+//# sourceMappingURL=default-status-page.d.ts.map

package/dist/server/default-status-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-status-page.d.ts","sourceRoot":"","sources":["../../src/server/default-status-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA+BH,wEAAwE;AACxE,eAAO,MAAM,gCAAgC,6BAA6B,CAAC;AAc3E,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIzD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA+B5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,GAAG,QAAQ,CAG5F"}

package/dist/server/deny-renderer.d.ts

@@ -31,14 +31,25 @@ export type DebugChannelFactory = () => {
 };
 /** Callback to pass RSC stream to SSR for HTML rendering. */
 export type CallSsrFn = (rscStream: ReadableStream<Uint8Array>, navContext: NavContext) => Promise<Response>;
+/**
+ * Supplies a replacement for the framework default page at the end of the
+ * chain. Returning `null` keeps the framework default.
+ *
+ * The dev server uses this to substitute its route-listing 404 page. It is a
+ * parameter rather than a check on the produced Response because "the app
+ * authored no status page" is a fact about the *chain*, and inspecting the
+ * result for it (e.g. an empty body) stops being true the moment the chain
+ * grows a real terminal — which is exactly what TIM-1258 did.
+ */
+export type DefaultPageRenderer = (status: number, responseHeaders: Headers) => Response | null;
 /**
  * Render a status-code error page for a DenySignal.
  *
  * Resolves the appropriate status-code file from the segment chain based
- * on format preference. Returns an HTML Response (component), JSON Response,
- * or bare fallback Response.
+ * on format preference. Returns an HTML Response (component), a JSON Response,
+ * or the framework default status page.
  */
-export declare function renderDenyPage(deny: DenySignal, segments: ManifestSegmentNode[], layoutComponents: LayoutEntry[], req: Request, match: RouteMatch, responseHeaders: Headers, clientBootstrap: ClientBootstrapConfig, createDebugChannelSink: DebugChannelFactory, callSsr: CallSsrFn): Promise<Response>;
+export declare function renderDenyPage(deny: DenySignal, segments: ManifestSegmentNode[], layoutComponents: LayoutEntry[], req: Request, match: RouteMatch, responseHeaders: Headers, clientBootstrap: ClientBootstrapConfig, createDebugChannelSink: DebugChannelFactory, callSsr: CallSsrFn, defaultPage?: DefaultPageRenderer): Promise<Response>;
 /**
  * Render a status-code error page as a raw RSC Flight stream for client navigation.
  *

package/dist/server/deny-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deny-renderer.d.ts","sourceRoot":"","sources":["../../src/server/deny-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAU7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAOjE,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,iEAAiE;AACjE,MAAM,MAAM,mBAAmB,GAAG,MAAM;IACtC,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,CACtB,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,KACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;AAiCvB;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,WAAW,EAAE,EAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,qBAAqB,EACtC,sBAAsB,EAAE,mBAAmB,EAC3C,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,QAAQ,CAAC,CA+FnB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,WAAW,EAAE,EAC/B,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,EACxB,sBAAsB,EAAE,mBAAmB,GAC1C,OAAO,CAAC,QAAQ,CAAC,CA6CnB"}
+{"version":3,"file":"deny-renderer.d.ts","sourceRoot":"","sources":["../../src/server/deny-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAe7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAOjE,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,iEAAiE;AACjE,MAAM,MAAM,mBAAmB,GAAG,MAAM;IACtC,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,CACtB,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,KACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;AAiCvB;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,KAAK,QAAQ,GAAG,IAAI,CAAC;AAEhG;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,WAAW,EAAE,EAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,qBAAqB,EACtC,sBAAsB,EAAE,mBAAmB,EAC3C,OAAO,EAAE,SAAS,EAClB,WAAW,CAAC,EAAE,mBAAmB,GAChC,OAAO,CAAC,QAAQ,CAAC,CA0HnB;AAgBD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,WAAW,EAAE,EAC/B,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,EACxB,sBAAsB,EAAE,mBAAmB,GAC1C,OAAO,CAAC,QAAQ,CAAC,CA2CnB"}

package/dist/server/head-response.d.ts

@@ -0,0 +1,35 @@
+/**
+ * HEAD body stripping — RFC 9110 §9.3.2.
+ *
+ * "The HEAD method is identical to GET except that the server MUST NOT send
+ * content in the response." The headers, however, must be the ones the
+ * corresponding GET would have produced — which is why timber renders the
+ * route in full and discards the body here rather than short-circuiting the
+ * render. Content-Type, Content-Length, Set-Cookie, cache directives and
+ * everything else ride through untouched.
+ *
+ * Node's `ServerResponse` happens to discard writes for HEAD, so the wire is
+ * usually correct even without this. That is a property of one adapter, not of
+ * the `Response` object: static generation, the Cloudflare and Nitro adapters,
+ * tests, and anything calling the pipeline handler as a function all observe
+ * the `Response` directly and saw the full body before TIM-1324.
+ *
+ * The pipeline applies this at its single exit so every response shape is
+ * covered — page render, API route, metadata route, deny page, error page,
+ * proxy short-circuit. The two unit-level producers that are also reachable as
+ * standalone functions (`handleRouteRequest`, `handleApiRoute`) call it too, so
+ * each honours HEAD on its own; they share this implementation rather than
+ * repeating it, and applying it twice is a no-op.
+ */
+/**
+ * Return a bodyless copy of `response` when `method` is HEAD.
+ *
+ * A no-op for every other method and for responses that already carry no body
+ * (204, 304, redirects), so callers do not need to pre-check either.
+ *
+ * The discarded stream is cancelled: an SSR render that reached this point has
+ * a live producer attached, and dropping the reference without cancelling
+ * leaks it for the lifetime of the render (design/13-security.md A4).
+ */
+export declare function stripHeadBody(response: Response, method: string): Response;
+//# sourceMappingURL=head-response.d.ts.map

package/dist/server/head-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"head-response.d.ts","sourceRoot":"","sources":["../../src/server/head-response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAmB1E"}

package/dist/server/index.js

@@ -1,6 +1,6 @@
-import { D as getSegmentParams, J as withSpan, L as isDebug, P as getCookieJar, R as isDevMode, S as waitUntil, T as getHeaders, U as getSpanId, W as getTraceId, X as formFlashAls, _ as RedirectSignal, b as redirect, g as DenySignal, x as redirectExternal, y as deny, z as addSpanEvent } from "../_chunks/logger-AWfuX-KJ.js";
+import { D as getSegmentParams, J as withSpan, L as isDebug, P as getCookieJar, R as isDevMode, S as waitUntil, T as getHeaders, U as getSpanId, W as getTraceId, X as formFlashAls, _ as RedirectSignal, b as redirect, g as DenySignal, x as redirectExternal, y as deny, z as addSpanEvent } from "../_chunks/logger-N7e5auP0.js";
 import { t as formatSize } from "../_chunks/format-CfwjgPz9.js";
-import { a as parseFormData, i as coerce, n as revalidatePath, r as revalidateTag } from "../_chunks/actions-O_LsyCE4.js";
+import { a as parseFormData, i as coerce, n as revalidatePath, r as revalidateTag } from "../_chunks/actions-C-Rw9vPc.js";
 //#region src/shared/redirect-type.ts
 /**
 * Next.js redirect type discriminator.