@valancex/common 0.11.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/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

@@ -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) => 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 });
+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,23 +25,52 @@ 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)) {
         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"],
+        ["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`);
+        }
     }
 };
 /** The names `src/main.ts` adds: state fields (readable in the layout) and commands (runnable from it). */
@@ -42,22 +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) ?? {};
-    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", "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 })), ...own };
+    return {
+        ...(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: "/", ...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({
@@ -68,29 +219,36 @@ export const application = (content, program, author) => {
                 program,
                 scope: (state) => {
                     const { page, ...own } = state;
-                    return { ...frame(content, page), ...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) });
-/** The plugin that makes the application a website: its tags, its URL policy, and its document head. */
-export const plugin = (content, built) => ({
-    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: documentTitle(content, page),
-            meta: shown.description === "" ? [] : [{ name: "description", content: shown.description }],
-            links: [...built.styles.map((href) => ({ rel: "stylesheet", href })), ...canonical],
-        };
-    },
-});
+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.
+ */
+export 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);
+};

package/dist/client.js

@@ -1,8 +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 { application, plugin } from "./app.js";
+import { Effect } from "effect";
+import { webPlatform } from "./http.js";
+import { watchColorScheme } from "./color-scheme.js";
+import { watchViewport } from "./viewport.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 {
@@ -12,12 +18,25 @@ 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 ?? [], 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);
+        });
         container.dataset["valance"] = "running"; // readiness marker for whoever drives the page
         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}`)))),
+    });
+};