@valancex/common 0.11.0 → 0.13.0

package/dist/platform.js

@@ -0,0 +1,4 @@
+// What a platform supplies the application: its capabilities, by contract. `Web.run` and `Native.run` each take one; the web's is `webPlatform` (`./http`), the desktop's is made in `./desktop`.
+import * as Nexus from "@valancex/nexus";
+/** A platform that supplies each `[capability, implementation]` given. */
+export const platformOf = (capabilities) => Nexus.Capability.EnvironmentLive(new Map(capabilities.map(([capability, implementation]) => [capability.id, { _tag: "Available", implementation }])));

package/dist/primitives.js

@@ -10,6 +10,12 @@ const label = Web.attribute("aria-label");
 // A prop a tag declares is a prop every use of it must write (docs/application-model/HANDOFF.md, finding D1: MESH derives "required" from the realization and has no optional prop). So the
 // table is many narrow tags rather than a few wide ones: a tag carries only what its uses always have.
 export const primitives = {
+    // The portable core (the same names, props, events and payloads as the Desktop PORT's vocabulary: a component written with only these runs on both targets). `column` and `row` are custom
+    // elements, because this table cannot give a `div` a fixed attribute to tell them apart; `vlx` ships their layout (`core.css`). `heading` is an `h2` with its level as `aria-level`.
+    column: { element: "vlx-column" },
+    row: { element: "vlx-row" },
+    heading: { element: "h2", props: { level: Web.attribute("aria-level") } },
+    text: { element: "span" },
     shell: { element: "div", props: { class: klass, theme: Web.attribute("data-theme") } },
     div: { element: "div", props: { class: klass } },
     header: { element: "header", props: { class: klass } },
@@ -37,5 +43,24 @@ export const primitives = {
     a: { element: "a", props: { href: Web.attribute("href") } },
     /** A link that is part of the page's furniture (navigation, a brand): it has a class, and says whether it is where you are (`aria-current`: "page" or "false"). */
     link: { element: "a", props: { href: Web.attribute("href"), class: klass, current: Web.attribute("aria-current") } },
-    button: { element: "button", props: { class: klass, pressed: Web.attribute("aria-pressed") }, events: { click: { type: "click" } } },
+    /** A box to tick, reporting `change` with the new value (a boolean). It is an `<input type="checkbox">` (a constant attribute of the primitive), and `checked` is live and server-rendered (`controlledBoolean`). */
+    checkbox: {
+        element: "input",
+        attributes: { type: "checkbox" },
+        props: { checked: Web.controlledBoolean("checked"), label },
+        events: { change: Web.event("change", { kind: "boolean", of: (_event, element) => element.checked }) },
+    },
+    /** A text field, reporting `change` with the new text (a string); the field shows what the state says. */
+    textfield: {
+        element: "input",
+        props: { value: Web.controlled("value"), placeholder: Web.attribute("placeholder"), label },
+        events: {
+            change: Web.event("input", { kind: "string", of: (_event, element) => element.value }),
+            // Enter: the person is done with what they typed
+            submit: Web.event("keydown", undefined, { key: "Enter" }),
+            // Escape: the person backs out of what they typed
+            cancel: Web.event("keydown", undefined, { key: "Escape" }),
+        },
+    },
+    button: { element: "button", props: { class: klass, pressed: Web.attribute("aria-pressed"), disabled: Web.booleanAttribute("disabled") }, events: { click: { type: "click" } } },
 };

package/dist/routes.js

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

package/dist/scope.d.ts

@@ -1,4 +1,5 @@
 import { Schema } from "effect";
+import type { ColorScheme, TitleParts, Viewport } from "./index.js";
 import type { Content, Page } from "./model.js";
 export declare const FrameScope: Schema.Struct<{
     /** The application's name (`valance.json`). */
@@ -29,6 +30,14 @@ export declare const FrameScope: Schema.Struct<{
         label: typeof Schema.String;
         level: typeof Schema.Number;
     }>>;
+    /** How much room the page has: `"compact"`, `"medium"` or `"expanded"` (see `Viewport`). `{#if viewport == "compact"}` chooses a layout for a phone. The server renders `expanded`; the browser corrects it after it starts. */
+    viewport: Schema.Literal<["compact", "medium", "expanded"]>;
+    /** The colors the person's system asks for: `"light"` or `"dark"`. `theme={theme == "system" ? colorScheme : theme}` lets an application offer "follow the system" beside its own choices. The server renders `light`; the page corrects it after it starts. */
+    colorScheme: Schema.Literal<["light", "dark"]>;
+    /** Whether there is a page before this one in the trail (`back()` goes to it). `disabled={!canGoBack}` greys a Back button. */
+    canGoBack: typeof Schema.Boolean;
+    /** Whether there is a page after this one in the trail (`forward()` goes to it), as there is after a `back()`. */
+    canGoForward: typeof Schema.Boolean;
     /** The page's body. Draw it with `<blocks items={blocks} />`, or draw each block yourself. */
     blocks: Schema.Array$<Schema.Struct<{
         id: typeof Schema.String;
@@ -72,6 +81,12 @@ export declare const sectionLabel: (dir: string) => string;
 /** The page shown for an address that is not a page: `content/404.md` if the author wrote one. */
 export declare const notFoundPage: (content: Content) => Page;
 export declare const pageAt: (content: Content, path: string) => Page | undefined;
-/** The text of the document's `<title>` for a page. */
-export declare const documentTitle: (content: Content, page: Page | undefined) => string;
-export declare const frame: (content: Content, path: string) => typeof FrameScope.Type;
+/**
+ * The text of the document's `<title>` for a page: the project's format (`{page} · {site}`) with the parts filled in, and the status first, in parentheses. A page whose title is the site's name
+ * (the home page, usually) is that name alone. The author's `title` function may replace the parts; the caller cleans the result (control and direction-override characters out, length limited).
+ */
+export declare const documentTitle: (content: Content, page: Page | undefined, parts?: TitleParts) => string;
+export declare const frame: (content: Content, path: string, viewport?: Viewport, colorScheme?: ColorScheme, trail?: {
+    readonly canGoBack: boolean;
+    readonly canGoForward: boolean;
+}) => typeof FrameScope.Type;

package/dist/scope.js

@@ -36,6 +36,14 @@ export const FrameScope = Schema.Struct({
     /** The `##` and `###` headings of the current page; `hasToc` is false when there are none. */
     hasToc: Schema.Boolean,
     toc: Schema.Array(Schema.Struct({ id: Schema.String, href: Schema.String, label: Schema.String, level: Schema.Number })),
+    /** How much room the page has: `"compact"`, `"medium"` or `"expanded"` (see `Viewport`). `{#if viewport == "compact"}` chooses a layout for a phone. The server renders `expanded`; the browser corrects it after it starts. */
+    viewport: Schema.Literal("compact", "medium", "expanded"),
+    /** The colors the person's system asks for: `"light"` or `"dark"`. `theme={theme == "system" ? colorScheme : theme}` lets an application offer "follow the system" beside its own choices. The server renders `light`; the page corrects it after it starts. */
+    colorScheme: Schema.Literal("light", "dark"),
+    /** Whether there is a page before this one in the trail (`back()` goes to it). `disabled={!canGoBack}` greys a Back button. */
+    canGoBack: Schema.Boolean,
+    /** Whether there is a page after this one in the trail (`forward()` goes to it), as there is after a `back()`. */
+    canGoForward: Schema.Boolean,
     /** The page's body. Draw it with `<blocks items={blocks} />`, or draw each block yourself. */
     blocks: Schema.Array(BlockView),
     /** Neighbours in navigation order; `href` is empty when there is none. */
@@ -91,15 +99,17 @@ export const notFoundPage = (content) => content.notFound ?? {
     ],
 };
 export const pageAt = (content, path) => content.pages.find((page) => page.path === path);
-/** The text of the document's `<title>` for a page. */
-export const documentTitle = (content, page) => page === undefined
-    ? `${notFoundPage(content).title} · ${content.site.name}`
-    : page.path === "/"
-        ? page.title === content.site.name
-            ? page.title
-            : `${page.title} · ${content.site.name}`
-        : `${page.title} · ${content.site.name}`;
-export const frame = (content, path) => {
+/**
+ * The text of the document's `<title>` for a page: the project's format (`{page} · {site}`) with the parts filled in, and the status first, in parentheses. A page whose title is the site's name
+ * (the home page, usually) is that name alone. The author's `title` function may replace the parts; the caller cleans the result (control and direction-override characters out, length limited).
+ */
+export const documentTitle = (content, page, parts = {}) => {
+    const shown = parts.page ?? (page === undefined ? notFoundPage(content).title : page.title);
+    const app = parts.app ?? content.site.name;
+    const body = shown === app ? shown : content.site.title.replaceAll("{page}", shown).replaceAll("{site}", app);
+    return parts.status === undefined || parts.status === "" ? body : `(${parts.status}) ${body}`;
+};
+export const frame = (content, path, viewport = "expanded", colorScheme = "light", trail = { canGoBack: false, canGoForward: false }) => {
     const page = pageAt(content, path);
     const shown = page ?? notFoundPage(content);
     const at = page === undefined ? -1 : content.pages.indexOf(page);
@@ -115,6 +125,10 @@ export const frame = (content, path) => {
     }
     return {
         site: content.site.name,
+        viewport,
+        colorScheme,
+        canGoBack: trail.canGoBack,
+        canGoForward: trail.canGoForward,
         home: withBase(content.site.base, "/"),
         title: shown.title,
         description: shown.description,

package/dist/server.js

@@ -1,7 +1,8 @@
 import { renderHead } from "@valancex/valance/web/plugin";
 import { renderToHtml } from "@valancex/valance/web/server";
 import { Effect } from "effect";
-import { application, plugin, stateFor } from "./app.js";
+import { application, stateFor } from "./app.js";
+import { plugin } from "./web-app.js";
 import { routes } from "./routes.js";
 export { routes };
 const safe = (json) => json.replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
@@ -10,7 +11,7 @@ export const createRenderer = ({ content, program, author }) => {
     const table = routes(content);
     return async (pathname, built) => {
         const state = stateFor(content, pathname, author);
-        const served = await Effect.runPromise(renderToHtml(app, { plugins: [plugin(content, built)], state }));
+        const served = await Effect.runPromise(renderToHtml(app, { plugins: [plugin(content, built, author)], state }));
         const boot = safe(JSON.stringify({ state: served.state, built }));
         return {
             status: table.known(pathname) ? 200 : 404,

package/dist/store-file.d.ts

@@ -0,0 +1,4 @@
+import type { StoreClient } from "./store.js";
+/** Where an application keeps its data on this machine: `$XDG_DATA_HOME` (else `~/.local/share`) on Linux, `%APPDATA%` on Windows, `~/Library/Application Support` on macOS, then the application's name. */
+export declare const userDataDir: (name: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform) => string;
+export declare const fileStore: (dir: string) => StoreClient;

package/dist/store-file.js

@@ -0,0 +1,49 @@
+// The desktop's store: one JSON file per key in the user's data directory for the application. Node only (the page never loads this). A write goes to a temporary file and is renamed over the
+// real one, so a crash leaves the old value or the new one, never half of one.
+import { Effect } from "effect";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { checkKey, decodeStored, encodeStored, MAX_STORED, StoreError } from "./store.js";
+/** Where an application keeps its data on this machine: `$XDG_DATA_HOME` (else `~/.local/share`) on Linux, `%APPDATA%` on Windows, `~/Library/Application Support` on macOS, then the application's name. */
+export const userDataDir = (name, env = process.env, platform = process.platform) => {
+    const app = name.replace(/[^\w.-]+/g, "-").replace(/^[.-]+/, "") || "app";
+    const base = platform === "win32"
+        ? (env["APPDATA"] ?? join(homedir(), "AppData", "Roaming"))
+        : platform === "darwin"
+            ? join(homedir(), "Library", "Application Support")
+            : (env["XDG_DATA_HOME"] ?? join(homedir(), ".local", "share"));
+    return join(base, app);
+};
+const unavailable = () => new StoreError("Unavailable", "the data directory refused");
+export const fileStore = (dir) => {
+    const file = (key) => join(dir, `${key}.json`);
+    return {
+        get: (key, schema) => Effect.flatMap(checkKey(key), (safe) => Effect.flatMap(Effect.try({
+            try: () => {
+                try {
+                    return readFileSync(file(safe), "utf8");
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        return null;
+                    }
+                    throw error;
+                }
+            },
+            catch: unavailable,
+        }), (text) => (text === null ? Effect.succeed(undefined) : decodeStored(text, schema)))),
+        set: (key, schema, value) => Effect.flatMap(checkKey(key), (safe) => Effect.flatMap(encodeStored(value, schema), (text) => text.length > MAX_STORED
+            ? Effect.fail(new StoreError("Full", "the value is larger than a store holds"))
+            : Effect.try({
+                try: () => {
+                    mkdirSync(dir, { recursive: true });
+                    const temporary = `${file(safe)}.${process.pid}.tmp`;
+                    writeFileSync(temporary, text);
+                    renameSync(temporary, file(safe));
+                },
+                catch: unavailable,
+            }))),
+        remove: (key) => Effect.flatMap(checkKey(key), (safe) => Effect.try({ try: () => rmSync(file(safe), { force: true }), catch: unavailable })),
+    };
+};

package/dist/store.d.ts

@@ -0,0 +1,40 @@
+import * as Nexus from "@valancex/nexus";
+import { Effect, Schema } from "effect";
+/** Why a store did not do what was asked, by kind. */
+export declare class StoreError extends Error {
+    readonly kind: "Unavailable" | "Full" | "Decode" | "Unsafe";
+    readonly _tag = "StoreError";
+    constructor(kind: "Unavailable" | "Full" | "Decode" | "Unsafe", message: string);
+}
+export interface StoreClient {
+    /** The value stored under `key`, decoded by `schema`; `undefined` when nothing is stored. */
+    readonly get: <A>(key: string, schema: Schema.Schema<A, any, never>) => Effect.Effect<A | undefined, StoreError>;
+    /** Stores `value` under `key`, encoded by `schema`. */
+    readonly set: <A>(key: string, schema: Schema.Schema<A, any, never>, value: A) => Effect.Effect<void, StoreError>;
+    /** Forgets `key`. */
+    readonly remove: (key: string) => Effect.Effect<void, StoreError>;
+}
+/** The capability: ask for it in a command (`Store.get`), and the platform says whether it has one. */
+export declare const Store: Nexus.Capability.Capability<StoreClient>;
+type Needs = Nexus.Capability.EnvironmentShape;
+type Failure = StoreError | Nexus.Capability.CapabilityUnavailableError;
+export declare const get: <A>(key: string, schema: Schema.Schema<A, any, never>) => Effect.Effect<A | undefined, Failure, Needs>;
+export declare const set: <A>(key: string, schema: Schema.Schema<A, any, never>, value: A) => Effect.Effect<void, Failure, Needs>;
+export declare const remove: (key: string) => Effect.Effect<void, Failure, Needs>;
+export declare const checkKey: (key: string) => Effect.Effect<string, StoreError>;
+/** Decodes stored text with `schema`: text that is not JSON, or does not fit, is `Decode`. */
+export declare const decodeStored: <A>(text: string, schema: Schema.Schema<A, any, never>) => Effect.Effect<A, StoreError>;
+export declare const encodeStored: <A>(value: A, schema: Schema.Schema<A, any, never>) => Effect.Effect<string, StoreError>;
+/** The part of `Storage` the web's store uses (so a test supplies its own). */
+export interface TextStorage {
+    readonly getItem: (key: string) => string | null;
+    readonly setItem: (key: string, value: string) => void;
+    readonly removeItem: (key: string) => void;
+}
+/** The longest value written, in characters: a page's storage is small and shared. */
+export declare const MAX_STORED = 1000000;
+/** The web's store: the page's `localStorage`, under `valance:<namespace>:<key>`. Where storage is off (a private window, blocked site data) every call is `Unavailable`, and the application runs without it. */
+export declare const webStore: (namespace: string, storage?: TextStorage) => StoreClient;
+/** The platform that supplies `store` as the `Store` capability. */
+export declare const storePlatform: (store: StoreClient) => Nexus.Application.Platform;
+export {};

package/dist/store.js

@@ -0,0 +1,60 @@
+// What an application keeps between runs. NEXUS and VALANCE hold no storage (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 a small keyed store, and the web's implementation of it (the page's `localStorage`). The desktop's, a file in the user's data directory,
+// is `./store-file` (it needs Node, so the page never loads it).
+//
+//   const saved = yield* Store.get("items", Items);        // Effect<readonly Item[] | undefined, StoreError, the Store capability>
+//   yield* Store.set("items", Items, next);
+//
+// A value goes in as JSON and comes out *decoded by the Schema the caller states*: what is stored by an older version of the application, or by anything else, and no longer fits, is not a
+// value: it is `Decode`, and nothing wrong reaches state. A failure says what kind it was and never what it carried.
+import * as Nexus from "@valancex/nexus";
+import { Effect, Schema } from "effect";
+/** Why a store did not do what was asked, by kind. */
+export class StoreError extends Error {
+    kind;
+    _tag = "StoreError";
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "StoreError";
+    }
+}
+/** The capability: ask for it in a command (`Store.get`), and the platform says whether it has one. */
+export const Store = Nexus.Capability.define("valance/store");
+const client = Nexus.Capability.require(Store);
+export const get = (key, schema) => Effect.flatMap(client, (store) => store.get(key, schema));
+export const set = (key, schema, value) => Effect.flatMap(client, (store) => store.set(key, schema, value));
+export const remove = (key) => Effect.flatMap(client, (store) => store.remove(key));
+/** A key is a word: letters, digits, `.`, `_` and `-`, so it can never name anything but the entry it is. */
+const SAFE_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+export const checkKey = (key) => SAFE_KEY.test(key) ? Effect.succeed(key) : Effect.fail(new StoreError("Unsafe", `"${key}" cannot be a store key: use letters, digits, . _ - (at most 80 characters)`));
+/** Decodes stored text with `schema`: text that is not JSON, or does not fit, is `Decode`. */
+export const decodeStored = (text, schema) => Effect.try({ try: () => JSON.parse(text), catch: () => new StoreError("Decode", "what is stored is not JSON") }).pipe(Effect.flatMap((json) => Schema.decodeUnknown(schema)(json).pipe(Effect.mapError(() => new StoreError("Decode", "what is stored no longer fits its type")))));
+export const encodeStored = (value, schema) => Schema.encode(schema)(value).pipe(Effect.mapError(() => new StoreError("Decode", "the value does not fit its type")), Effect.map((encoded) => JSON.stringify(encoded)));
+/** The longest value written, in characters: a page's storage is small and shared. */
+export const MAX_STORED = 1_000_000;
+/** The web's store: the page's `localStorage`, under `valance:<namespace>:<key>`. Where storage is off (a private window, blocked site data) every call is `Unavailable`, and the application runs without it. */
+export const webStore = (namespace, storage) => {
+    const prefix = `valance:${namespace}:`;
+    const area = () => Effect.try({
+        try: () => {
+            const found = storage ?? globalThis.localStorage;
+            if (found === undefined) {
+                throw new Error("no storage");
+            }
+            return found;
+        },
+        catch: () => new StoreError("Unavailable", "this page has no storage"),
+    });
+    const guarded = (run) => Effect.flatMap(area(), (found) => Effect.try({
+        try: () => run(found),
+        catch: (error) => new StoreError(error instanceof Error && error.name === "QuotaExceededError" ? "Full" : "Unavailable", "the page's storage refused"),
+    }));
+    return {
+        get: (key, schema) => Effect.flatMap(checkKey(key), (safe) => Effect.flatMap(guarded((found) => found.getItem(`${prefix}${safe}`)), (text) => (text === null ? Effect.succeed(undefined) : decodeStored(text, schema)))),
+        set: (key, schema, value) => Effect.flatMap(checkKey(key), (safe) => Effect.flatMap(encodeStored(value, schema), (text) => text.length > MAX_STORED ? Effect.fail(new StoreError("Full", "the value is larger than a store holds")) : guarded((found) => found.setItem(`${prefix}${safe}`, text)))),
+        remove: (key) => Effect.flatMap(checkKey(key), (safe) => guarded((found) => found.removeItem(`${prefix}${safe}`))),
+    };
+};
+/** The platform that supplies `store` as the `Store` capability. */
+export const storePlatform = (store) => Nexus.Capability.EnvironmentLive(new Map([[Store.id, { _tag: "Available", implementation: store }]]));

package/dist/targets.d.ts

@@ -0,0 +1,8 @@
+import type { DefinedApp } from "./index.js";
+export type TargetName = "web" | "desktop";
+/** On a definition made by `forTarget`: the definition it was made from, so the toolchain can still see every target's templates. */
+export declare const WHOLE: unique symbol;
+/** The definition as `target` sees it: its own layout in place of the top-level one, its components and overrides added. */
+export declare const forTarget: (author: DefinedApp | undefined, target: TargetName) => DefinedApp | undefined;
+/** Every target the definition has templates for. */
+export declare const targetsOf: (author: DefinedApp | undefined) => ReadonlyArray<TargetName>;

package/dist/targets.js

@@ -0,0 +1,22 @@
+/** On a definition made by `forTarget`: the definition it was made from, so the toolchain can still see every target's templates. */
+export const WHOLE = Symbol.for("valancex.common.whole");
+/** The definition as `target` sees it: its own layout in place of the top-level one, its components and overrides added. */
+export const forTarget = (author, target) => {
+    if (author === undefined) {
+        return undefined;
+    }
+    const parts = author.targets?.[target];
+    if (parts === undefined) {
+        return author;
+    }
+    const layout = parts.layout ?? author.layout;
+    return {
+        ...author,
+        ...{ [WHOLE]: author },
+        ...(layout === undefined ? {} : { layout }),
+        components: [...(author.components ?? []), ...(parts.components ?? [])],
+        override: [...(author.override ?? []), ...(parts.override ?? [])],
+    };
+};
+/** Every target the definition has templates for. */
+export const targetsOf = (author) => Object.keys(author?.targets ?? {});

package/dist/transport.d.ts

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

package/dist/transport.js

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

package/dist/viewport.d.ts

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

package/dist/viewport.js

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

package/dist/vocabulary.d.ts

@@ -0,0 +1,30 @@
+import type { WebPrimitives } from "@valancex/port-web";
+/**
+ * A target's vocabulary has one of two forms. The web's is a table of PORT Web's realizations, from which the manifest is derived (`tags`). Any other target's is a MESH manifest, as data
+ * (`components`): the PORT ships it (the Desktop PORT's `vocabulary.json` and `content.json`), and the build reads it as it is.
+ */
+export interface WebVocabulary {
+    /** The target's id (`web`). */
+    readonly target: string;
+    /** The tags, each with its props and events. */
+    readonly tags: WebPrimitives;
+    /**
+     * The props a template may leave out, by tag. PORT Web's table says how a prop is realized, not whether it is required, so the manifest derived from it makes every prop required but a boolean
+     * one; this is the author-facing rule beside it. An absent prop is not in the render tree, and PORT Web realizes an absent prop as no attribute (or the element's own initial value).
+     */
+    readonly optional?: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+export interface ManifestVocabulary {
+    readonly target: string;
+    /** MESH manifest components: each with its props and events. */
+    readonly components: Readonly<Record<string, unknown>>;
+}
+export type Vocabulary = WebVocabulary | ManifestVocabulary;
+/** The names a template may write as a primitive in this vocabulary. */
+export declare const namesOf: (vocabulary: Vocabulary) => ReadonlyArray<string>;
+/** A vocabulary that is a MESH manifest (or several: their components are merged, and a name may not be in two). */
+export declare const fromManifests: (target: string, ...manifests: ReadonlyArray<{
+    readonly components: Readonly<Record<string, unknown>>;
+}>) => ManifestVocabulary;
+/** The web's vocabulary: HTML elements, with `class`, `theme`, `id` and `aria-*` as styling and accessibility hooks. */
+export declare const webVocabulary: WebVocabulary;

package/dist/vocabulary.js

@@ -0,0 +1,28 @@
+import { primitives } from "./primitives.js";
+/** The names a template may write as a primitive in this vocabulary. */
+export const namesOf = (vocabulary) => Object.keys("tags" in vocabulary ? vocabulary.tags : vocabulary.components);
+/** A vocabulary that is a MESH manifest (or several: their components are merged, and a name may not be in two). */
+export const fromManifests = (target, ...manifests) => {
+    const components = {};
+    for (const manifest of manifests) {
+        for (const [name, each] of Object.entries(manifest.components)) {
+            if (name in components) {
+                throw new Error(`the ${target} vocabulary declares "${name}" twice`);
+            }
+            components[name] = each;
+        }
+    }
+    return { target, components };
+};
+/** The web's vocabulary: HTML elements, with `class`, `theme`, `id` and `aria-*` as styling and accessibility hooks. */
+export const webVocabulary = {
+    target: "web",
+    tags: primitives,
+    optional: {
+        // styling and accessibility hooks are the web's, and a template for both targets does not write them
+        button: ["class", "pressed"],
+        checkbox: ["label"],
+        textfield: ["label", "placeholder"],
+        heading: ["level"],
+    },
+};

package/dist/web-app.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "@valancex/valance/web/plugin";
+import type { AppState, Built } from "./app.js";
+import type { DefinedApp } from "./index.js";
+import type { Content } from "./model.js";
+/** The plugin that makes the application a website: its tags, its URL policy, and its document head. */
+export declare const plugin: (content: Content, built: Built, author?: DefinedApp) => Plugin<AppState>;

package/dist/web-app.js

@@ -0,0 +1,20 @@
+import { titleFor } from "./app.js";
+import { pageAt } from "./scope.js";
+import { primitives } from "./primitives.js";
+import { routes } from "./routes.js";
+/** 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/package.json

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