@valancex/common 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -7,10 +7,22 @@ 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;
+/** The brand of a state field that holds a form (`Form.field()`): the application then takes the person to the first field in error after a failed submit, with nothing written. */
+export declare const FORM: unique symbol;
 /** A state field: its type and its default, declared together. */
 export interface Field<A = unknown> {
     readonly [FIELD]: true;
@@ -21,6 +33,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>>>;
@@ -49,27 +70,105 @@ export interface Component {
     readonly [COMPONENT]: true;
     readonly template: Template;
     /** Present when the component declares its props (an omitted side of a declared interface is none). Absent: the contract is inferred from the template and its uses. */
-    readonly props?: Readonly<Record<string, Schema.Schema<any, any, never>>>;
+    readonly props?: Readonly<Record<string, PropDeclaration>>;
     readonly events?: Readonly<Record<string, Schema.Schema<any, any, never>>>;
+    /** The prop that is the component's accessible name, when its template passes the name of whoever uses it through to a control (see `Contract.name`). */
+    readonly name?: string;
+    /** The state and commands of one occurrence of the component, when it has any (see `unit`). */
+    readonly unit?: Valance.Unit;
 }
+export declare const SNIPPET: unique symbol;
+/** A prop that is a piece of template: what an occurrence writes between its tags (`children`), or as a `{#snippet}` of that name among them. */
+export interface SnippetDeclaration {
+    readonly [SNIPPET]: true;
+    /** The types of the snippet's parameters, in order; `{@render name(a, b)}` passes exactly these. */
+    readonly params: ReadonlyArray<Schema.Schema<any, any, never>>;
+    /** Whether an occurrence may leave it out. Rendering it then needs `{#if has(name)}` around the render (`possibly-absent-snippet`). */
+    readonly isOptional: boolean;
+    /** The same snippet, which an occurrence may leave out: `snippet(Item).optional()`. */
+    optional(): SnippetDeclaration;
+}
+/**
+ * Declares a prop whose value is a snippet, with the types of its parameters: `children: snippet()` is the content written between the component's tags; `row: snippet(Item, Schema.Number)` is a
+ * `{#snippet row(item, index)}` an occurrence passes and the template renders with `{@render row(item, index)}`. The prop named `children` is reserved for the content between the tags and takes no
+ * parameters. A snippet is not data: it has no default, is not a field of a record or an event's payload, and is declared on a component that has a template. `snippet(...).optional()` is one an occurrence may leave out (an absent one draws nothing), and `children: snippet().optional()` is content an occurrence may leave out.
+ */
+export declare const snippet: (...params: ReadonlyArray<Schema.Schema<any, any, never>>) => SnippetDeclaration;
+/** Whether a declaration is a snippet's. */
+export declare const isSnippet: (value: unknown) => value is SnippetDeclaration;
+/** A prop is declared by its schema, by `field(schema, default)` when an occurrence that leaves it out should get a value, or by `snippet(…)` when it is a piece of template. */
+export type PropDeclaration = Schema.Schema<any, any, never> | Field<any> | SnippetDeclaration;
+/** Whether a prop is declared with a default. */
+export declare const isFormField: (value: unknown) => boolean;
+export declare const isField: (value: unknown) => value is Field;
 export interface Contract<P extends string, E extends string> {
     /**
-     * The inputs the template reads, each with its type. Optional when the schema admits `undefined`. A prop has no default: the model has none. With neither `props` nor `events` the contract is
-     * inferred; with either, the interface is exactly what is written (an omitted side is none).
+     * The inputs the template reads, each with its type. Optional when the schema admits `undefined`. `field(schema, default)` gives a prop a default: an occurrence of the component that leaves
+     * the prop out gets the default (for a component with a template; a primitive ignores it), and the prop may then be left out. A string-literal union (`Schema.Literal("a", "b")`) is a closed set:
+     * the model checks every literal written for it. With neither `props` nor `events` the contract is inferred; with either, the interface is exactly what is written (an omitted side is none).
      */
     readonly props?: {
-        readonly [K in P]: Schema.Schema<any, any, never>;
+        readonly [K in P]: PropDeclaration;
     };
     /** The events the template raises, each with its payload's schema; `Schema.Void` is no payload. */
     readonly events?: {
         readonly [K in E]: Schema.Schema<any, any, never>;
     };
+    /**
+     * The prop that is the component's accessible name: a component whose template draws a control and takes its name from whoever uses it (a labelled checkbox of the design system) says which
+     * prop that is, and the toolchain holds both sides to it. The prop must be a string every use writes (the model reports a use that omits it, where it is written), and the template must read it;
+     * a control in the template that has no name of its own (no `label`, not inside a `<label>`) is then not reported by `unnamed-control`, because the name arrives from the use.
+     */
+    readonly name?: P;
+    /**
+     * State that belongs to one occurrence of the component, such as whether a disclosure is open or which tab is chosen: `unit({ state, commands })`. The template reads its fields and runs its commands
+     * by name, like any others; the application never sees them. A component with a unit states its interface (`props` and `events`, empty if it has none).
+     */
+    readonly unit?: Valance.Unit;
 }
 /**
  * Defines a component: its template and an optional contract. Register it once, in `defineApp`'s `components`; the templates that write its tag use it, and nothing about its interface is
  * written again there. Where the toolchain has generated the template's type, a contract that disagrees with the template's keys is a compile-time error.
  */
 export declare function component<P extends string = string, E extends string = string>(template: Template<P, E>, contract?: Contract<NoInfer<P>, NoInfer<E>>): Component;
+/** What a unit's commands change: some of its fields. */
+type Changes<S> = Partial<S>;
+/** One command of a unit: a function of the state as the person saw it that returns the fields it changes, or the same with parameters and the events it announces. */
+export type UnitCommandSpec<S, P extends Schema.Struct.Fields = Schema.Struct.Fields> = ((state: S) => Changes<S>) | {
+    /** The command's parameters, in order: `{ n: Schema.Number }`. Each is a parameter of the command in the model. */
+    readonly params?: P;
+    readonly run: (state: S, args: Schema.Struct.Type<P>) => Changes<S>;
+    /** Events of the component the command announces to its caller, each with the payload it carries, worked out from the state the command leaves: `{ change: (next) => next.at }`. */
+    readonly raises?: Readonly<Record<string, (next: S, args: Schema.Struct.Type<P>) => unknown>>;
+};
+/** A command with parameters, typed: the parameters' types reach `run` and `raises`. */
+export declare const unitCommand: <S, P extends Schema.Struct.Fields>(spec: {
+    readonly params: P;
+    readonly run: (state: S, args: Schema.Struct.Type<P>) => Changes<S>;
+    readonly raises?: Readonly<Record<string, (next: S, args: Schema.Struct.Type<P>) => unknown>>;
+}) => UnitCommandSpec<S, P>;
+/**
+ * Declares the state and commands of one occurrence of a component (Tier 2; a component with no unit needs none of it). The state is typed with defaults, as application state is; a command is a
+ * pure function of the state as the person saw it that returns the fields it changes:
+ *
+ *   export default component(template, {
+ *     props: { label: Schema.String },
+ *     events: {},
+ *     unit: unit({ state: { open: field(Schema.Boolean, false) }, commands: { toggle: (state) => ({ open: !state.open }) } }),
+ *   });
+ *
+ * The template reads `open` and runs `toggle()`; the application holds neither. The state belongs to the occurrence: it follows its row when a keyed list is re-sorted, and starts again from the defaults
+ * when the occurrence leaves the page and returns. State that must outlive that (or that another part of the application reads) is application state, not a unit. A field named in `controllable` is
+ * owned by the caller when it writes a prop of the same name (the prop must be declared, optional and of the same type): the prop is then the value, the unit's change to it is not applied, and
+ * `raises` tells the caller what the person chose.
+ */
+export declare const unit: <F extends Fields>(definition: {
+    readonly state: F;
+    readonly commands: {
+        readonly [name: string]: UnitCommandSpec<StateOf<F>, any>;
+    };
+    readonly controllable?: ReadonlyArray<Extract<keyof F, string>>;
+}) => Valance.Unit<StateOf<F>>;
 /**
  * What the document's title is made of. `page` is the page's own part (default: its title, from the Markdown front matter), `app` the application's name (default: the site's name), `status` what is
  * going on right now and is not part of any page (an unread count, "Saving…"): it is written first, in parentheses. The project's format in \`valance.json\` (`"title": "{page} · {site}"`) puts them
@@ -81,7 +180,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 +223,62 @@ 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;
+export * as Form from "./form.js";

package/dist/index.js

@@ -1,11 +1,35 @@
+import { UNIT } from "@valancex/valance";
+import { Schema } from "effect";
 // ---- state -------------------------------------------------------------------------------------------------------------------------------------------------
 export const FIELD = Symbol.for("valancex.common.field");
+/** The brand of a state field that holds a form (`Form.field()`): the application then takes the person to the first field in error after a failed submit, with nothing written. */
+export const FORM = Symbol.for("valancex.common.form");
 /**
  * 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");
+export const SNIPPET = Symbol.for("valancex.common.snippet");
+/**
+ * Declares a prop whose value is a snippet, with the types of its parameters: `children: snippet()` is the content written between the component's tags; `row: snippet(Item, Schema.Number)` is a
+ * `{#snippet row(item, index)}` an occurrence passes and the template renders with `{@render row(item, index)}`. The prop named `children` is reserved for the content between the tags and takes no
+ * parameters. A snippet is not data: it has no default, is not a field of a record or an event's payload, and is declared on a component that has a template. `snippet(...).optional()` is one an occurrence may leave out (an absent one draws nothing), and `children: snippet().optional()` is content an occurrence may leave out.
+ */
+export const snippet = (...params) => declare(params, false);
+const declare = (params, isOptional) => ({
+    [SNIPPET]: true,
+    params,
+    isOptional,
+    optional: () => declare(params, true),
+});
+/** Whether a declaration is a snippet's. */
+export const isSnippet = (value) => typeof value === "object" && value !== null && SNIPPET in value;
+/** Whether a prop is declared with a default. */
+export const isFormField = (value) => typeof value === "object" && value !== null && FORM in value;
+export const isField = (value) => typeof value === "object" && value !== null && FIELD in value;
 /**
  * Defines a component: its template and an optional contract. Register it once, in `defineApp`'s `components`; the templates that write its tag use it, and nothing about its interface is
  * written again there. Where the toolchain has generated the template's type, a contract that disagrees with the template's keys is a compile-time error.
@@ -16,9 +40,53 @@ export function component(template, contract = {}) {
         template,
         ...(contract.props === undefined ? {} : { props: contract.props }),
         ...(contract.events === undefined ? {} : { events: contract.events }),
+        ...(contract.name === undefined ? {} : { name: contract.name }),
+        ...(contract.unit === undefined ? {} : { unit: contract.unit }),
     };
 }
+/** A command with parameters, typed: the parameters' types reach `run` and `raises`. */
+export const unitCommand = (spec) => spec;
+/**
+ * Declares the state and commands of one occurrence of a component (Tier 2; a component with no unit needs none of it). The state is typed with defaults, as application state is; a command is a
+ * pure function of the state as the person saw it that returns the fields it changes:
+ *
+ *   export default component(template, {
+ *     props: { label: Schema.String },
+ *     events: {},
+ *     unit: unit({ state: { open: field(Schema.Boolean, false) }, commands: { toggle: (state) => ({ open: !state.open }) } }),
+ *   });
+ *
+ * The template reads `open` and runs `toggle()`; the application holds neither. The state belongs to the occurrence: it follows its row when a keyed list is re-sorted, and starts again from the defaults
+ * when the occurrence leaves the page and returns. State that must outlive that (or that another part of the application reads) is application state, not a unit. A field named in `controllable` is
+ * owned by the caller when it writes a prop of the same name (the prop must be declared, optional and of the same type): the prop is then the value, the unit's change to it is not applied, and
+ * `raises` tells the caller what the person chose.
+ */
+export const unit = (definition) => {
+    const entries = Object.entries(definition.state);
+    const fields = Object.fromEntries(entries.map(([name, each]) => [name, { schema: each.schema, initial: each.initial }]));
+    const schema = Schema.Struct(Object.fromEntries(entries.map(([name, each]) => [name, each.schema])));
+    return {
+        [UNIT]: true,
+        schema: schema,
+        fields,
+        controllable: definition.controllable ?? [],
+        commands: Object.fromEntries(Object.entries(definition.commands).map(([name, command]) => [
+            name,
+            typeof command === "function"
+                ? { run: command }
+                : {
+                    ...(command.params === undefined ? {} : { input: Schema.Struct(command.params) }),
+                    run: command.run,
+                    ...(command.raises === undefined ? {} : { raises: command.raises }),
+                },
+        ])),
+    };
+};
 /** 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 });
+// ---- forms ---------------------------------------------------------------------------------------------------------------------------------------------------
+export * as Form from "./form.js";

package/dist/internal.d.ts

@@ -1,7 +1,14 @@
 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";
+export { earlyHead, earlyShell, earlyShellLimit } from "./early.js";

package/dist/internal.js

@@ -1,9 +1,16 @@
 // 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";
+export { earlyHead, earlyShell, earlyShellLimit } from "./early.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.d.ts

@@ -1,2 +1,23 @@
 import * as Web from "@valancex/valance/web";
 export declare const primitives: Web.WebPrimitives;
+/** What each tag's props and events are, as the specification states them (the derivation from the table alone cannot say whether a prop is required, nor type one realized as text). */
+export declare const declared: Readonly<Record<string, {
+    readonly props: Readonly<Record<string, {
+        readonly type: Readonly<Record<string, unknown>>;
+        readonly required: boolean;
+    }>>;
+    readonly events: Readonly<Record<string, {
+        readonly payload?: Readonly<Record<string, unknown>>;
+    }>>;
+}>>;
+/** The tags that were renamed (decision P7), old to new: a template that writes the old one is told the new. */
+export declare const renamed: Readonly<Record<string, string>>;
+/** The props that were renamed (decision I29), by tag, old to new: a template that writes the old one is told the new. */
+export declare const renamedProps: Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** What a use of a tag must satisfy besides its props (`vlx` checks it): the tags that need a name (a `label` prop, or a `label` around them), the tags a tag may contain only, and the tags a tag must be inside. */
+export declare const rules: {
+    readonly named: ReadonlyArray<string>;
+    readonly modal: ReadonlyArray<string>;
+    readonly only: Readonly<Record<string, ReadonlyArray<string>>>;
+    readonly within: Readonly<Record<string, ReadonlyArray<string>>>;
+};