foldkit 0.146.0 → 0.148.0

package/dist/experimental/server/host.js

@@ -0,0 +1,359 @@
+// NOTE: request-classification primitives shared by the dev host (the Vite
+// plugin), the reference server, and the scaffold, so development predicts
+// production. `acceptsHtml` parses the `Accept` header the way a browser
+// negotiates content, and `resolvesToIndexHtml` normalizes a request path the
+// way a static file server does, both of which are easy to get subtly wrong
+// when duplicated per host.
+const HTML_RANGE_SPECIFICITY = {
+    'text/html': 3,
+    'text/*': 2,
+    '*/*': 1,
+};
+const qualityOf = (parameters) => {
+    for (const parameter of parameters) {
+        const separator = parameter.indexOf('=');
+        if (separator === -1) {
+            continue;
+        }
+        const name = parameter.slice(0, separator).trim().toLowerCase();
+        if (name !== 'q') {
+            continue;
+        }
+        const value = Number(parameter.slice(separator + 1).trim());
+        return Number.isNaN(value) ? 1 : value;
+    }
+    return 1;
+};
+// NOTE: split on a delimiter only where it is not inside a double-quoted string,
+// so a quoted media-type parameter (`text/html;profile="a,b"`) is not torn apart
+// at the comma or semicolon inside its value. A backslash inside a quoted string
+// escapes the next character, so an escaped quote (`"a\",b"`) does not end the
+// string and its delimiter stays quoted.
+const splitOutsideQuotes = (value, delimiter) => {
+    const parts = [];
+    let current = '';
+    let isInQuotes = false;
+    let isEscaped = false;
+    for (const character of value) {
+        if (isEscaped) {
+            current += character;
+            isEscaped = false;
+        }
+        else if (isInQuotes && character === '\\') {
+            current += character;
+            isEscaped = true;
+        }
+        else if (character === '"') {
+            isInQuotes = !isInQuotes;
+            current += character;
+        }
+        else if (character === delimiter && !isInQuotes) {
+            parts.push(current);
+            current = '';
+        }
+        else {
+            current += character;
+        }
+    }
+    parts.push(current);
+    return parts;
+};
+/**
+ * Decides whether a client accepts an HTML response, given its `Accept`
+ * header. An absent or empty header accepts anything. Otherwise the most
+ * specific media range that covers `text/html` (`text/html`, then `text/*`,
+ * then `*​/*`) decides, using its `q` value, so `text/html;q=0` is refused
+ * even alongside `*​/*`.
+ *
+ * A page host renders the application for a request that accepts HTML and
+ * serves a non-page response otherwise, so this is the negotiation a host runs
+ * before falling through to a render.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export const acceptsHtml = (acceptHeader) => {
+    if (acceptHeader === undefined || acceptHeader.trim() === '') {
+        return true;
+    }
+    let bestSpecificity = 0;
+    let bestQuality = 0;
+    for (const range of splitOutsideQuotes(acceptHeader, ',')) {
+        const parts = splitOutsideQuotes(range, ';');
+        const mediaType = parts[0]?.trim().toLowerCase() ?? '';
+        const specificity = HTML_RANGE_SPECIFICITY[mediaType];
+        if (specificity === undefined) {
+            continue;
+        }
+        if (specificity > bestSpecificity) {
+            bestSpecificity = specificity;
+            bestQuality = qualityOf(parts.slice(1));
+        }
+    }
+    return bestSpecificity > 0 && bestQuality > 0;
+};
+/**
+ * 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 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 varyWith = (existing, fieldName) => {
+    const tokens = existing === undefined
+        ? []
+        : existing
+            .split(',')
+            .map(token => token.trim())
+            .filter(token => token !== '');
+    const lowered = tokens.map(token => token.toLowerCase());
+    if (lowered.includes('*')) {
+        return '*';
+    }
+    if (lowered.includes(fieldName.toLowerCase())) {
+        return tokens.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 = [];
+    for (const segment of path.split('/')) {
+        if (segment === '' || segment === '.') {
+            continue;
+        }
+        if (segment === '..') {
+            segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    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
+ * repeated separators collapsed, and dot segments resolved. A host renders the
+ * application for such a request rather than serving the raw, unfilled
+ * template, so `/`, `/index.html`, `/%2findex.html`, and `/foo/../index.html`
+ * all resolve to it. An undecodable or null-byte path resolves to nothing.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export const resolvesToIndexHtml = (requestUrl) => {
+    let pathname;
+    try {
+        pathname = new URL(requestUrl, 'http://localhost').pathname;
+    }
+    catch {
+        return false;
+    }
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        return false;
+    }
+    if (decoded.includes('\0')) {
+        return false;
+    }
+    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/index.d.ts

@@ -0,0 +1,5 @@
+export * from './entry.js';
+export * from './host.js';
+export * from './server.js';
+export * from './template.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/dist/experimental/server/index.js

@@ -0,0 +1,4 @@
+export * from './entry.js';
+export * from './host.js';
+export * from './server.js';
+export * from './template.js';

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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +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,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

@@ -0,0 +1 @@
+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

@@ -0,0 +1,43 @@
+import type { VNode } from '../../snabbdom/vnode.js';
+/** Extra attributes appended to the serialized root element, used by
+ *  `renderToString` to stamp the hydration marker without threading
+ *  server-only concerns through view code. Root attributes are applied after
+ *  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.
+ *
+ * @internal Shared with the template injector; not part of the `foldkit/experimental/server` surface.
+ */
+export declare const escapeText: (value: string) => string;
+/** Escapes a string for use inside a double-quoted HTML attribute value.
+ *
+ * @internal Shared with the template injector; not part of the `foldkit/experimental/server` surface.
+ */
+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 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.
+ */
+export declare const serializeHtml: (root: VNode | null, options?: SerializeOptions) => string;
+//# sourceMappingURL=serialize.d.ts.map

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

@@ -0,0 +1 @@
+{"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"}