@valancex/common 0.12.0 → 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/app.d.ts

@@ -1,8 +1,8 @@
 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";
+import { pageAt } from "./scope.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 {
@@ -26,10 +26,13 @@ export declare const ownNames: (author: DefinedApp | undefined) => {
 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 commandTable: (author: DefinedApp | undefined, known?: (page: string) => boolean) => (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>;
+/**
+ * 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.
+ */
+export declare const titleFor: (content: Content, page: ReturnType<typeof pageAt>, state: AppState, author: DefinedApp | undefined) => string;

package/dist/app.js

@@ -2,12 +2,22 @@
 // `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 { History, permit } from "@valancex/router";
+import * as Nexus from "@valancex/nexus";
+import { Effect, Schema, Stream } from "effect";
 import { documentTitle, frame, FrameScope, pageAt, RESERVED } from "./scope.js";
-import { primitives } from "./primitives.js";
-import { normalize, routes } from "./routes.js";
+import { normalize } from "./routes.js";
+import { derivedOf } from "./index.js";
+import { Navigation } from "./navigation.js";
+import * as StoreOps from "./store.js";
 import { badDefaults, stateOf } from "./state.js";
-const PageSchema = Schema.Struct({ page: Schema.String, viewport: Schema.Literal("compact", "medium", "expanded") });
+const PageSchema = Schema.Struct({
+    page: Schema.String,
+    trail: Schema.Array(Schema.String),
+    cursor: Schema.Number,
+    viewport: Schema.Literal("compact", "medium", "expanded"),
+    colorScheme: Schema.Literal("light", "dark"),
+});
 /** A mistake in `src/main.ts`, reported with what to change. */
 export class AppDefinitionError extends Error {
     constructor(message) {
@@ -15,15 +25,34 @@ export class AppDefinitionError extends Error {
         this.name = "AppDefinitionError";
     }
 }
-const authorFields = (author) => Object.keys(stateOf(author)?.schema.fields ?? {});
+const authorFields = (author) => [...Object.keys(stateOf(author)?.schema.fields ?? {}), ...Object.keys(derivedOf(author))];
+/** What the author keeps between runs: state fields, and `"navigation"` (the list of pages visited, where the engine keeps it). */
+const persisted = (author) => author?.persist ?? [];
+/** The state fields among them. */
+const persistedFields = (author) => persisted(author).filter((name) => name !== "navigation");
+/** The key the persisted fields are stored under. */
+const STORE_KEY = "state";
+/** The derived values for a state, by name. */
+const derivedValues = (author, state) => Object.fromEntries(Object.entries(derivedOf(author)).map(([name, each]) => [name, each.from(state)]));
 /** 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');
+        if (name === "page" || name === "trail" || name === "cursor") {
+            throw new AppDefinitionError(`src/main.ts: the state field "${name}" is the framework's (which page is shown, and the pages visited); choose another`);
+        }
+    }
+    const fields = Object.keys(stateOf(author)?.schema.fields ?? {});
+    for (const name of persistedFields(author)) {
+        if (!fields.includes(name)) {
+            throw new AppDefinitionError(`src/main.ts: \`persist\` names "${name}", which is not a state field${fields.length === 0 ? " (the state has none)" : ` (the fields: ${fields.join(", ")}; "navigation" keeps the pages visited)`}`);
+        }
+    }
+    for (const name of Object.keys(derivedOf(author))) {
+        if (fields.includes(name)) {
+            throw new AppDefinitionError(`src/main.ts: "${name}" is both a state field and a derived value; a name is one or the other`);
         }
     }
     for (const name of badDefaults(author)) {
@@ -33,7 +62,11 @@ export const checkDefinition = (author) => {
     const own = author?.commands?.(Valance.command({})) ?? {};
     for (const [name, what] of [
         ["go", "shows a page"],
+        ["back", "goes to the page before this one in the trail"],
+        ["forward", "goes to the page after this one in the trail"],
         ["resize", "tells the layout how much room the page has"],
+        ["colorScheme", "tells the layout which colors the system asks for"],
+        ["persist", "keeps the fields named in `persist` between runs"],
     ]) {
         if (name in own) {
             throw new AppDefinitionError(`src/main.ts: "${name}" is the framework's command (it ${what}); choose another name`);
@@ -48,29 +81,134 @@ export const ownNames = (author) => ({
 /** 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);
+    const derived = Object.entries(derivedOf(author));
+    const base = state === undefined ? FrameScope : Schema.extend(FrameScope, state.schema);
+    // A derived value is a name the layout reads, with the type it was given.
+    return derived.length === 0
+        ? base
+        : Schema.extend(base, Schema.Struct(Object.fromEntries(derived.map(([name, each]) => [name, each.schema]))));
 };
 export const stateSchema = (author) => {
     const state = stateOf(author);
     return state === undefined ? PageSchema : Schema.extend(PageSchema, state.schema);
 };
+/**
+ * The command the application starts with when the author names fields in `persist`: load them from the platform's store, then save them whenever they change. A platform with no store
+ * ends it at once (the application runs without persistence); stored data that no longer fits is ignored, and the next change replaces it. It never ends otherwise: it belongs to the
+ * application and ends with it.
+ */
+const keepBetweenRuns = (author, state, command, known) => {
+    const names = persistedFields(author);
+    const navigation = persisted(author).includes("navigation");
+    const fields = stateOf(author)?.schema.fields ?? {};
+    const schema = Schema.Struct({
+        ...Object.fromEntries(names.map((name) => [name, fields[name]])),
+        ...(navigation ? { navigation: Schema.Unknown } : {}),
+    });
+    const update = (f) => state.update(f);
+    const pick = (current, keepList) => ({
+        ...Object.fromEntries(names.map((name) => [name, current[name]])),
+        ...(keepList ? { navigation: { entries: current["trail"], index: current["cursor"] } } : {}),
+    });
+    return command.effect(() => Effect.gen(function* () {
+        // does this platform leave the list to the engine? (a page's is the browser's, and the address is the truth there)
+        const engineKeepsList = navigation
+            ? yield* Nexus.Capability.require(Navigation).pipe(Effect.as(true), Effect.catchAll(() => Effect.succeed(false)))
+            : false;
+        // what a previous run kept, if the platform has a store and what is kept still fits
+        const stored = yield* StoreOps.get(STORE_KEY, schema).pipe(Effect.map((value) => ({ store: true, value })), Effect.catchTag("CapabilityUnavailableError", () => Effect.succeed({ store: false, value: undefined })), Effect.catchAll(() => Effect.succeed({ store: true, value: undefined })));
+        if (!stored.store) {
+            return;
+        }
+        if (stored.value !== undefined) {
+            const { navigation: list, ...kept } = stored.value;
+            yield* update((current) => {
+                const next = { ...current, ...kept };
+                if (!engineKeepsList) {
+                    return Effect.succeed(next);
+                }
+                // the pages visited: those that are still pages of the site, and the first page when none is
+                const restored = History.restore(list, (entry) => typeof entry === "string" && known(entry), "/");
+                return Effect.succeed({ ...next, trail: restored.entries, cursor: restored.index, page: History.current(restored) });
+            });
+        }
+        let last = JSON.stringify(pick((yield* state.get), engineKeepsList));
+        yield* Stream.runForEach(state.values, (current) => {
+            const picked = pick(current, engineKeepsList);
+            const text = JSON.stringify(picked);
+            if (text === last) {
+                return Effect.void;
+            }
+            last = text;
+            return StoreOps.set(STORE_KEY, schema, picked).pipe(Effect.ignore);
+        });
+    }));
+};
+const listOf = (current) => ({ entries: current.trail, index: current.cursor });
+const withList = (current, list) => ({ ...current, trail: [...list.entries], cursor: list.index, page: History.current(list) });
+const routeOf = (page) => ({ name: page, params: {}, query: {} });
+/**
+ * `go`, `back` and `forward`: moves along the list of pages (`History`, from the router), each first asking the author's `guard` if there is one. Going to a page puts it after the one shown
+ * and drops the pages that were ahead; Back and Forward move along the list, for a target with no browser history of its own. Without a guard they are plain transitions.
+ */
+const navigationCommands = (author, state, command) => {
+    const guard = author?.guard;
+    const go = (current, id) => (id === current.page ? current : withList(current, History.push(listOf(current), id)));
+    const traverse = (current, distance) => withList(current, History.go(listOf(current), distance));
+    const handle = state;
+    /** Asks the guard about a move to `to`; the page to go to instead when it redirects, `undefined` when it stops the move. */
+    const asked = (current, to, kind) => guard === undefined || to === current.page
+        ? Effect.succeed(to)
+        : permit(guard, { from: routeOf(current.page), to: routeOf(to), state: current, kind, data: {} }).pipe(Effect.map((answer) => (answer === true ? to : answer === false ? undefined : answer.name)));
+    const guarded = (target, kind, apply) => Effect.gen(function* () {
+        const current = yield* handle.get;
+        const to = target(current);
+        const allowed = to === undefined ? undefined : yield* asked(current, to, kind);
+        if (allowed !== undefined) {
+            // a redirect is a page to go to, not a place in the list: it is added after the page shown
+            yield* handle.update((latest) => Effect.succeed(allowed === to ? apply(latest, allowed) : go(latest, allowed)));
+        }
+    });
+    if (guard === undefined) {
+        return {
+            go: command(Schema.Struct({ id: Schema.String }), ({ id }, current) => go(current, id)),
+            back: command((current) => traverse(current, -1)),
+            forward: command((current) => traverse(current, 1)),
+        };
+    }
+    return {
+        go: command.effect(Schema.Struct({ id: Schema.String }), ({ id }) => guarded(() => id, "programmatic", (latest, to) => go(latest, to))),
+        back: command.effect(() => guarded((current) => (History.canGo(listOf(current), -1) ? current.trail[current.cursor - 1] : undefined), "history", (latest) => traverse(latest, -1))),
+        forward: command.effect(() => guarded((current) => (History.canGo(listOf(current), 1) ? current.trail[current.cursor + 1] : undefined), "history", (latest) => traverse(latest, 1))),
+    };
+};
 /** The command table: the framework's `go`, then the author's. */
-export const commandTable = (author) => (state) => {
+export const commandTable = (author, known = () => true) => (state) => {
     const command = Valance.command(state);
     const own = author?.commands?.(command) ?? {};
-    for (const name of ["go", "resize"]) {
+    for (const name of ["go", "back", "forward", "resize", "colorScheme", "persist"]) {
         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 })),
+        ...(persisted(author).length === 0 ? {} : { persist: keepBetweenRuns(author, state, command, known) }),
+        ...navigationCommands(author, state, command),
         // 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 })),
+        // The person's system changed colors: the page or the window tells the application, which tells the layout (`colorScheme`).
+        colorScheme: command(Schema.Struct({ scheme: Schema.Literal("light", "dark") }), ({ scheme }, current) => ({ ...current, colorScheme: scheme })),
         ...own,
     };
 };
-export const initialState = (author) => ({ page: "/", viewport: "expanded", ...stateOf(author)?.initial });
+export const initialState = (author) => ({
+    page: "/",
+    trail: ["/"],
+    cursor: 0,
+    viewport: "expanded",
+    colorScheme: "light",
+    ...stateOf(author)?.initial,
+});
 export const application = (content, program, author) => {
     checkDefinition(author);
     return Valance.define({
@@ -81,21 +219,29 @@ export const application = (content, program, author) => {
                 program,
                 scope: (state) => {
                     const { page, ...own } = state;
-                    return { ...frame(content, page, state.viewport), ...own };
+                    return {
+                        ...frame(content, page, state.viewport, state.colorScheme, { canGoBack: state.cursor > 0, canGoForward: state.cursor < state.trail.length - 1 }),
+                        ...own,
+                        ...derivedValues(author, state),
+                    };
                 },
             },
         },
         view: () => "layout",
-        commands: commandTable(author),
+        commands: commandTable(author, (page) => pageAt(content, page) !== undefined),
+        ...(persisted(author).length === 0 ? {} : { start: "persist" }),
     });
 };
 /** The state a request for `pathname` starts from. */
-export const stateFor = (content, pathname, author) => ({ ...initialState(author), page: normalize(pathname, content.site.base) });
+export const stateFor = (content, pathname, author) => {
+    const page = normalize(pathname, content.site.base);
+    return { ...initialState(author), page, trail: [page], cursor: 0 };
+};
 /**
  * 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) => {
+export const titleFor = (content, page, state, author) => {
     let parts = {};
     try {
         const made = author?.title?.(state, { path: state.page, title: page?.title ?? "" });
@@ -106,19 +252,3 @@ const titleFor = (content, page, state, author) => {
     }
     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.js

@@ -1,11 +1,14 @@
 // 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 { webStore } from "./store.js";
 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 { watchColorScheme } from "./color-scheme.js";
 import { watchViewport } from "./viewport.js";
-import { application, plugin } from "./app.js";
+import { application } from "./app.js";
+import { plugin } from "./web-app.js";
 export const start = async ({ content, program, author }) => {
     const container = document.getElementById("app");
     try {
@@ -17,10 +20,14 @@ export const start = async ({ content, program, author }) => {
             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 ?? [] }),
+            platform: webPlatform({ base: content.site.api, interceptors: author?.http?.interceptors ?? [], store: webStore(content.site.name) }),
             shutdown: { grace: "250 millis" },
         });
         // The server rendered for a wide window; tell the application how wide this one is (and keep telling it).
+        const unwatchScheme = watchColorScheme(window, (scheme) => {
+            container.dataset["colorScheme"] = scheme; // for a stylesheet or a test; the layout reads the state's own `colorScheme`
+            void Effect.runPromise(host.handle.invoke("app/colorScheme", [{ value: scheme }])).catch(() => undefined);
+        });
         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);
@@ -29,6 +36,7 @@ export const start = async ({ content, program, author }) => {
         addEventListener("pagehide", (event) => {
             if (!event.persisted) {
                 unwatch();
+                unwatchScheme();
                 void host.stop();
             }
         });

package/dist/color-scheme.d.ts

@@ -0,0 +1,12 @@
+import type { ColorScheme } from "./index.js";
+interface Query {
+    readonly matches: boolean;
+    addEventListener(type: "change", listener: () => void): void;
+    removeEventListener(type: "change", listener: () => void): void;
+}
+export interface SchemeWindow {
+    matchMedia(query: string): Query;
+}
+/** Calls `changed` with the current scheme now, and again whenever it changes. Returns the function that stops watching. */
+export declare const watchColorScheme: (win: SchemeWindow, changed: (scheme: ColorScheme) => void) => (() => void);
+export {};

package/dist/color-scheme.js

@@ -0,0 +1,15 @@
+/** Calls `changed` with the current scheme now, and again whenever it changes. Returns the function that stops watching. */
+export const watchColorScheme = (win, changed) => {
+    const dark = win.matchMedia("(prefers-color-scheme: dark)");
+    let last;
+    const check = () => {
+        const now = dark.matches ? "dark" : "light";
+        if (now !== last) {
+            last = now;
+            changed(now);
+        }
+    };
+    dark.addEventListener("change", check);
+    check();
+    return () => dark.removeEventListener("change", check);
+};

package/dist/desktop.d.ts

@@ -0,0 +1,22 @@
+import type { RenderTree } from "@valancex/mesh-runtime";
+import type * as Valance from "@valancex/valance";
+import type { DefinedApp } from "./index.js";
+import type { Content } from "./model.js";
+export interface DesktopParts {
+    readonly content: Content;
+    readonly program: Valance.Program;
+    readonly author?: DefinedApp | undefined;
+    /** Where the project's `public/` files are on this machine: an image whose address is a file there is drawn from it. Absent: images are drawn as their descriptions. */
+    readonly assets?: string | undefined;
+    /** The MESH runtime's module, when the host reads it (the generated entry reads the copy beside the engine). */
+    readonly wasm?: Uint8Array | undefined;
+}
+/** Runs the application on stdin and stdout until the window closes. */
+/**
+ * An image's address as the window can use it. Content says `/logo.png`, an address on the site; the window draws files it is given by absolute path, so an address that names a file under
+ * `assets` becomes that file's path, and anything else (an address on the network, a path that leaves `assets`, a file that is not there) is left as it is, and drawn as its description.
+ */
+export declare const assetPath: (assets: string, src: string) => string | undefined;
+/** The tree with each image's address turned into the file it names, where there is one. */
+export declare const withAssets: (tree: RenderTree, assets: string) => RenderTree;
+export declare const start: ({ content, program, author, wasm, assets }: DesktopParts) => Promise<void>;

package/dist/desktop.js

@@ -0,0 +1,71 @@
+// The desktop half, for the generated entry (`.valance/desktop.ts`): run the application as the engine of a native window. An author never imports this. It is what `./client` is to a page: the
+// content, the compiled program and the author's definition, run; the window itself is the Desktop PORT's, a separate program that starts this one.
+import * as Native from "@valancex/valance/native";
+import { init } from "@valancex/mesh-runtime";
+import { Effect } from "effect";
+import { statSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { application, titleFor } from "./app.js";
+import { Open } from "./open.js";
+import { systemOpen } from "./open-system.js";
+import { platformOf } from "./platform.js";
+import { Navigation } from "./navigation.js";
+import { Store } from "./store.js";
+import { fileStore, userDataDir } from "./store-file.js";
+import { routes } from "./routes.js";
+import { pageAt } from "./scope.js";
+/** Whether a link's address is one of the application's own pages (it starts with `/`, once). An address anywhere else is the `Open` capability's. */
+const onSite = (href) => href.startsWith("/") && !href.startsWith("//");
+/** Runs the application on stdin and stdout until the window closes. */
+/**
+ * An image's address as the window can use it. Content says `/logo.png`, an address on the site; the window draws files it is given by absolute path, so an address that names a file under
+ * `assets` becomes that file's path, and anything else (an address on the network, a path that leaves `assets`, a file that is not there) is left as it is, and drawn as its description.
+ */
+export const assetPath = (assets, src) => {
+    if (!src.startsWith("/") || src.startsWith("//")) {
+        return undefined;
+    }
+    const file = resolve(assets, `.${decodeURI(src).split("?")[0].split("#")[0]}`);
+    return file.startsWith(resolve(assets) + sep) && statSync(file, { throwIfNoEntry: false })?.isFile() === true ? file : undefined;
+};
+/** The tree with each image's address turned into the file it names, where there is one. */
+export const withAssets = (tree, assets) => {
+    const walk = (node) => {
+        if (node.type !== "node") {
+            return node;
+        }
+        const src = node.component === "image" ? node.props?.["src"] : undefined;
+        const file = typeof src === "string" ? assetPath(assets, src) : undefined;
+        return { ...node, ...(file === undefined ? {} : { props: { ...node.props, src: file } }), children: (node.children ?? []).map(walk) };
+    };
+    return { ...tree, root: walk(tree.root) };
+};
+export const start = async ({ content, program, author, wasm, assets }) => {
+    if (wasm !== undefined) {
+        await init(wasm);
+    }
+    const table = routes(content);
+    const opener = systemOpen();
+    await Native.run(application(content, program, author), {
+        // The window follows the system's colors unless the application asks otherwise (`appearance` in `defineApp`), and the application learns the system's (`colorScheme`).
+        appearanceOf: (state) => author?.appearance?.(state) ?? "system",
+        onScheme: (scheme, handle) => handle.invoke("app/colorScheme", [{ value: scheme }]),
+        // Back and Forward, as the window's keys and mouse buttons ask for them: the framework's own commands, which the author's `guard` may refuse.
+        onNavigate: (direction, handle) => handle.invoke(direction === "back" ? "app/back" : "app/forward", []),
+        // What the desktop supplies: a store, in the user's data directory for the application.
+        platform: platformOf([
+            [Store, fileStore(userDataDir(content.site.name))],
+            [Open, opener],
+            // a window has no history of its own: the engine keeps the list of pages, and may keep it between runs (`persist: ["navigation"]`)
+            [Navigation, { owner: "engine" }],
+        ]),
+        ...(assets === undefined ? {} : { present: (tree) => withAssets(tree, assets) }),
+        // The window's title follows the page, in the project's format (`valance.json`), or whatever the author's `title` function says.
+        titleOf: (state) => titleFor(content, pageAt(content, state.page), state, author),
+        // A link is an address, and navigation is the application's own `go` command, as it is for a page.
+        onLink: (href, handle) => onSite(href)
+            ? handle.invoke("app/go", [{ value: table.stateOf(new URL(href, "http://app.invalid/")).id }])
+            : // an address elsewhere goes to the person's own program for it, when it is one a link may open; anything else is dropped
+                opener.open(href).pipe(Effect.catchAll((error) => Effect.sync(() => console.error(`a link was not opened: ${error.message}`)))),
+    });
+};

package/dist/http.d.ts

@@ -1,5 +1,6 @@
 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. */
@@ -62,4 +63,6 @@ export declare const refreshOn401: (refresh: () => Promise<void>) => Interceptor
 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;
+export declare const webPlatform: (options: WebHttpOptions & {
+    readonly store?: StoreClient;
+}) => Nexus.Application.Platform;

package/dist/http.js

@@ -13,6 +13,8 @@
 // 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. */
@@ -185,4 +187,8 @@ export const webHttp = (options) => {
     };
 };
 /** 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) }]]));
+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 }]]),
+]));