@valancex/common 0.11.0 → 0.13.0

package/dist/http.d.ts

@@ -0,0 +1,68 @@
+import * as Nexus from "@valancex/nexus";
+import { Effect, Schema } from "effect";
+import type { StoreClient } from "./store.js";
+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 & {
+    readonly store?: StoreClient;
+}) => Nexus.Application.Platform;

package/dist/http.js

@@ -0,0 +1,194 @@
+// 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";
+import { Open, webOpen } from "./open.js";
+import { Store } from "./store.js";
+/** 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) }],
+    [Open.id, { _tag: "Available", implementation: webOpen() }],
+    ...(options.store === undefined ? [] : [[Store.id, { _tag: "Available", implementation: options.store }]]),
+]));

package/dist/index.d.ts

@@ -1,10 +1,25 @@
 /// <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;
+    /** The pages visited, in order, for `back` and `forward`: `go` adds the page it goes to after the one shown (and drops any that were ahead). */
+    readonly trail: ReadonlyArray<string>;
+    /** Where in `trail` the page shown is. */
+    readonly cursor: number;
+    /** The colors the person's system asks for: `light` or `dark`. The framework keeps it current (the page's `prefers-color-scheme`, the window's system theme); a layout reads it as `colorScheme`. The server renders `light`; the page corrects it as it starts. */
+    readonly colorScheme: ColorScheme;
 }
+/** The system's color preference. */
+export type ColorScheme = "light" | "dark";
+/** What an application asks its window to look like: a scheme, or `system` for the person's own. */
+export type Appearance = ColorScheme | "system";
+/** 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> {
@@ -16,6 +31,15 @@ export interface Field<A = unknown> {
  * Declares one field of the application's state with its type and its default in one place. The framework builds the state's schema and its initial value from the fields; the default is
  * checked against the type (by TypeScript, and again when the application is built).
  */
+export declare const DERIVED: unique symbol;
+/** A value worked out from the state, and the type it has. A template reads it by name, like a state field, and no command changes it. */
+export interface Derived<A = unknown> {
+    readonly [DERIVED]: true;
+    readonly schema: Schema.Schema<A, any, never>;
+    readonly from: (state: any) => A;
+}
+/** What `derived` is given: `derive(type, (state) => value)`. The state is the application's, as a command sees it. */
+export type DeriveMaker<S> = <A, I = A>(schema: Schema.Schema<A, I, never>, from: (state: S) => A) => Derived<A>;
 export declare const field: <A, I = A>(schema: Schema.Schema<A, I, never>, initial: NoInfer<A>) => Field<A>;
 /** Fields declared one by one. */
 export type Fields = Readonly<Record<string, Field<any>>>;
@@ -65,7 +89,33 @@ 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;
+}
+/** What differs between targets: the templates. Everything else in the definition (state, commands, title, http) is the application's, and the same on every target. */
+export interface TargetParts {
+    readonly layout?: Component;
+    readonly components?: ReadonlyArray<Component>;
+    readonly override?: ReadonlyArray<Component>;
+}
 export interface AppDefinition<S extends StateInput = {}> {
+    /**
+     * The templates of one target, for a project with more than one (`valance.web.json` and `valance.desktop.json`): `targets: { web: { layout, components }, desktop: { layout } }`. A target's
+     * `layout` replaces the top-level one, and its `components` and `override` are added to it. A target's templates are compiled against that target's vocabulary only; the state, the commands and
+     * the content are the one application's.
+     */
+    readonly targets?: {
+        readonly web?: TargetParts;
+        readonly desktop?: TargetParts;
+    };
     /** 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;
     /** Every component of the application besides the layout and the overrides. A template uses one by writing its tag; one that no template writes yet is not part of the program. */
@@ -77,13 +127,77 @@ 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 appearance this application asks of its window, for a state: `appearance: (state) => state.theme` (`"light"`, `"dark"` or `"system"`). A page draws its own colors, so it is the desktop
+     * window's: the window follows the system's theme unless this says otherwise. Absent: the system's.
+     */
+    readonly appearance?: (state: PageState & StateOf<S>) => Appearance;
+    /**
+     * The state fields that outlive a run: `persist: ["items", "theme"]`. They are loaded when the application starts and saved when they change, through the platform's `Store` (the page's
+     * storage on the web, a file in the user's data directory on the desktop), under the application's name. What was stored and no longer fits a field's type is ignored, not loaded. Where a
+     * platform has no store the application runs as it would without this. A field not listed is not kept (a `navigation` flag on one target should not follow the person to another).
+     */
+    readonly persist?: ReadonlyArray<Extract<keyof StateOf<S>, string> | "navigation">;
+    /**
+     * A guard for moving between pages by `go`, `back` and `forward`: the router's `Guard`, asked before the move. It is told where the application is going from and to (a route named for the
+     * page, with no parameters), the state, and why: `kind` is `"programmatic"` for `go` and `"history"` for `back` and `forward`. `true` lets it through, `false` stops it (nothing changes),
+     * a `redirect(...)` sends it to another page. A guard that throws or fails stops the move. Without one every move is allowed. A page's own Back and Forward are the browser's: the router
+     * guards those as `"popstate"`.
+     */
+    readonly guard?: NavigationGuard;
+    /**
+     * Values worked out from the state, for a template to read: `derived: (derive) => ({ open: derive(Schema.Number, (state) => state.items.filter((item) => !item.done).length) })`. Each has its
+     * type, as a state field does. They are computed from the state each time it changes, on every target, and a command cannot change one (change the state they come from). The function must
+     * be pure and must not throw.
+     */
+    readonly derived?: (derive: DeriveMaker<PageState & StateOf<S>>) => {
+        readonly [name: string]: Derived<any>;
+    };
     /** 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>;
 }
+/** What a navigation guard is told; the router's `GuardContext`, spelled out so the author's entry needs nothing but VALANCE and effect. */
+export interface NavigationContext {
+    readonly from: {
+        readonly name: string;
+        readonly params: Readonly<Record<string, unknown>>;
+        readonly query: Readonly<Record<string, unknown>>;
+    } | undefined;
+    readonly to: {
+        readonly name: string;
+        readonly params: Readonly<Record<string, unknown>>;
+        readonly query: Readonly<Record<string, unknown>>;
+    };
+    readonly state: unknown;
+    readonly kind: "link" | "popstate" | "programmatic" | "history" | "initial" | "close";
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/** `true` allows, `false` stops, and `{ _tag: "Redirect", name }` (the router's `redirect(page)`) goes to another page; it may answer now, later or as an Effect. */
+export type NavigationGuard = (context: NavigationContext) => unknown;
 /** The brand that says a value came from `defineApp`. */
 export declare const APP: unique symbol;
 export interface DefinedApp extends AppDefinition<any> {
     readonly [APP]: true;
 }
 /** Declares the application's component tree, state and commands. It starts nothing; the framework runs it. */
+/** What `derived` makes, for the toolchain: the function is called with the one `derive`. */
+export declare const derivedOf: (author: {
+    readonly derived?: AppDefinition<any>["derived"];
+} | undefined) => Readonly<Record<string, Derived<any>>>;
 export declare const defineApp: <S extends StateInput = {}>(definition: AppDefinition<S>) => DefinedApp;

package/dist/index.js

@@ -4,6 +4,8 @@ export const FIELD = Symbol.for("valancex.common.field");
  * Declares one field of the application's state with its type and its default in one place. The framework builds the state's schema and its initial value from the fields; the default is
  * checked against the type (by TypeScript, and again when the application is built).
  */
+export const DERIVED = Symbol.for("valancex.common.derived");
+const derive = (schema, from) => ({ [DERIVED]: true, schema: schema, from });
 export const field = (schema, initial) => ({ [FIELD]: true, schema: schema, initial });
 export const COMPONENT = Symbol.for("valancex.common.component");
 /**
@@ -21,4 +23,6 @@ export function component(template, contract = {}) {
 /** The brand that says a value came from `defineApp`. */
 export const APP = Symbol.for("valancex.common");
 /** Declares the application's component tree, state and commands. It starts nothing; the framework runs it. */
+/** What `derived` makes, for the toolchain: the function is called with the one `derive`. */
+export const derivedOf = (author) => author?.derived?.(derive) ?? {};
 export const defineApp = (definition) => ({ ...definition, [APP]: true });

package/dist/internal.d.ts

@@ -1,6 +1,13 @@
 export * from "./app.js";
+export * from "./web-app.js";
 export * from "./model.js";
 export * from "./primitives.js";
 export * from "./routes.js";
 export * from "./scope.js";
 export * from "./state.js";
+export * from "./vocabulary.js";
+export * from "./targets.js";
+export * from "./store.js";
+export * from "./open.js";
+export * from "./navigation.js";
+export * from "./platform.js";

package/dist/internal.js

@@ -1,8 +1,15 @@
 // What the build tools share with the runtime: the content model, the tag table, the scope a layout reads, the state and the application they make. `@valancex/cli` builds with these and the generated
 // entries run them, so there is one definition of each. Not for applications: an application's code is `@valancex/common` (the entry point).
 export * from "./app.js";
+export * from "./web-app.js";
 export * from "./model.js";
 export * from "./primitives.js";
 export * from "./routes.js";
 export * from "./scope.js";
 export * from "./state.js";
+export * from "./vocabulary.js";
+export * from "./targets.js";
+export * from "./store.js";
+export * from "./open.js";
+export * from "./navigation.js";
+export * from "./platform.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/navigation.d.ts

@@ -0,0 +1,6 @@
+import * as Nexus from "@valancex/nexus";
+/** The platform has no history of its own: the engine keeps the list (`trail` and `cursor`). */
+export interface NavigationOwner {
+    readonly owner: "engine";
+}
+export declare const Navigation: Nexus.Capability.Capability<NavigationOwner>;

package/dist/navigation.js

@@ -0,0 +1,5 @@
+// Who keeps the list of places the person has been (docs/application-model/NAVIGATION.md). A page has the browser's: its session history holds the list, restores it, and moves along it with the
+// person's Back and Forward. A window has none, so the engine keeps the list in its state; a platform that supplies this capability is one of those, and only there does `persist: ["navigation"]`
+// do anything (restoring a stored page on the web would argue with the address, which is the truth there).
+import * as Nexus from "@valancex/nexus";
+export const Navigation = Nexus.Capability.define("valance/navigation");

package/dist/open-system.d.ts

@@ -0,0 +1,12 @@
+import type { OpenClient } from "./open.js";
+/** The program and arguments that open `address` on `platform`. */
+export declare const openerFor: (address: string, platform?: NodeJS.Platform) => {
+    readonly program: string;
+    readonly args: ReadonlyArray<string>;
+};
+type Spawn = (program: string, args: ReadonlyArray<string>) => {
+    readonly on: (event: "error", listener: (error: Error) => void) => unknown;
+    readonly unref: () => void;
+};
+export declare const systemOpen: (spawn?: Spawn, platform?: NodeJS.Platform) => OpenClient;
+export {};

package/dist/open-system.js

@@ -0,0 +1,31 @@
+// The desktop's opener: the system's own, given the address as an argument (never through a shell, so the address is data and nothing else). Node only.
+import { Effect } from "effect";
+import { spawn as nodeSpawn } from "node:child_process";
+import { OpenError, refusal } from "./open.js";
+/** The program and arguments that open `address` on `platform`. */
+export const openerFor = (address, platform = process.platform) => platform === "win32"
+    ? { program: "rundll32", args: ["url.dll,FileProtocolHandler", address] }
+    : platform === "darwin"
+        ? { program: "open", args: [address] }
+        : { program: "xdg-open", args: [address] };
+export const systemOpen = (spawn = (program, args) => nodeSpawn(program, [...args], { detached: true, stdio: "ignore" }), platform = process.platform) => ({
+    open: (address) => {
+        const reason = refusal(address);
+        if (reason !== undefined) {
+            return Effect.fail(new OpenError("Refused", reason));
+        }
+        const { program, args } = openerFor(address, platform);
+        return Effect.async((resume) => {
+            try {
+                const child = spawn(program, args);
+                child.on("error", () => resume(Effect.fail(new OpenError("Unavailable", `${program} could not be started`))));
+                child.unref();
+                // handed over: the opener is the system's, and does not report back to a program that asked
+                setTimeout(() => resume(Effect.void), 0);
+            }
+            catch {
+                resume(Effect.fail(new OpenError("Unavailable", `${program} could not be started`)));
+            }
+        });
+    },
+});

package/dist/open.d.ts

@@ -0,0 +1,23 @@
+import * as Nexus from "@valancex/nexus";
+import { Effect } from "effect";
+export declare class OpenError extends Error {
+    readonly kind: "Refused" | "Unavailable";
+    readonly _tag = "OpenError";
+    constructor(kind: "Refused" | "Unavailable", message: string);
+}
+export interface OpenClient {
+    /** Opens `address` in the program the platform keeps for it. Resolves when it was handed over, not when anything finished. */
+    readonly open: (address: string) => Effect.Effect<void, OpenError>;
+}
+/** The capability: ask for it in a command (`Open.open`), and the platform says whether it has one. */
+export declare const Open: Nexus.Capability.Capability<OpenClient>;
+/** The schemes an address may have to be opened. */
+export declare const OPENABLE: readonly ["https:", "http:", "mailto:"];
+/** Why `address` may not be opened, or `undefined` when it may: an absolute address of an openable scheme, without a control character, of a sensible length. */
+export declare const refusal: (address: string) => string | undefined;
+/** Opens `address` through the platform's opener. Requires the `Open` capability. */
+export declare const open: (address: string) => Effect.Effect<void, OpenError | Nexus.Capability.CapabilityUnavailableError, Nexus.Capability.EnvironmentShape>;
+/** The page's opener: a new tab, with no link back to this page. */
+export declare const webOpen: (win?: {
+    readonly open: (url: string, target: string, features: string) => unknown;
+}) => OpenClient;

package/dist/open.js

@@ -0,0 +1,47 @@
+// Sending a person to an address outside the application: a web page in their browser, a mail in their mail program. NEXUS and VALANCE hold no such thing (their rule): it is a capability the
+// platform supplies. The web's is a new tab; the desktop's is the system's own opener (`./open-system`). Only the addresses a person expects a link to open are opened: a script, a file or a
+// program's own scheme is refused, whatever text asked.
+import * as Nexus from "@valancex/nexus";
+import { Effect } from "effect";
+export class OpenError extends Error {
+    kind;
+    _tag = "OpenError";
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "OpenError";
+    }
+}
+/** The capability: ask for it in a command (`Open.open`), and the platform says whether it has one. */
+export const Open = Nexus.Capability.define("valance/open");
+/** The schemes an address may have to be opened. */
+export const OPENABLE = ["https:", "http:", "mailto:"];
+/** Why `address` may not be opened, or `undefined` when it may: an absolute address of an openable scheme, without a control character, of a sensible length. */
+export const refusal = (address) => {
+    // oxlint-disable-next-line no-control-regex -- a control character in an address is how one is smuggled into a command line
+    if (address.length === 0 || address.length > 2048 || /[\u0000-\u001f\u007f\s]/.test(address)) {
+        return "an address is one line of text, at most 2048 characters";
+    }
+    try {
+        const url = new URL(address);
+        return OPENABLE.includes(url.protocol) ? undefined : `a ${url.protocol} address is not opened (only ${OPENABLE.join(", ")})`;
+    }
+    catch {
+        return "not an absolute address";
+    }
+};
+/** Opens `address` through the platform's opener. Requires the `Open` capability. */
+export const open = (address) => Effect.flatMap(Nexus.Capability.require(Open), (client) => client.open(address));
+/** The page's opener: a new tab, with no link back to this page. */
+export const webOpen = (win) => ({
+    open: (address) => {
+        const reason = refusal(address);
+        if (reason !== undefined) {
+            return Effect.fail(new OpenError("Refused", reason));
+        }
+        const target = win ?? globalThis.window;
+        return target === undefined
+            ? Effect.fail(new OpenError("Unavailable", "this page cannot open a tab"))
+            : Effect.try({ try: () => void target.open(address, "_blank", "noopener,noreferrer"), catch: () => new OpenError("Unavailable", "the page's tab was blocked") });
+    },
+});

package/dist/platform.d.ts

@@ -0,0 +1,5 @@
+import * as Nexus from "@valancex/nexus";
+/** A platform that supplies each `[capability, implementation]` given. */
+export declare const platformOf: (capabilities: ReadonlyArray<readonly [{
+    readonly id: string;
+}, unknown]>) => Nexus.Application.Platform;