foldkit 0.147.0 → 0.148.0

package/dist/experimental/server/host.js

@@ -92,21 +92,22 @@ export const acceptsHtml = (acceptHeader) => {
     return bestSpecificity > 0 && bestQuality > 0;
 };
 /**
- * Merges the `Accept` field name into an existing `Vary` header value, parsing
- * it as a comma-separated, case-insensitive list of field names. `Vary: *`
- * already varies on everything and is returned unchanged, an existing `Accept`
- * token (in any case, and distinct from `Accept-Language` or `Accept-Encoding`)
- * is not duplicated, and otherwise `Accept` is appended.
+ * Merges a field name into an existing `Vary` header value, parsing it as a
+ * comma-separated, case-insensitive list of field names. `Vary: *` already
+ * varies on everything and is returned unchanged, a token already present (in
+ * any case, and distinct from a longer name that merely starts with it, such as
+ * `Accept-Language` beside `Accept`) is not duplicated, and otherwise the field
+ * name is appended.
  *
- * A page host that negotiates HTML on the `Accept` header must declare that in
- * `Vary` so a shared cache does not serve one representation in place of the
- * other. The dev host, reference server, and scaffold merge through this one
- * helper so a comma-joined field-name string like `Accept-Language` is never
- * mistaken for the `Accept` field.
+ * A host whose response depends on a request header must declare that header in
+ * `Vary` so a shared cache does not serve one client's representation to
+ * another. The dev host, reference server, and scaffold merge through this one
+ * helper rather than assigning `Vary`, which would drop the fields already
+ * there.
  *
  * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
  */
-export const varyWithAccept = (existing) => {
+export const varyWith = (existing, fieldName) => {
     const tokens = existing === undefined
         ? []
         : existing
@@ -117,10 +118,61 @@ export const varyWithAccept = (existing) => {
     if (lowered.includes('*')) {
         return '*';
     }
-    if (lowered.includes('accept')) {
+    if (lowered.includes(fieldName.toLowerCase())) {
         return tokens.join(', ');
     }
-    return [...tokens, 'Accept'].join(', ');
+    return [...tokens, fieldName].join(', ');
+};
+/**
+ * Merges the `Accept` field name into an existing `Vary` header value.
+ *
+ * A page host that negotiates HTML on the `Accept` header must declare that in
+ * `Vary` so a shared cache does not serve one representation in place of the
+ * other.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export const varyWithAccept = (existing) => varyWith(existing, 'Accept');
+/**
+ * Resolves a request target against the origin the host serves, returning the
+ * absolute URL to hand the server entry, or `undefined` when the target names
+ * a different origin.
+ *
+ * A request target is not a URL. HTTP allows origin-form (`/page?q=1`) and
+ * absolute-form (`http://host/page`), and a client can send a network-path
+ * reference (`//elsewhere.example/page`) that resolves against no scheme at
+ * all. Resolving one of those against the host origin silently adopts the
+ * origin the client wrote, so an entry that derives redirects, canonical URLs,
+ * cookie domains, or tenant selection from `Request.url` would take them from
+ * the request rather than from the deployment. Only a target that resolves to
+ * the host's own origin is accepted; a host behind a proxy that must serve a
+ * different public origin passes that origin in explicitly.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export const resolveRequestUrl = (requestTarget, origin) => {
+    let base;
+    try {
+        base = new URL(origin);
+    }
+    catch {
+        return undefined;
+    }
+    let resolved;
+    try {
+        resolved = new URL(requestTarget, base);
+    }
+    catch {
+        return undefined;
+    }
+    // Credentials in the target are refused rather than passed along. `origin`
+    // ignores them, so `http://user:pass@host/page` reads as same-origin here and
+    // then makes `new Request(url)` throw, turning a malformed request into a 500
+    // instead of the 400 it is.
+    if (resolved.username !== '' || resolved.password !== '') {
+        return undefined;
+    }
+    return resolved.origin === base.origin ? resolved.href : undefined;
 };
 const normalizePath = (path) => {
     const segments = [];
@@ -136,6 +188,108 @@ const normalizePath = (path) => {
     }
     return segments.join('/');
 };
+// The `Sec-Fetch-Dest` values a browser sends for a subresource it fetches for
+// an already-loaded page, as opposed to a navigation (`document`, `iframe`,
+// `frame`) or a scripted fetch whose destination is `empty`. A request carrying
+// one of these is never a page request, whatever it says it accepts.
+const SUBRESOURCE_FETCH_DESTINATIONS = new Set([
+    'audio',
+    'audioworklet',
+    'embed',
+    'font',
+    'image',
+    'manifest',
+    'object',
+    'paintworklet',
+    'script',
+    'serviceworker',
+    'sharedworker',
+    'style',
+    'track',
+    'video',
+    'worker',
+    'xslt',
+]);
+const ASSET_EXTENSIONS = new Set([
+    'avif',
+    'bmp',
+    'cjs',
+    'css',
+    'csv',
+    'eot',
+    'gif',
+    'gz',
+    'ico',
+    'jpeg',
+    'jpg',
+    'js',
+    'json',
+    'map',
+    'mjs',
+    'mp3',
+    'mp4',
+    'ogg',
+    'otf',
+    'pdf',
+    'png',
+    'svg',
+    'ttf',
+    'txt',
+    'wasm',
+    'wav',
+    'webm',
+    'webmanifest',
+    'webp',
+    'woff',
+    'woff2',
+    'xml',
+    'zip',
+]);
+/**
+ * Classifies a request that no static file answered, from its path and, when
+ * the client sent one, its `Sec-Fetch-Dest`.
+ *
+ * A host answers a static miss by content negotiation, and a browser requests
+ * scripts, stylesheets, and images with `Accept: *​/*`, which accepts HTML. A
+ * request for a hashed asset that is no longer deployed would therefore be
+ * answered with the application shell at 200, so a stale bundle reads as a
+ * blank page rather than the 404 it is.
+ *
+ * The path is read first, so a request the URL alone settles is never made to
+ * depend on a header the client may or may not send.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export const classifyRequest = (requestUrl, fetchDestination) => {
+    let pathname;
+    try {
+        pathname = new URL(requestUrl, 'http://localhost').pathname;
+    }
+    catch {
+        pathname = '';
+    }
+    // Read the path a static file server would resolve, not the raw one. A file
+    // server percent-decodes before it looks for a file, so `/assets/a%2Ejs` and
+    // `/assets/a.js` name the same asset; classifying the raw form reads the
+    // first as an ordinary page and answers a missing bundle with the shell.
+    try {
+        pathname = decodeURIComponent(pathname);
+    }
+    catch {
+        // An undecodable path names no file, so leave it as written.
+    }
+    const lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);
+    const separator = lastSegment.lastIndexOf('.');
+    if (separator > 0 &&
+        ASSET_EXTENSIONS.has(lastSegment.slice(separator + 1).toLowerCase())) {
+        return 'PathAsset';
+    }
+    if (fetchDestination !== undefined &&
+        SUBRESOURCE_FETCH_DESTINATIONS.has(fetchDestination.trim().toLowerCase())) {
+        return 'DestinationAsset';
+    }
+    return 'Page';
+};
 /**
  * Decides whether a request path resolves to the `index.html` template, the
  * way a static file server resolves it: percent-decoded, backslashes and
@@ -167,3 +321,39 @@ export const resolvesToIndexHtml = (requestUrl) => {
     const normalized = normalizePath(decoded.replace(/\\/g, '/'));
     return normalized === '' || normalized.toLowerCase() === 'index.html';
 };
+/**
+ * The answer a host gives for the methods it cannot hand to a server entry.
+ *
+ * The WHATWG `Request` constructor rejects `CONNECT`, `TRACE`, and `TRACK`, so
+ * an entry can never be handed one: forwarding it turns a malformed request
+ * into a 500. A host refuses them itself, with `405` and an `Allow` header
+ * naming what it does forward.
+ *
+ * On Node only `TRACE` reaches this rule. The HTTP parser rejects `TRACK` with
+ * a 400 before any handler runs, and `CONNECT` arrives on its own event rather
+ * than as an ordinary request. Both are named anyway, so a host on another
+ * runtime refuses them rather than handing one to `new Request`.
+ *
+ * Every other method reaches the entry, `OPTIONS` included. A preflight is a
+ * question about a resource, so the application answers it: the entry can allow
+ * one origin for one route and refuse it for another, which no host-level
+ * policy could express. The Vite dev host applies Vite's CORS option only to
+ * Vite-owned modules and assets. An application preflight therefore reaches
+ * the entry rather than middleware a deployed host has no counterpart for.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export const HOST_METHOD_ANSWERS = {
+    refusedStatus: 405,
+    allow: 'GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS',
+};
+/**
+ * Whether a host refuses this method itself instead of calling the server
+ * entry. See {@link HOST_METHOD_ANSWERS}.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export const isHostSettledMethod = (method) => {
+    const normalized = method.toUpperCase();
+    return (normalized === 'CONNECT' || normalized === 'TRACE' || normalized === 'TRACK');
+};

package/dist/experimental/server/public.d.ts

@@ -1,3 +1,3 @@
-export { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE, FlagsEncodeError, InvalidHydrationRoot, InvalidRuntimeId, InvalidUrl, Rendered, Responded, SerializationError, acceptsHtml, injectIntoTemplate, renderToString, resolvesToIndexHtml, toResponse, varyWithAccept, } from './index.js';
-export type { InjectIntoTemplateOptions, ResponseOptions, RenderedApplication, RenderOptions, RenderUrlOptions, RenderFlagsOptions, RenderUrlFlagsOptions, ApplicationConfig, ApplicationConfigWithFlags, EntryModule, EntryResult, RenderError, RoutingApplicationConfig, RoutingApplicationConfigWithFlags, } from './index.js';
+export { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE, FlagsEncodeError, HOST_METHOD_ANSWERS, InvalidHydrationRoot, InvalidRuntimeId, InvalidUrl, MissingBuildId, Rendered, Responded, SerializationError, acceptsHtml, classifyRequest, injectIntoTemplate, isHostSettledMethod, renderToString, resolveRequestUrl, resolvesToIndexHtml, toResponse, varyWith, varyWithAccept, } from './index.js';
+export type { InjectIntoTemplateOptions, RequestClassification, ResponseOptions, RenderedApplication, HydratableRenderOptions, StaticRenderOptions, RenderOptions, RenderUrlOptions, RenderFlagsOptions, RenderUrlFlagsOptions, ApplicationConfig, ApplicationConfigWithFlags, EntryModule, EntryResult, RenderError, RoutingApplicationConfig, RoutingApplicationConfigWithFlags, } from './index.js';
 //# sourceMappingURL=public.d.ts.map

package/dist/experimental/server/public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAA;AAEnB,YAAY,EACV,yBAAyB,EACzB,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,0BAA0B,EAC1B,WAAW,EACX,WAAW,EACX,WAAW,EACX,wBAAwB,EACxB,iCAAiC,GAClC,MAAM,YAAY,CAAA"}
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,QAAQ,EACR,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,EACV,QAAQ,EACR,cAAc,GACf,MAAM,YAAY,CAAA;AAEnB,YAAY,EACV,yBAAyB,EACzB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,0BAA0B,EAC1B,WAAW,EACX,WAAW,EACX,WAAW,EACX,wBAAwB,EACxB,iCAAiC,GAClC,MAAM,YAAY,CAAA"}

package/dist/experimental/server/public.js

@@ -1 +1 @@
-export { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE, FlagsEncodeError, InvalidHydrationRoot, InvalidRuntimeId, InvalidUrl, Rendered, Responded, SerializationError, acceptsHtml, injectIntoTemplate, renderToString, resolvesToIndexHtml, toResponse, varyWithAccept, } from './index.js';
+export { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE, FlagsEncodeError, HOST_METHOD_ANSWERS, InvalidHydrationRoot, InvalidRuntimeId, InvalidUrl, MissingBuildId, Rendered, Responded, SerializationError, acceptsHtml, classifyRequest, injectIntoTemplate, isHostSettledMethod, renderToString, resolveRequestUrl, resolvesToIndexHtml, toResponse, varyWith, varyWithAccept, } from './index.js';

package/dist/experimental/server/serialize.d.ts

@@ -5,10 +5,15 @@ import type { VNode } from '../../snabbdom/vnode.js';
  *  the vnode's own data, so the stamp always wins over a same-named
  *  attribute in the view.
  *
+ * `emitHydrationMarkers` turns on the key and identity markers hydration
+ * verifies adoption against. They are part of the hydration handoff, so a
+ * render nobody will hydrate carries none of them.
+ *
  * @internal Not part of the `foldkit/experimental/server` surface; `renderToString` is the public entry to serialization.
  */
 export type SerializeOptions = Readonly<{
     rootAttributes?: Readonly<Record<string, string>>;
+    emitHydrationMarkers?: boolean;
 }>;
 /** Escapes a string for use as HTML text content.
  *
@@ -21,11 +26,16 @@ export declare const escapeText: (value: string) => string;
  */
 export declare const escapeAttributeValue: (value: string) => string;
 export declare const controlledValueContent: (properties: Readonly<Record<string, unknown>> | undefined) => string | undefined;
-/** Serializes a view-produced vnode tree to an HTML string. Event handlers,
- *  hooks, keys, and identity are behavior, not markup, and are skipped;
- *  attrs, class, dataset, prop-backed attributes, and inline style are
- *  emitted in that order. A `null` tree serializes to an empty comment,
- *  mirroring how the runtime patches `null` as a comment node.
+/** Serializes a view-produced vnode tree to an HTML string. Event handlers and
+ *  hooks are behavior, not markup, and are skipped; attrs, class, dataset,
+ *  prop-backed attributes, and inline style are emitted in that order. A `null`
+ *  tree serializes to an empty comment, mirroring how the runtime patches
+ *  `null` as a comment node.
+ *
+ * A hydratable render also stamps a digest of each vnode's key and identity, so
+ * hydration can tell one logical entity from another; the raw key and the
+ * compiler's source identity never appear in the markup. A render that is not
+ * hydratable emits neither.
  *
  * @internal Not part of the `foldkit/experimental/server` surface; `renderToString` is the public entry to serialization.
  */

package/dist/experimental/server/serialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/serialize.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAGpD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAClD,CAAC,CAAA;AA8MF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MACmC,CAAA;AAE9E;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,MAIlD,CAAA;AAuKH,eAAO,MAAM,sBAAsB,GACjC,YAAY,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,KACxD,MAAM,GAAG,SAMX,CAAA;AAmRD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,KAAK,GAAG,IAAI,EAClB,UAAU,gBAAgB,KACzB,MAOF,CAAA"}
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/serialize.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAGpD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B,CAAC,CAAA;AAsNF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MAM1C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,MAMpD,CAAA;AA0MD,eAAO,MAAM,sBAAsB,GACjC,YAAY,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,KACxD,MAAM,GAAG,SAMX,CAAA;AAugBD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,KAAK,GAAG,IAAI,EAClB,UAAU,gBAAgB,KACzB,MAUF,CAAA"}