@valancex/common 0.11.0 → 0.12.0

package/README.md

@@ -25,7 +25,7 @@ export default defineApp({
 
 | Export | Is |
 |---|---|
-| `defineApp({ layout?, components?, override?, state?, commands? })` | The application: its shell, its components, its state and the commands that change it. It starts nothing. |
+| `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. |
 
@@ -34,6 +34,7 @@ export default defineApp({
 | 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. |
 

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

@@ -32,4 +32,4 @@ export declare const application: (content: Content, program: Valance.Program, a
 /** 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) => Plugin<AppState>;
+export declare const plugin: (content: Content, built: Built, author?: DefinedApp) => Plugin<AppState>;

package/dist/app.js

@@ -7,7 +7,7 @@ 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 });
+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) {
@@ -30,8 +30,14 @@ export const checkDefinition = (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.
-    if ("go" in (author?.commands?.(Valance.command({})) ?? {})) {
-        throw new AppDefinitionError('src/main.ts: "go" is the framework\'s command (it shows a page); choose another name');
+    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). */
@@ -52,12 +58,19 @@ export const stateSchema = (author) => {
 export const commandTable = (author) => (state) => {
     const command = Valance.command(state);
     const own = author?.commands?.(command) ?? {};
-    if ("go" in own) {
-        throw new AppDefinitionError('src/main.ts: "go" is the framework\'s command (it shows a page); choose another name');
+    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 })), ...own };
+    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: "/", ...stateOf(author)?.initial });
+export const initialState = (author) => ({ page: "/", viewport: "expanded", ...stateOf(author)?.initial });
 export const application = (content, program, author) => {
     checkDefinition(author);
     return Valance.define({
@@ -68,7 +81,7 @@ export const application = (content, program, author) => {
                 program,
                 scope: (state) => {
                     const { page, ...own } = state;
-                    return { ...frame(content, page), ...own };
+                    return { ...frame(content, page, state.viewport), ...own };
                 },
             },
         },
@@ -78,8 +91,23 @@ export const application = (content, program, 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) => ({
+export const plugin = (content, built, author) => ({
     name: "valance-app",
     primitives,
     routes: routes(content),
@@ -88,7 +116,7 @@ export const plugin = (content, built) => ({
         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: documentTitle(content, page),
+            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.js

@@ -2,6 +2,9 @@
 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");
@@ -12,12 +15,20 @@ export const start = async ({ content, program, author }) => {
             container,
             present: "hydrate",
             state: boot.state,
-            plugins: [plugin(content, boot.built)],
+            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();
             }
         });

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) }]]));

package/dist/index.d.ts

@@ -1,10 +1,15 @@
 /// <reference path="../types/mprx.d.ts" preserve="true" />
 import type * as Valance from "@valancex/valance";
 import { Schema } from "effect";
+import type { Interceptor } from "./transport.js";
 /** The part of the application's state the framework owns: which page is shown. A command's `state` always has it. */
 export interface PageState {
     readonly page: string;
+    /** How much room the page has: `compact` (under 600 px wide: a phone), `medium` (600 to 839) or `expanded` (840 and up). The framework keeps it current as the window changes; a layout reads it as `viewport`. */
+    readonly viewport: Viewport;
 }
+/** Window size classes, the ones Material Design and iOS size classes agree on closely enough to design for. */
+export type Viewport = "compact" | "medium" | "expanded";
 export declare const FIELD: unique symbol;
 /** A state field: its type and its default, declared together. */
 export interface Field<A = unknown> {
@@ -65,6 +70,17 @@ export interface Contract<P extends string, E extends string> {
  * written again there. Where the toolchain has generated the template's type, a contract that disagrees with the template's keys is a compile-time error.
  */
 export declare function component<P extends string = string, E extends string = string>(template: Template<P, E>, contract?: Contract<NoInfer<P>, NoInfer<E>>): Component;
+/**
+ * What the document's title is made of. `page` is the page's own part (default: its title, from the Markdown front matter), `app` the application's name (default: the site's name), `status` what is
+ * going on right now and is not part of any page (an unread count, "Saving…"): it is written first, in parentheses. The project's format in \`valance.json\` (`"title": "{page} · {site}"`) puts them
+ * together. A target that is not a web page uses the same three parts for its own surfaces (a window title, a navigation bar, a badge). All text: control and direction-override characters are removed
+ * and the length is limited, so a title built from user data cannot reorder or hide what surrounds it.
+ */
+export interface TitleParts {
+    readonly page?: string;
+    readonly app?: string;
+    readonly status?: string;
+}
 export interface AppDefinition<S extends StateInput = {}> {
     /** The page's shell. Omit it to use the built-in layout. Its template must be named `layout.mprx`, and it has no props or events: its inputs are the state and the commands. */
     readonly layout?: Component;
@@ -77,6 +93,22 @@ export interface AppDefinition<S extends StateInput = {}> {
      * hydration and shared schemas.
      */
     readonly state?: S;
+    /**
+     * The document's title for a state: `(state, page) => { status: unread > 0 ? String(unread) : undefined }`. A string is the page part. Absent: the page's title and the site's name. It runs for
+     * every committed state, on the server for the state it renders and in the browser after each one; it should be cheap and must not throw (a throw is logged and the title stays).
+     */
+    readonly title?: (state: PageState & StateOf<S>, page: {
+        readonly path: string;
+        readonly title: string;
+    }) => TitleParts | string;
+    /**
+     * What the application sends to its backend, for every request: `http: { interceptors: [bearer(base, token), refreshOn401(refresh), retryGet(2)] }`, outermost first. Interceptors
+     * (`@valancex/common/http`) all have one shape, `(next) => next`, so they chain; a narrower scope is `withInterceptors(effect, ...)` around a command's work, or `interceptors` on one request.
+     * Used by the page; the server makes no requests.
+     */
+    readonly http?: {
+        readonly interceptors?: ReadonlyArray<Interceptor>;
+    };
     /** The commands a layout can run. `command` makes one: `command((state) => nextState)` or `command(InputSchema, (input, state) => nextState)`. */
     readonly commands?: (command: Valance.CommandMaker<PageState & StateOf<S>>) => Valance.CommandTable<any, Valance.Ambient>;
 }

package/dist/internal.d.ts

@@ -4,3 +4,4 @@ export * from "./primitives.js";
 export * from "./routes.js";
 export * from "./scope.js";
 export * from "./state.js";
+export * from "./vocabulary.js";

package/dist/internal.js

@@ -6,3 +6,4 @@ export * from "./primitives.js";
 export * from "./routes.js";
 export * from "./scope.js";
 export * from "./state.js";
+export * from "./vocabulary.js";

package/dist/model.d.ts

@@ -54,7 +54,15 @@ export interface SiteInfo {
     readonly base: string;
     /** Where the site is published (no trailing slash), or empty. */
     readonly url: string;
+    /** How a document's title is written from a page's title and the site's name: `{page}` and `{site}`. */
+    readonly title: string;
+    /** The address the application's backend requests go to (a path on the site's origin, or an absolute https address), or empty when it has none. */
+    readonly api: string;
+    /** Tell assistive technology about a page change made in place (the title, and focus at the content). */
+    readonly announce: boolean;
 }
+/** The title format when the project does not say: the page, then the site. */
+export declare const DEFAULT_TITLE = "{page} \u00B7 {site}";
 export interface Content {
     readonly site: SiteInfo;
     /** In navigation order. */

package/dist/model.js

@@ -1,3 +1,4 @@
 // The content model: what the build produces from `content/` and what the application and its layout consume. Plain JSON-able data. A MESH scope is flat, so a block is one record whose
 // unused fields are empty (`kind` says which are meaningful); the empty values are explicit so a template never reads something missing.
-export {};
+/** The title format when the project does not say: the page, then the site. */
+export const DEFAULT_TITLE = "{page} · {site}";

package/dist/routes.js

@@ -1,3 +1,4 @@
+import { announcePage } from "./announce.js";
 import { pageAt } from "./scope.js";
 /** An address as the application sees it: under the base removed, no trailing slash, `/` for the first page. An address outside the base is kept whole (it is not a page). */
 export const normalize = (pathname, base) => {
@@ -15,8 +16,18 @@ export const routes = (content) => ({
     // Static first: every page is rendered once at build time.
     delivery: () => "static",
     onNavigated: ({ kind, url }) => {
+        if (typeof window === "undefined") {
+            return;
+        }
+        // A person who cannot see the page change is told it did: the new title, and focus at the content. Not for a fragment (the browser moves there itself), and not when the project turned it off.
+        const announce = () => {
+            if (content.site.announce && url.hash === "") {
+                setTimeout(() => announcePage(document), 0); // after the application has presented the new page
+            }
+        };
         // Land at the top of a new page, or at its heading when the address names one; Back and Forward are the browser's to restore.
-        if (kind !== "link" || typeof window === "undefined") {
+        if (kind !== "link") {
+            announce();
             return;
         }
         // The application's state has no fragment, so the address bar lost it: put it back.
@@ -30,5 +41,6 @@ export const routes = (content) => ({
         else {
             target.scrollIntoView();
         }
+        announce();
     },
 });

package/dist/scope.d.ts

@@ -1,4 +1,5 @@
 import { Schema } from "effect";
+import type { TitleParts, Viewport } from "./index.js";
 import type { Content, Page } from "./model.js";
 export declare const FrameScope: Schema.Struct<{
     /** The application's name (`valance.json`). */
@@ -29,6 +30,8 @@ export declare const FrameScope: Schema.Struct<{
         label: typeof Schema.String;
         level: typeof Schema.Number;
     }>>;
+    /** How much room the page has: `"compact"`, `"medium"` or `"expanded"` (see `Viewport`). `{#if viewport == "compact"}` chooses a layout for a phone. The server renders `expanded`; the browser corrects it after it starts. */
+    viewport: Schema.Literal<["compact", "medium", "expanded"]>;
     /** The page's body. Draw it with `<blocks items={blocks} />`, or draw each block yourself. */
     blocks: Schema.Array$<Schema.Struct<{
         id: typeof Schema.String;
@@ -72,6 +75,9 @@ export declare const sectionLabel: (dir: string) => string;
 /** The page shown for an address that is not a page: `content/404.md` if the author wrote one. */
 export declare const notFoundPage: (content: Content) => Page;
 export declare const pageAt: (content: Content, path: string) => Page | undefined;
-/** The text of the document's `<title>` for a page. */
-export declare const documentTitle: (content: Content, page: Page | undefined) => string;
-export declare const frame: (content: Content, path: string) => typeof FrameScope.Type;
+/**
+ * The text of the document's `<title>` for a page: the project's format (`{page} · {site}`) with the parts filled in, and the status first, in parentheses. A page whose title is the site's name
+ * (the home page, usually) is that name alone. The author's `title` function may replace the parts; the caller cleans the result (control and direction-override characters out, length limited).
+ */
+export declare const documentTitle: (content: Content, page: Page | undefined, parts?: TitleParts) => string;
+export declare const frame: (content: Content, path: string, viewport?: Viewport) => typeof FrameScope.Type;

package/dist/scope.js

@@ -36,6 +36,8 @@ export const FrameScope = Schema.Struct({
     /** The `##` and `###` headings of the current page; `hasToc` is false when there are none. */
     hasToc: Schema.Boolean,
     toc: Schema.Array(Schema.Struct({ id: Schema.String, href: Schema.String, label: Schema.String, level: Schema.Number })),
+    /** How much room the page has: `"compact"`, `"medium"` or `"expanded"` (see `Viewport`). `{#if viewport == "compact"}` chooses a layout for a phone. The server renders `expanded`; the browser corrects it after it starts. */
+    viewport: Schema.Literal("compact", "medium", "expanded"),
     /** The page's body. Draw it with `<blocks items={blocks} />`, or draw each block yourself. */
     blocks: Schema.Array(BlockView),
     /** Neighbours in navigation order; `href` is empty when there is none. */
@@ -91,15 +93,17 @@ export const notFoundPage = (content) => content.notFound ?? {
     ],
 };
 export const pageAt = (content, path) => content.pages.find((page) => page.path === path);
-/** The text of the document's `<title>` for a page. */
-export const documentTitle = (content, page) => page === undefined
-    ? `${notFoundPage(content).title} · ${content.site.name}`
-    : page.path === "/"
-        ? page.title === content.site.name
-            ? page.title
-            : `${page.title} · ${content.site.name}`
-        : `${page.title} · ${content.site.name}`;
-export const frame = (content, path) => {
+/**
+ * The text of the document's `<title>` for a page: the project's format (`{page} · {site}`) with the parts filled in, and the status first, in parentheses. A page whose title is the site's name
+ * (the home page, usually) is that name alone. The author's `title` function may replace the parts; the caller cleans the result (control and direction-override characters out, length limited).
+ */
+export const documentTitle = (content, page, parts = {}) => {
+    const shown = parts.page ?? (page === undefined ? notFoundPage(content).title : page.title);
+    const app = parts.app ?? content.site.name;
+    const body = shown === app ? shown : content.site.title.replaceAll("{page}", shown).replaceAll("{site}", app);
+    return parts.status === undefined || parts.status === "" ? body : `(${parts.status}) ${body}`;
+};
+export const frame = (content, path, viewport = "expanded") => {
     const page = pageAt(content, path);
     const shown = page ?? notFoundPage(content);
     const at = page === undefined ? -1 : content.pages.indexOf(page);
@@ -115,6 +119,7 @@ export const frame = (content, path) => {
     }
     return {
         site: content.site.name,
+        viewport,
         home: withBase(content.site.base, "/"),
         title: shown.title,
         description: shown.description,

package/dist/server.js

@@ -10,7 +10,7 @@ export const createRenderer = ({ content, program, author }) => {
     const table = routes(content);
     return async (pathname, built) => {
         const state = stateFor(content, pathname, author);
-        const served = await Effect.runPromise(renderToHtml(app, { plugins: [plugin(content, built)], state }));
+        const served = await Effect.runPromise(renderToHtml(app, { plugins: [plugin(content, built, author)], state }));
         const boot = safe(JSON.stringify({ state: served.state, built }));
         return {
             status: table.known(pathname) ? 200 : 404,

package/dist/transport.d.ts

@@ -0,0 +1,37 @@
+import type { Effect } from "effect";
+export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** Why a request did not give a value. None of them carries the response text, the address or a header: those can hold a secret. */
+export type HttpError = {
+    readonly _tag: "Offline";
+} | {
+    readonly _tag: "Status";
+    readonly status: number;
+} | {
+    readonly _tag: "Decode";
+} | {
+    readonly _tag: "Timeout";
+} | {
+    readonly _tag: "Aborted";
+} | {
+    readonly _tag: "TooLarge";
+} | {
+    readonly _tag: "Unsafe";
+    readonly reason: string;
+};
+/** The request as it goes out: already checked, with its final address. Headers are lower-case. */
+export interface TransportRequest {
+    readonly method: Method;
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly timeoutMs: number;
+}
+/** The answer as it came back, whatever its status. Headers are lower-case. `text` is empty for no content. */
+export interface TransportResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly text: string;
+}
+export type Transport = (request: TransportRequest) => Effect.Effect<TransportResponse, HttpError>;
+/** Wraps the next transport: change the request on the way in, the answer on the way out, call `next` more than once (retry) or not at all (a cached answer). */
+export type Interceptor = (next: Transport) => Transport;

package/dist/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/viewport.d.ts

@@ -0,0 +1,15 @@
+import type { Viewport } from "./index.js";
+export declare const MEDIUM = 600;
+export declare const EXPANDED = 840;
+export declare const viewportOf: (width: number) => Viewport;
+interface Query {
+    readonly matches: boolean;
+    addEventListener(type: "change", listener: () => void): void;
+    removeEventListener(type: "change", listener: () => void): void;
+}
+export interface MediaWindow {
+    matchMedia(query: string): Query;
+}
+/** Calls `changed` with the current class now, and again whenever it changes. Returns the function that stops watching. */
+export declare const watchViewport: (win: MediaWindow, changed: (viewport: Viewport) => void) => (() => void);
+export {};

package/dist/viewport.js

@@ -0,0 +1,24 @@
+export const MEDIUM = 600;
+export const EXPANDED = 840;
+export const viewportOf = (width) => (width >= EXPANDED ? "expanded" : width >= MEDIUM ? "medium" : "compact");
+/** Calls `changed` with the current class now, and again whenever it changes. Returns the function that stops watching. */
+export const watchViewport = (win, changed) => {
+    const medium = win.matchMedia(`(min-width: ${MEDIUM}px)`);
+    const expanded = win.matchMedia(`(min-width: ${EXPANDED}px)`);
+    const current = () => (expanded.matches ? "expanded" : medium.matches ? "medium" : "compact");
+    let last;
+    const check = () => {
+        const now = current();
+        if (now !== last) {
+            last = now;
+            changed(now);
+        }
+    };
+    medium.addEventListener("change", check);
+    expanded.addEventListener("change", check);
+    check();
+    return () => {
+        medium.removeEventListener("change", check);
+        expanded.removeEventListener("change", check);
+    };
+};

package/dist/vocabulary.d.ts

@@ -0,0 +1,9 @@
+import type { WebPrimitives } from "@valancex/port-web";
+export interface Vocabulary {
+    /** The target's id (`web`). */
+    readonly target: string;
+    /** The tags, each with its props and events. */
+    readonly tags: WebPrimitives;
+}
+/** The web's vocabulary: HTML elements, with `class`, `theme`, `id` and `aria-*` as styling and accessibility hooks. */
+export declare const webVocabulary: Vocabulary;

package/dist/vocabulary.js

@@ -0,0 +1,3 @@
+import { primitives } from "./primitives.js";
+/** The web's vocabulary: HTML elements, with `class`, `theme`, `id` and `aria-*` as styling and accessibility hooks. */
+export const webVocabulary = { target: "web", tags: primitives };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valancex/common",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The author's side of a VALANCE application (defineApp, component, field) and the runtime the vlx build runs: the browser and server entries. What src/main.ts imports; @valancex/cli builds what it describes.",
   "keywords": [
     "valance",
@@ -32,15 +32,19 @@
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
     },
-    "./server": {
-      "types": "./dist/server.d.ts",
-      "default": "./dist/server.js"
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
     },
     "./internal": {
       "types": "./dist/internal.d.ts",
       "default": "./dist/internal.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
   },
   "types": "./dist/index.d.ts",
   "files": [
@@ -53,8 +57,9 @@
   },
   "dependencies": {
     "@valancex/mesh-runtime": "^0.11.0",
+    "@valancex/nexus": "^0.12.0",
     "@valancex/port-web": "^0.4.0",
-    "@valancex/valance": "^0.11.0"
+    "@valancex/valance": "^0.12.0"
   },
   "peerDependencies": {
     "effect": "^3.10.0"