@valancex/common 0.12.0 → 0.13.0

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/internal.d.ts

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

package/dist/internal.js

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

package/dist/navigation.d.ts

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

package/dist/navigation.js

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

package/dist/open-system.d.ts

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

package/dist/open-system.js

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

package/dist/open.d.ts

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

package/dist/open.js

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

package/dist/platform.d.ts

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

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/scope.d.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import type { TitleParts, Viewport } from "./index.js";
+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`). */
@@ -32,6 +32,12 @@ export declare const FrameScope: Schema.Struct<{
     }>>;
     /** 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;
@@ -80,4 +86,7 @@ export declare const pageAt: (content: Content, path: string) => Page | undefine
  * (the home page, usually) is that name alone. The author's `title` function may replace the parts; the caller cleans the result (control and direction-override characters out, length limited).
  */
 export declare const documentTitle: (content: Content, page: Page | undefined, parts?: TitleParts) => string;
-export declare const frame: (content: Content, path: string, viewport?: Viewport) => typeof FrameScope.Type;
+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

@@ -38,6 +38,12 @@ export const FrameScope = Schema.Struct({
     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. */
@@ -103,7 +109,7 @@ export const documentTitle = (content, page, parts = {}) => {
     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") => {
+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);
@@ -120,6 +126,9 @@ export const frame = (content, path, viewport = "expanded") => {
     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");

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 ?? {});