@valancex/common 0.0.0-stage → 0.12.0

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @valancex/common
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What an application's `src/main.ts` imports (`defineApp`, `component`, `field`), and the runtime a built application runs. It describes the application; the [`vlx` command](../cli) builds, serves and checks what it describes.
+
+```console
+$ vlx init my-app --web      # a project that already depends on this package
+```
+
+```ts
+// src/main.ts
+import { component, defineApp, field } from "@valancex/common";
+import { Schema } from "effect";
+import layout from "./layout.mprx";
+import themeToggle from "./theme-toggle.js";
+
+export default defineApp({
+  layout: component(layout),
+  components: [themeToggle],
+  state: { theme: field(Schema.Literal("light", "dark"), "light") },
+  commands: (command) => ({
+    toggleTheme: command((state) => ({ ...state, theme: state.theme === "light" ? "dark" : "light" })),
+  }),
+});
+```
+
+| Export | Is |
+|---|---|
+| `defineApp({ layout?, components?, override?, state?, title?, commands? })` | The application: its shell, its components, its state, the title it wants for a state, and the commands that change it. It starts nothing. |
+| `component(template, { props?, events? })` | A component: a `.mprx` template and, optionally, the interface it states (Effect Schemas). Which components its template uses is read from the template. |
+| `field(schema, initial)` | One field of the state: its type and its default, together. |
+
+`Schema` is [Effect's](https://effect.website/docs/schema/introduction/); import it from `effect`. This package types against it and does not re-export it.
+
+| Entry | Is |
+|---|---|
+| `@valancex/common` | The three exports above. No Node, bundler or terminal import: `src/main.ts` is loaded in the browser as well as at build time. |
+| `@valancex/common/http` | The `Http` capability (`request({ path, response })`), its error type and the web's implementation. Imported by the commands that call a backend; it holds no `fetch` until the page supplies one. |
+| `@valancex/common/client`, `/server` | The browser and server halves of a built application: `start` takes over the server's HTML, `createRenderer` turns a path into a document. The files `vlx` generates import these; you do not. |
+| `@valancex/common/internal` | What the build tools share with the runtime (content model, tag table, the scope a layout reads). For `@valancex/cli`, not for applications. |
+
+A built or deployed application depends on this package and `effect`; `@valancex/cli` is only needed to develop it. This package depends on `@valancex/valance`, `@valancex/mesh-runtime` and `@valancex/port-web`.
+
+Documentation: [`@valancex/cli`](../cli/README.md) (the project layout, components, state and commands).
+
+Pre-1.0: the API may change between minor releases; every change is in the [release notes](../../docs/releases/).

package/dist/announce.d.ts

@@ -0,0 +1,25 @@
+export interface Node_ {
+    textContent: string | null;
+    setAttribute(name: string, value: string): void;
+    hasAttribute?(name: string): boolean;
+    readonly style?: {
+        setProperty(name: string, value: string): void;
+    };
+    focus?(options?: {
+        preventScroll?: boolean;
+    }): void;
+}
+export interface AnnounceDocument {
+    readonly title: string;
+    readonly body: {
+        append(node: never): void;
+    };
+    getElementById(id: string): Node_ | null;
+    querySelector(selector: string): Node_ | null;
+    createElement(tag: string): Node_;
+}
+export declare const ANNOUNCER_ID = "valance-announcer";
+/** Says the document's title, and focuses `#content` (or `<main>`) when it has a `tabindex`. */
+export declare const announcePage: (document: AnnounceDocument, options?: {
+    readonly focus: boolean;
+}) => void;

package/dist/announce.js

@@ -0,0 +1,39 @@
+export const ANNOUNCER_ID = "valance-announcer";
+/**
+ * Visually hidden, still read out. Set through the style object, not a `style` attribute: a page served with the strict policy `vlx build` writes (`style-src 'self'`) refuses an inline style
+ * attribute, and setting properties on `element.style` is the one way it allows.
+ */
+const HIDDEN = [
+    ["position", "absolute"],
+    ["width", "1px"],
+    ["height", "1px"],
+    ["margin", "-1px"],
+    ["padding", "0"],
+    ["overflow", "hidden"],
+    ["clip", "rect(0 0 0 0)"],
+    ["clip-path", "inset(50%)"],
+    ["white-space", "nowrap"],
+    ["border", "0"],
+];
+/** Says the document's title, and focuses `#content` (or `<main>`) when it has a `tabindex`. */
+export const announcePage = (document, options = { focus: true }) => {
+    let region = document.getElementById(ANNOUNCER_ID);
+    if (region === null) {
+        region = document.createElement("div");
+        region.setAttribute("id", ANNOUNCER_ID);
+        region.setAttribute("role", "status");
+        region.setAttribute("aria-live", "polite");
+        HIDDEN.forEach(([name, value]) => region.style?.setProperty(name, value));
+        document.body.append(region);
+    }
+    // A region that says the same words again is not announced again: clear it first.
+    region.textContent = "";
+    region.textContent = document.title;
+    if (options.focus) {
+        const main = document.getElementById("content") ?? document.querySelector("main");
+        // Only an element the author made focusable (a `tabindex`): making one focusable here would put an outline on the whole page.
+        if (main !== null && main.hasAttribute?.("tabindex") === true) {
+            main.focus?.({ preventScroll: true });
+        }
+    }
+};

package/dist/app.d.ts

@@ -0,0 +1,35 @@
+import * as Valance from "@valancex/valance";
+import type { Plugin } from "@valancex/valance/web/plugin";
+import { Schema } from "effect";
+import type { DefinedApp, PageState } from "./index.js";
+import type { Content } from "./model.js";
+export type AppState = PageState & Record<string, unknown>;
+/** What the browser needs to know about the built page to keep the document's head in step. */
+export interface Built {
+    /** The address of the page script. */
+    readonly script: string;
+    /** Stylesheet addresses, in order. Empty in development, where the script brings its styles. */
+    readonly styles: ReadonlyArray<string>;
+}
+/** A mistake in `src/main.ts`, reported with what to change. */
+export declare class AppDefinitionError extends Error {
+    constructor(message: string);
+}
+/** Checks the author's definition against the names the framework owns. */
+export declare const checkDefinition: (author: DefinedApp | undefined) => void;
+/** The names `src/main.ts` adds: state fields (readable in the layout) and commands (runnable from it). */
+export declare const ownNames: (author: DefinedApp | undefined) => {
+    readonly state: ReadonlyArray<string>;
+    readonly commands: ReadonlyArray<string>;
+};
+/** The scope schema a layout is compiled against: the framework's names and the author's state fields. */
+export declare const scopeSchema: (author: DefinedApp | undefined) => Schema.Schema<any, any, never>;
+export declare const stateSchema: (author: DefinedApp | undefined) => Schema.Schema<any, any, never>;
+/** The command table: the framework's `go`, then the author's. */
+export declare const commandTable: (author: DefinedApp | undefined) => (state: Parameters<typeof Valance.command>[0]) => Valance.CommandTable<any, Valance.Ambient>;
+export declare const initialState: (author: DefinedApp | undefined) => AppState;
+export declare const application: (content: Content, program: Valance.Program, author?: DefinedApp) => Valance.ApplicationDefinition<AppState, any, Valance.Ambient, "layout">;
+/** The state a request for `pathname` starts from. */
+export declare const stateFor: (content: Content, pathname: string, author?: DefinedApp) => AppState;
+/** The plugin that makes the application a website: its tags, its URL policy, and its document head. */
+export declare const plugin: (content: Content, built: Built, author?: DefinedApp) => Plugin<AppState>;

package/dist/app.js

@@ -0,0 +1,124 @@
+// The application the framework assembles from the three things an author supplies: the content (built from `content/`), the program (built from the templates), and optionally
+// `defineApp`'s state and commands. This is one Valance application (`Valance.define`): the page is its state, going to a page is its `go` command, and the layout is its one view.
+// The server renders it and the browser runs it, from the same function.
+import * as Valance from "@valancex/valance";
+import { Schema } from "effect";
+import { documentTitle, frame, FrameScope, pageAt, RESERVED } from "./scope.js";
+import { primitives } from "./primitives.js";
+import { normalize, routes } from "./routes.js";
+import { badDefaults, stateOf } from "./state.js";
+const PageSchema = Schema.Struct({ page: Schema.String, viewport: Schema.Literal("compact", "medium", "expanded") });
+/** A mistake in `src/main.ts`, reported with what to change. */
+export class AppDefinitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AppDefinitionError";
+    }
+}
+const authorFields = (author) => Object.keys(stateOf(author)?.schema.fields ?? {});
+/** Checks the author's definition against the names the framework owns. */
+export const checkDefinition = (author) => {
+    for (const name of authorFields(author)) {
+        if (RESERVED.includes(name)) {
+            throw new AppDefinitionError(`src/main.ts: the state field "${name}" is a name the layout already reads from the framework (${RESERVED.join(", ")}); choose another`);
+        }
+        if (name === "page") {
+            throw new AppDefinitionError('src/main.ts: the state field "page" is the framework\'s (which page is shown); choose another');
+        }
+    }
+    for (const name of badDefaults(author)) {
+        throw new AppDefinitionError(`src/main.ts: the default of the state field "${name}" is not a value of its type`);
+    }
+    // Building the table reads no state (a command reads it when it runs), so it can be built here, with nothing, to see its names.
+    const own = author?.commands?.(Valance.command({})) ?? {};
+    for (const [name, what] of [
+        ["go", "shows a page"],
+        ["resize", "tells the layout how much room the page has"],
+    ]) {
+        if (name in own) {
+            throw new AppDefinitionError(`src/main.ts: "${name}" is the framework's command (it ${what}); choose another name`);
+        }
+    }
+};
+/** The names `src/main.ts` adds: state fields (readable in the layout) and commands (runnable from it). */
+export const ownNames = (author) => ({
+    state: authorFields(author),
+    commands: Object.keys(author?.commands?.(Valance.command({})) ?? {}),
+});
+/** The scope schema a layout is compiled against: the framework's names and the author's state fields. */
+export const scopeSchema = (author) => {
+    const state = stateOf(author);
+    return state === undefined ? FrameScope : Schema.extend(FrameScope, state.schema);
+};
+export const stateSchema = (author) => {
+    const state = stateOf(author);
+    return state === undefined ? PageSchema : Schema.extend(PageSchema, state.schema);
+};
+/** The command table: the framework's `go`, then the author's. */
+export const commandTable = (author) => (state) => {
+    const command = Valance.command(state);
+    const own = author?.commands?.(command) ?? {};
+    for (const name of ["go", "resize"]) {
+        if (name in own) {
+            throw new AppDefinitionError(`src/main.ts: "${name}" is the framework's command; choose another name`);
+        }
+    }
+    return {
+        go: command(Schema.Struct({ id: Schema.String }), ({ id }, current) => ({ ...current, page: id })),
+        // The window changed size: the browser tells the application, which tells the layout (`viewport`).
+        resize: command(Schema.Struct({ viewport: Schema.Literal("compact", "medium", "expanded") }), ({ viewport }, current) => ({ ...current, viewport })),
+        ...own,
+    };
+};
+export const initialState = (author) => ({ page: "/", viewport: "expanded", ...stateOf(author)?.initial });
+export const application = (content, program, author) => {
+    checkDefinition(author);
+    return Valance.define({
+        name: content.site.name,
+        state: { schema: stateSchema(author), initial: initialState(author) },
+        views: {
+            layout: {
+                program,
+                scope: (state) => {
+                    const { page, ...own } = state;
+                    return { ...frame(content, page, state.viewport), ...own };
+                },
+            },
+        },
+        view: () => "layout",
+        commands: commandTable(author),
+    });
+};
+/** The state a request for `pathname` starts from. */
+export const stateFor = (content, pathname, author) => ({ ...initialState(author), page: normalize(pathname, content.site.base) });
+/**
+ * The title for a state: the page's and the site's name, or what the author's `title` function says. A function that throws falls back to the default (a title is never worth a failed render),
+ * and the failure is reported by its name only.
+ */
+const titleFor = (content, page, state, author) => {
+    let parts = {};
+    try {
+        const made = author?.title?.(state, { path: state.page, title: page?.title ?? "" });
+        parts = made === undefined ? {} : typeof made === "string" ? { page: made } : made;
+    }
+    catch (error) {
+        console.error(`the title function in src/main.ts failed (${error instanceof Error ? error.name : "error"}); the default title is used`);
+    }
+    return documentTitle(content, page, parts);
+};
+/** The plugin that makes the application a website: its tags, its URL policy, and its document head. */
+export const plugin = (content, built, author) => ({
+    name: "valance-app",
+    primitives,
+    routes: routes(content),
+    head: (state) => {
+        const page = pageAt(content, state.page);
+        const shown = page ?? { description: "" };
+        const canonical = content.site.url === "" || page === undefined ? [] : [{ rel: "canonical", href: `${content.site.url}${content.site.base}${page.path.replace(/^\//, "")}` }];
+        return {
+            title: titleFor(content, page, state, author),
+            meta: shown.description === "" ? [] : [{ name: "description", content: shown.description }],
+            links: [...built.styles.map((href) => ({ rel: "stylesheet", href })), ...canonical],
+        };
+    },
+});

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+import type * as Valance from "@valancex/valance";
+import type { DefinedApp } from "./index.js";
+import type { Content } from "./model.js";
+export interface ClientParts {
+    readonly content: Content;
+    readonly program: Valance.Program;
+    readonly author?: DefinedApp | undefined;
+}
+export declare const start: ({ content, program, author }: ClientParts) => Promise<void>;

package/dist/client.js

@@ -0,0 +1,40 @@
+// The browser half, for the generated entry (`.valance/client.ts`): start the MESH runtime and run the application, taking over the HTML the server wrote. An author never imports this.
+import { init } from "@valancex/mesh-runtime";
+import wasmUrl from "@valancex/mesh-runtime/mesh-runtime.wasm?url";
+import * as Web from "@valancex/valance/web";
+import { Effect } from "effect";
+import { webPlatform } from "./http.js";
+import { watchViewport } from "./viewport.js";
+import { application, plugin } from "./app.js";
+export const start = async ({ content, program, author }) => {
+    const container = document.getElementById("app");
+    try {
+        const boot = JSON.parse(document.getElementById("valance-boot").textContent);
+        await init(wasmUrl);
+        const host = await Web.run(application(content, program, author), {
+            container,
+            present: "hydrate",
+            state: boot.state,
+            plugins: [plugin(content, boot.built, author)],
+            // What the application's commands may ask the page for: the backend (`Http`), at `api.base` of valance.web.json.
+            platform: webPlatform({ base: content.site.api, interceptors: author?.http?.interceptors ?? [] }),
+            shutdown: { grace: "250 millis" },
+        });
+        // The server rendered for a wide window; tell the application how wide this one is (and keep telling it).
+        const unwatch = watchViewport(window, (viewport) => {
+            container.dataset["viewport"] = viewport; // for a stylesheet or a test; the layout reads the state's own `viewport`
+            void Effect.runPromise(host.handle.invoke("app/resize", [{ value: viewport }])).catch(() => undefined);
+        });
+        container.dataset["valance"] = "running"; // readiness marker for whoever drives the page
+        addEventListener("pagehide", (event) => {
+            if (!event.persisted) {
+                unwatch();
+                void host.stop();
+            }
+        });
+    }
+    catch (error) {
+        container.dataset["valance"] = "failed";
+        console.error("the application did not start", error); // the server's HTML stays as drawn
+    }
+};

package/dist/http.d.ts

@@ -0,0 +1,65 @@
+import * as Nexus from "@valancex/nexus";
+import { Effect, Schema } from "effect";
+import type { HttpError, Interceptor, Method, TransportRequest } from "./transport.js";
+export type { HttpError, Interceptor, Method, Transport, TransportRequest, TransportResponse } from "./transport.js";
+/** One request: where, what is sent, and what the answer must be. */
+export interface RequestSpec<A> {
+    readonly method?: Method;
+    /** On the API's base: starts with `/` (not `//`), no scheme, no backslash. Anything else is `Unsafe`: a path built from data cannot send the request somewhere else. */
+    readonly path: string;
+    /** Appended to the address, encoded. `undefined` values are left out. */
+    readonly query?: Readonly<Record<string, string | number | boolean | undefined>>;
+    /** Sent as JSON. */
+    readonly body?: unknown;
+    /** What the answer must be. The decoded value is what the command receives; an answer that is not this is `Decode`, and nothing else gets through. */
+    readonly response: Schema.Schema<A, any, never>;
+    /** Milliseconds before the request is given up (`Timeout`), for each attempt. Default 15 000. */
+    readonly timeoutMs?: number;
+    /** Interceptors for this request alone: the innermost, the closest to the wire (see `Interceptor`). */
+    readonly interceptors?: ReadonlyArray<Interceptor>;
+}
+export interface HttpClient {
+    readonly request: <A>(spec: RequestSpec<A>) => Effect.Effect<A, HttpError>;
+}
+/** The capability: ask for it in a command (`Http.request`), and the platform says whether it has one. */
+export declare const Http: Nexus.Capability.Capability<HttpClient>;
+/** Makes a request through the platform's client. Requires the `Http` capability. */
+export declare const request: <A>(spec: RequestSpec<A>) => Effect.Effect<A, HttpError | Nexus.Capability.CapabilityUnavailableError, Nexus.Capability.EnvironmentShape>;
+export interface WebHttpOptions {
+    /** `api.base` in `valance.web.json`: `""` (the site's own origin), a path (`/api`) or an absolute https address. */
+    readonly base: string;
+    /** Default `globalThis.fetch`. Tests pass their own. */
+    readonly fetch?: typeof fetch;
+    /** Send cookies to an `api.base` on another origin. Default off: a cross-origin backend gets no ambient credentials unless the application says so. */
+    readonly credentials?: "same-origin" | "include";
+    /** The largest answer read, in characters. Default 5 000 000. */
+    readonly maxResponse?: number;
+    /** The application's interceptors, outermost first: the ones that hold for every request (`defineApp({ http: { interceptors } })`). Scoped ones are added by `withInterceptors` and `RequestSpec.interceptors`. */
+    readonly interceptors?: ReadonlyArray<Interceptor>;
+}
+/** The address for `path` under `base`, or why it cannot be one. */
+export declare const addressOf: (base: string, path: string, query: RequestSpec<unknown>["query"]) => {
+    readonly url: string;
+} | {
+    readonly unsafe: string;
+};
+/** Several interceptors as one, the first listed outermost: `chain(a, b)(t)` is `a(b(t))`. */
+export declare const chain: (...interceptors: ReadonlyArray<Interceptor>) => Interceptor;
+/** An interceptor that applies only to the requests `applies` accepts; every other request goes straight to the next. This is how a scope narrows: by address, by method, by anything the request says. */
+export declare const only: (applies: (request: TransportRequest) => boolean, interceptor: Interceptor) => Interceptor;
+/**
+ * Runs `effect` with `interceptors` added for the requests it makes: a scope narrower than the application's. A scope inside another is inside it (the outer ones see the request first and the
+ * answer last). It ends with the effect; a request made outside it is not touched.
+ *
+ *   work: () => withInterceptors(Http.request({ path: "/admin/users", response: Users }), bearer(...adminToken))
+ */
+export declare const withInterceptors: <A, E, R>(effect: Effect.Effect<A, E, R>, ...interceptors: ReadonlyArray<Interceptor>) => Effect.Effect<A, E, R>;
+/** Adds `Authorization: Bearer <token>` to requests for the API's origin and to no other: a credential never follows a request somewhere else. `base` is `api.base`. */
+export declare const bearer: (base: string, token: () => string | undefined | Promise<string | undefined>) => Interceptor;
+/** On a 401, runs `refresh` once however many requests failed together, then sends each of them once more. A second 401 is the answer. */
+export declare const refreshOn401: (refresh: () => Promise<void>) => Interceptor;
+/** Sends a GET again, up to `times` more, when it did not connect or the server failed (5xx). Never another method: a repeated POST is a second order. */
+export declare const retryGet: (times: number) => Interceptor;
+export declare const webHttp: (options: WebHttpOptions) => HttpClient;
+/** The platform for a web page: the `Http` capability, made from `api.base`. Merged with the application's own by `Web.run`. */
+export declare const webPlatform: (options: WebHttpOptions) => Nexus.Application.Platform;

package/dist/http.js

@@ -0,0 +1,188 @@
+// Talking to the application's backend. NEXUS and VALANCE hold no HTTP (their rule): what an application needs from where it runs is a *capability*, a typed contract the application states and the
+// platform supplies. This is that contract for HTTP, and the web's implementation of it. A desktop or mobile platform supplies the same contract with its own client (the OS's networking, a
+// keychain for the token), and no command changes.
+//
+//   const load = command.waiting(Schema.Struct({}), {
+//     begin: (_, s) => ({ ...s, inbox: { status: "loading" } }),
+//     work: () => Http.request({ path: "/inbox", response: Inbox }),     // Effect<Inbox, HttpError, the Http capability>
+//     wanted: (_, s) => s.inbox.status === "loading",
+//     settle: (outcome, _, s) => ({ ...s, inbox: outcome.ok ? { status: "ready", ...outcome.value } : { status: "failed", why: describe(outcome.error) } }),
+//   });
+//
+// The defaults are the safe ones: a request goes to the application's own origin (or the one `api.base` names), carries no credentials to another origin, sends and accepts JSON, is
+// bounded in time and size, and its response is *decoded by a Schema* before it can reach state. A failure says what kind it was and never what it carried.
+import * as Nexus from "@valancex/nexus";
+import { Effect, FiberRef, Schema } from "effect";
+/** The capability: ask for it in a command (`Http.request`), and the platform says whether it has one. */
+export const Http = Nexus.Capability.define("valance/http");
+/** Makes a request through the platform's client. Requires the `Http` capability. */
+export const request = (spec) => Effect.flatMap(Nexus.Capability.require(Http), (client) => client.request(spec));
+const UNSAFE_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+const DEFAULT_TIMEOUT = 15_000;
+const DEFAULT_MAX = 5_000_000;
+/** The address for `path` under `base`, or why it cannot be one. */
+export const addressOf = (base, path, query) => {
+    // oxlint-disable-next-line no-control-regex -- refusing control characters in a path is the point
+    if (!path.startsWith("/") || path.startsWith("//") || path.includes("\\") || /[\u0000-\u001f]/.test(path) || /^\/[^/?#]*:\/\//.test(path)) {
+        return { unsafe: 'a path starts with a single "/" and holds no scheme, backslash or control character' };
+    }
+    if (path.split(/[/?#]/).includes("..")) {
+        return { unsafe: 'a path does not climb out of the API ("..")' };
+    }
+    const search = new URLSearchParams();
+    for (const [name, value] of Object.entries(query ?? {})) {
+        if (value !== undefined) {
+            search.append(name, String(value));
+        }
+    }
+    const tail = search.size === 0 ? "" : `${path.includes("?") ? "&" : "?"}${search.toString()}`;
+    return { url: `${base.replace(/\/+$/, "")}${path}${tail}` };
+};
+// ---- interceptors ------------------------------------------------------------------------------------------------------------------------------------------
+//
+// One shape for all of them. A `Transport` takes the request the client built and checked, and gives the answer before the client decodes it. An `Interceptor` takes the next `Transport` and gives
+// a `Transport`: so every interceptor has the same input and the same output, they chain by plain composition, and the only thing that differs between two is what they do. The client's own
+// checks come first (the path, the method, the body) and last (the answer's status, type and Schema), so no interceptor can skip them. Failures are `HttpError`s, which carry no address, header or body.
+/** Several interceptors as one, the first listed outermost: `chain(a, b)(t)` is `a(b(t))`. */
+export const chain = (...interceptors) => (next) => interceptors.reduceRight((inner, intercept) => intercept(inner), next);
+/** An interceptor that applies only to the requests `applies` accepts; every other request goes straight to the next. This is how a scope narrows: by address, by method, by anything the request says. */
+export const only = (applies, interceptor) => (next) => {
+    const inner = interceptor(next);
+    return (request) => (applies(request) ? inner(request) : next(request));
+};
+/** The interceptors in force for the requests made inside `withInterceptors`. The client reads it for each request, so a scope reaches every request its effect makes, however deep. */
+const scope = FiberRef.unsafeMake([]);
+/**
+ * Runs `effect` with `interceptors` added for the requests it makes: a scope narrower than the application's. A scope inside another is inside it (the outer ones see the request first and the
+ * answer last). It ends with the effect; a request made outside it is not touched.
+ *
+ *   work: () => withInterceptors(Http.request({ path: "/admin/users", response: Users }), bearer(...adminToken))
+ */
+export const withInterceptors = (effect, ...interceptors) => Effect.locallyWith(effect, scope, (current) => [...current, ...interceptors]);
+/** Whether the request goes to the origin the application's API is on (the base's, or the page's for a relative base). */
+const sameApi = (base, url) => {
+    const origin = (value) => {
+        try {
+            return new URL(value, "http://page.invalid").origin;
+        }
+        catch {
+            return "";
+        }
+    };
+    return origin(url) !== "" && origin(url) === origin(base === "" ? "/" : base);
+};
+/** Adds `Authorization: Bearer <token>` to requests for the API's origin and to no other: a credential never follows a request somewhere else. `base` is `api.base`. */
+export const bearer = (base, token) => (next) => (request) => !sameApi(base, request.url)
+    ? next(request)
+    : Effect.flatMap(Effect.promise(async () => token()), (value) => next(value === undefined ? request : { ...request, headers: { ...request.headers, authorization: `Bearer ${value}` } }));
+/** On a 401, runs `refresh` once however many requests failed together, then sends each of them once more. A second 401 is the answer. */
+export const refreshOn401 = (refresh) => {
+    let refreshing;
+    return (next) => (request) => Effect.flatMap(next(request), (first) => first.status !== 401
+        ? Effect.succeed(first)
+        : Effect.flatMap(Effect.tryPromise({
+            try: async () => {
+                refreshing ??= refresh().finally(() => void (refreshing = undefined));
+                return refreshing;
+            },
+            catch: () => ({ _tag: "Offline" }),
+        }), () => next(request)));
+};
+/** Sends a GET again, up to `times` more, when it did not connect or the server failed (5xx). Never another method: a repeated POST is a second order. */
+export const retryGet = (times) => (next) => (request) => {
+    const attempt = (n) => request.method !== "GET"
+        ? next(request)
+        : next(request).pipe(Effect.flatMap((response) => (response.status >= 500 && n < times ? attempt(n + 1) : Effect.succeed(response))), Effect.catchTag("Offline", (error) => (n < times ? attempt(n + 1) : Effect.fail(error))));
+    return attempt(0);
+};
+// ---- the web's implementation ------------------------------------------------------------------------------------------------------------------------------------
+/** The last transport: `fetch`, with the timeout, the size bound and the safe defaults. It returns any status; the client judges it after the interceptors have seen it. */
+const fetchTransport = (options, crossOrigin) => {
+    const send = options.fetch ?? ((...args) => globalThis.fetch(...args));
+    return (request) => Effect.tryPromise({
+        try: async (signal) => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort("timeout"), request.timeoutMs);
+            const stop = () => controller.abort("aborted");
+            signal.addEventListener("abort", stop, { once: true });
+            try {
+                const response = await send(request.url, {
+                    method: request.method,
+                    headers: { ...request.headers },
+                    ...(request.body === undefined ? {} : { body: request.body }),
+                    credentials: crossOrigin ? (options.credentials ?? "omit") : "same-origin",
+                    redirect: "follow",
+                    referrerPolicy: "strict-origin-when-cross-origin",
+                    cache: "no-store",
+                    signal: controller.signal,
+                });
+                const headers = {};
+                response.headers.forEach((value, name) => void (headers[name.toLowerCase()] = value));
+                const text = response.status === 204 ? "" : await response.text();
+                if (text.length > (options.maxResponse ?? DEFAULT_MAX)) {
+                    throw { _tag: "TooLarge" };
+                }
+                return { status: response.status, headers, text };
+            }
+            catch (error) {
+                // A fetch that was aborted rejects with the abort's reason, whatever that was: what we passed says who stopped it.
+                if (controller.signal.aborted) {
+                    throw { _tag: controller.signal.reason === "timeout" ? "Timeout" : "Aborted" };
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
+                signal.removeEventListener("abort", stop);
+                if (controller.signal.aborted === false) {
+                    controller.abort("done");
+                }
+            }
+        },
+        catch: (error) => (typeof error === "object" && error !== null && "_tag" in error ? error : { _tag: "Offline" }),
+    });
+};
+export const webHttp = (options) => {
+    const crossOrigin = /^https?:\/\//i.test(options.base);
+    const wire = fetchTransport(options, crossOrigin);
+    const global = chain(...(options.interceptors ?? []));
+    return {
+        request: (spec) => Effect.gen(function* () {
+            const method = spec.method ?? "GET";
+            const address = addressOf(options.base, spec.path, spec.query);
+            if ("unsafe" in address) {
+                return yield* Effect.fail({ _tag: "Unsafe", reason: address.unsafe });
+            }
+            const body = spec.body === undefined ? undefined : JSON.stringify(spec.body);
+            if (method === "GET" && body !== undefined) {
+                return yield* Effect.fail({ _tag: "Unsafe", reason: "a GET request has no body" });
+            }
+            const request = {
+                method,
+                url: address.url,
+                headers: {
+                    accept: "application/json",
+                    ...(body === undefined ? {} : { "content-type": "application/json" }),
+                    // A header a plain cross-site form cannot send: with the backend checking it (or SameSite cookies), a forged request from another page has nothing to ride on.
+                    ...(UNSAFE_METHODS.has(method) ? { "x-requested-with": "valance" } : {}),
+                },
+                ...(body === undefined ? {} : { body }),
+                timeoutMs: spec.timeoutMs ?? DEFAULT_TIMEOUT,
+            };
+            // Whatever the interceptors did to the request, it goes where the API is: the address is checked again as the wire gets it.
+            const guarded = (final) => sameApi(options.base, final.url) ? wire(final) : Effect.fail({ _tag: "Unsafe", reason: "an interceptor sent the request outside the API's origin" });
+            const scoped = yield* FiberRef.get(scope);
+            const response = yield* chain(global, ...scoped, ...(spec.interceptors ?? []))(guarded)(request);
+            if (response.status < 200 || response.status >= 300) {
+                return yield* Effect.fail({ _tag: "Status", status: response.status });
+            }
+            if (response.status !== 204 && !/^application\/(?:[\w.+-]+\+)?json\b/i.test(response.headers["content-type"] ?? "")) {
+                return yield* Effect.fail({ _tag: "Decode" }); // an HTML error page or a proxy's reply is not the API's answer
+            }
+            const json = yield* Effect.try({ try: () => (response.text === "" ? undefined : JSON.parse(response.text)), catch: () => ({ _tag: "Decode" }) });
+            return yield* Schema.decodeUnknown(spec.response)(json).pipe(Effect.mapError(() => ({ _tag: "Decode" })));
+        }),
+    };
+};
+/** The platform for a web page: the `Http` capability, made from `api.base`. Merged with the application's own by `Web.run`. */
+export const webPlatform = (options) => Nexus.Capability.EnvironmentLive(new Map([[Http.id, { _tag: "Available", implementation: webHttp(options) }]]));