@valancex/common 0.0.0-stage → 0.12.0

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+/// <reference path="../types/mprx.d.ts" preserve="true" />
+import type * as Valance from "@valancex/valance";
+import { Schema } from "effect";
+import type { Interceptor } from "./transport.js";
+/** The part of the application's state the framework owns: which page is shown. A command's `state` always has it. */
+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;
+}
+/** 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;
+/** A state field: its type and its default, declared together. */
+export interface Field<A = unknown> {
+    readonly [FIELD]: true;
+    readonly schema: Schema.Schema<A, any, never>;
+    readonly initial: A;
+}
+/**
+ * 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 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>>>;
+/** A schema built by hand with a separate initial value: for hydration and for schemas shared with other code. */
+export interface HandBuilt<F extends Schema.Struct.Fields = Schema.Struct.Fields> {
+    readonly schema: Schema.Struct<F>;
+    readonly initial: Schema.Struct.Type<F>;
+}
+export type StateInput = Fields | HandBuilt<any>;
+/** The type of the state a definition declares, beyond the page. */
+export type StateOf<S> = S extends HandBuilt<infer F> ? Schema.Struct.Type<F> : S extends Fields ? {
+    readonly [K in keyof S]: S[K] extends Field<infer A> ? A : never;
+} : {};
+/**
+ * What importing a template file gives you: its address. `P` and `E` are the names of its props and events when the toolchain has generated them (`.valance/templates.d.ts`, included by the
+ * project's `tsconfig.json`); without that, templates are untyped (`string`).
+ */
+export interface Template<P extends string = string, E extends string = string> {
+    readonly mprx: string;
+    readonly "~props"?: P;
+    readonly "~events"?: E;
+}
+export declare const COMPONENT: unique symbol;
+/** One component: a template, and the interface it declares if it declares one. Which components its template uses is read from the template; nothing is written twice. */
+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 events?: Readonly<Record<string, Schema.Schema<any, any, never>>>;
+}
+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).
+     */
+    readonly props?: {
+        readonly [K in P]: Schema.Schema<any, any, never>;
+    };
+    /** 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>;
+    };
+}
+/**
+ * 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 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
+ * together. A target that is not a web page uses the same three parts for its own surfaces (a window title, a navigation bar, a badge). All text: control and direction-override characters are removed
+ * and the length is limited, so a title built from user data cannot reorder or hide what surrounds it.
+ */
+export interface TitleParts {
+    readonly page?: string;
+    readonly app?: string;
+    readonly status?: string;
+}
+export interface AppDefinition<S extends StateInput = {}> {
+    /** 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. */
+    readonly components?: ReadonlyArray<Component>;
+    /** Built-in components (`heading`, `runs`, …) you replace with your own template of the same name. */
+    readonly override?: ReadonlyArray<Component>;
+    /**
+     * Application state beyond the page: `{ theme: field(Schema.Literal("light", "dark"), "light") }`. Its fields become names a layout can read. A hand-built `{ schema, initial }` is also accepted, for
+     * hydration and shared schemas.
+     */
+    readonly state?: S;
+    /**
+     * The document's title for a state: `(state, page) => { status: unread > 0 ? String(unread) : undefined }`. A string is the page part. Absent: the page's title and the site's name. It runs for
+     * every committed state, on the server for the state it renders and in the browser after each one; it should be cheap and must not throw (a throw is logged and the title stays).
+     */
+    readonly title?: (state: PageState & StateOf<S>, page: {
+        readonly path: string;
+        readonly title: string;
+    }) => TitleParts | string;
+    /**
+     * What the application sends to its backend, for every request: `http: { interceptors: [bearer(base, token), refreshOn401(refresh), retryGet(2)] }`, outermost first. Interceptors
+     * (`@valancex/common/http`) all have one shape, `(next) => next`, so they chain; a narrower scope is `withInterceptors(effect, ...)` around a command's work, or `interceptors` on one request.
+     * Used by the page; the server makes no requests.
+     */
+    readonly http?: {
+        readonly interceptors?: ReadonlyArray<Interceptor>;
+    };
+    /** 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>;
+}
+/** 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. */
+export declare const defineApp: <S extends StateInput = {}>(definition: AppDefinition<S>) => DefinedApp;

package/dist/index.js

@@ -0,0 +1,24 @@
+// ---- state -------------------------------------------------------------------------------------------------------------------------------------------------
+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 field = (schema, initial) => ({ [FIELD]: true, schema: schema, initial });
+export const COMPONENT = Symbol.for("valancex.common.component");
+/**
+ * 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 function component(template, contract = {}) {
+    return {
+        [COMPONENT]: true,
+        template,
+        ...(contract.props === undefined ? {} : { props: contract.props }),
+        ...(contract.events === undefined ? {} : { events: contract.events }),
+    };
+}
+/** 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. */
+export const defineApp = (definition) => ({ ...definition, [APP]: true });

package/dist/internal.d.ts

@@ -0,0 +1,7 @@
+export * from "./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";

package/dist/internal.js

@@ -0,0 +1,9 @@
+// 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 "./model.js";
+export * from "./primitives.js";
+export * from "./routes.js";
+export * from "./scope.js";
+export * from "./state.js";
+export * from "./vocabulary.js";

package/dist/model.d.ts

@@ -0,0 +1,72 @@
+/** A run of inline text. `href` is empty unless `kind` is `link`. */
+export interface Span {
+    readonly id: string;
+    readonly kind: "text" | "strong" | "emphasis" | "code" | "link";
+    readonly text: string;
+    readonly href: string;
+}
+export interface Item {
+    readonly id: string;
+    readonly spans: ReadonlyArray<Span>;
+}
+/** What a layout draws a page's body from. Kinds: heading, paragraph, list, code, quote, image. */
+export interface Block {
+    readonly id: string;
+    readonly kind: "heading" | "paragraph" | "list" | "code" | "quote" | "image";
+    /** heading: 1 to 3. */
+    readonly level: number;
+    /** heading: the id on the page. */
+    readonly anchor: string;
+    readonly spans: ReadonlyArray<Span>;
+    /** list: the items. */
+    readonly items: ReadonlyArray<Item>;
+    readonly ordered: boolean;
+    /** code: the language, and the source. */
+    readonly lang: string;
+    readonly text: string;
+    /** image: the address under the site's base, and its description. */
+    readonly src: string;
+    readonly alt: string;
+}
+export interface Heading {
+    readonly id: string;
+    readonly label: string;
+    readonly anchor: string;
+    readonly level: number;
+}
+export interface Page {
+    /** Its path in the site: `/` or `/guide/getting-started`. The identity of the page. */
+    readonly path: string;
+    /** The file it came from, relative to the project. */
+    readonly file: string;
+    readonly title: string;
+    readonly description: string;
+    /** Position among its siblings in navigation. */
+    readonly order: number;
+    /** The navigation group: the page's directory, or empty at the top level. */
+    readonly section: string;
+    readonly blocks: ReadonlyArray<Block>;
+    readonly outline: ReadonlyArray<Heading>;
+}
+export interface SiteInfo {
+    readonly name: string;
+    /** Every address starts with this: `/` or `/something/`. */
+    readonly base: string;
+    /** Where the site is published (no trailing slash), or empty. */
+    readonly url: string;
+    /** How a document's title is written from a page's title and the site's name: `{page}` and `{site}`. */
+    readonly title: string;
+    /** The address the application's backend requests go to (a path on the site's origin, or an absolute https address), or empty when it has none. */
+    readonly api: string;
+    /** Tell assistive technology about a page change made in place (the title, and focus at the content). */
+    readonly announce: boolean;
+}
+/** The title format when the project does not say: the page, then the site. */
+export declare const DEFAULT_TITLE = "{page} \u00B7 {site}";
+export interface Content {
+    readonly site: SiteInfo;
+    /** In navigation order. */
+    readonly pages: ReadonlyArray<Page>;
+    /** `content/404.md` when the author wrote one. */
+    readonly notFound?: Page;
+}

package/dist/model.js

@@ -0,0 +1,4 @@
+// The content model: what the build produces from `content/` and what the application and its layout consume. Plain JSON-able data. A MESH scope is flat, so a block is one record whose
+// unused fields are empty (`kind` says which are meaningful); the empty values are explicit so a template never reads something missing.
+/** The title format when the project does not say: the page, then the site. */
+export const DEFAULT_TITLE = "{page} · {site}";

package/dist/primitives.d.ts

@@ -0,0 +1,2 @@
+import * as Web from "@valancex/valance/web";
+export declare const primitives: Web.WebPrimitives;

package/dist/primitives.js

@@ -0,0 +1,41 @@
+// The tags a layout or component may use, and the element each becomes. This is the vocabulary of the application model: a template says `<nav>`, `<link>`, `<para>`, and this table says
+// what they are on the web. It is also what the MESH manifest is derived from, so a tag that is not here is a compile error that names it.
+//
+// Styling hooks are attributes: `class` for a part with a role of its own, `theme` (the `data-theme` attribute) for a variant, `label` (`aria-label`) and `current` (`aria-current`) where
+// the state is an accessibility fact too. A stylesheet is written against those and the elements.
+import * as Web from "@valancex/valance/web";
+const klass = Web.attribute("class");
+const id = Web.attribute("id");
+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 = {
+    shell: { element: "div", props: { class: klass, theme: Web.attribute("data-theme") } },
+    div: { element: "div", props: { class: klass } },
+    header: { element: "header", props: { class: klass } },
+    footer: { element: "footer", props: { class: klass } },
+    main: { element: "main", props: { id, tabindex: Web.attribute("tabindex") } },
+    nav: { element: "nav", props: { class: klass, label } },
+    aside: { element: "aside", props: { class: klass } },
+    section: { element: "section" },
+    article: { element: "article" },
+    h1: { element: "h1", props: { id } },
+    h2: { element: "h2", props: { id } },
+    h3: { element: "h3", props: { id } },
+    para: { element: "p", props: { class: klass } },
+    quote: { element: "blockquote", props: { class: klass } },
+    list: { element: "ul", props: { class: klass } },
+    olist: { element: "ol", props: { class: klass } },
+    item: { element: "li" },
+    pre: { element: "pre", props: { class: klass, tabindex: Web.attribute("tabindex") } },
+    code: { element: "code" },
+    strong: { element: "strong" },
+    em: { element: "em" },
+    span: { element: "span", props: { class: klass } },
+    image: { element: "img", props: { class: klass, src: Web.attribute("src"), alt: Web.attribute("alt"), loading: Web.attribute("loading") } },
+    /** A link inside text. */
+    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" } } },
+};

package/dist/routes.d.ts

@@ -0,0 +1,9 @@
+import type { RouteTable } from "@valancex/valance/web/plugin";
+import type { Content } from "./model.js";
+export interface PageState {
+    readonly page: string;
+}
+/** 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 declare const normalize: (pathname: string, base: string) => string;
+export declare const urlOf: (content: Content, path: string) => string;
+export declare const routes: (content: Content) => RouteTable<PageState>;

package/dist/routes.js

@@ -0,0 +1,46 @@
+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) => {
+    const inside = pathname === base.replace(/\/$/, "") ? "/" : pathname.startsWith(base) ? `/${pathname.slice(base.length)}` : pathname;
+    const trimmed = inside.replace(/\/+$/, "");
+    return trimmed === "" ? "/" : trimmed;
+};
+export const urlOf = (content, path) => `${content.site.base}${path.replace(/^\//, "")}`;
+export const routes = (content) => ({
+    urlOf: ({ page }) => urlOf(content, page),
+    stateOf: (url) => ({ id: normalize(url.pathname, content.site.base) }),
+    navigate: "go",
+    known: (pathname) => pageAt(content, normalize(pathname, content.site.base)) !== undefined,
+    paths: () => content.pages.map((page) => urlOf(content, page.path)),
+    // 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") {
+            announce();
+            return;
+        }
+        // The application's state has no fragment, so the address bar lost it: put it back.
+        if (url.hash !== "") {
+            window.history.replaceState(window.history.state, "", `${url.pathname}${url.search}${url.hash}`);
+        }
+        const target = url.hash === "" ? undefined : document.getElementById(decodeURIComponent(url.hash.slice(1)));
+        if (target === null || target === undefined) {
+            window.scrollTo(0, 0);
+        }
+        else {
+            target.scrollIntoView();
+        }
+        announce();
+    },
+});

package/dist/scope.d.ts

@@ -0,0 +1,83 @@
+import { Schema } from "effect";
+import type { TitleParts, Viewport } from "./index.js";
+import type { Content, Page } from "./model.js";
+export declare const FrameScope: Schema.Struct<{
+    /** The application's name (`valance.json`). */
+    site: typeof Schema.String;
+    /** The address of the first page, under the base. */
+    home: typeof Schema.String;
+    /** The current page's title, and its description. */
+    title: typeof Schema.String;
+    description: typeof Schema.String;
+    /** False on the page shown for an address that is not a page. */
+    found: typeof Schema.Boolean;
+    /** Pages grouped by directory. A top-level page is in a group with no title. `current` is `"page"` for the page being shown and `"false"` otherwise (the value of `aria-current`). */
+    sections: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        title: typeof Schema.String;
+        items: Schema.Array$<Schema.Struct<{
+            id: typeof Schema.String;
+            href: typeof Schema.String;
+            label: typeof Schema.String;
+            current: typeof Schema.String;
+        }>>;
+    }>>;
+    /** The `##` and `###` headings of the current page; `hasToc` is false when there are none. */
+    hasToc: typeof Schema.Boolean;
+    toc: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        href: typeof Schema.String;
+        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 page's body. Draw it with `<blocks items={blocks} />`, or draw each block yourself. */
+    blocks: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        kind: typeof Schema.String;
+        level: typeof Schema.Number;
+        anchor: typeof Schema.String;
+        spans: Schema.Array$<Schema.Struct<{
+            id: typeof Schema.String;
+            kind: typeof Schema.String;
+            text: typeof Schema.String;
+            href: typeof Schema.String;
+        }>>;
+        items: Schema.Array$<Schema.Struct<{
+            id: typeof Schema.String;
+            spans: Schema.Array$<Schema.Struct<{
+                id: typeof Schema.String;
+                kind: typeof Schema.String;
+                text: typeof Schema.String;
+                href: typeof Schema.String;
+            }>>;
+        }>>;
+        ordered: typeof Schema.Boolean;
+        lang: typeof Schema.String;
+        text: typeof Schema.String;
+        src: typeof Schema.String;
+        alt: typeof Schema.String;
+    }>>;
+    /** Neighbours in navigation order; `href` is empty when there is none. */
+    prev: Schema.Struct<{
+        href: typeof Schema.String;
+        label: typeof Schema.String;
+    }>;
+    next: Schema.Struct<{
+        href: typeof Schema.String;
+        label: typeof Schema.String;
+    }>;
+}>;
+/** The names a layout may read from the framework; an application's own state may not reuse them. */
+export declare const RESERVED: ReadonlyArray<string>;
+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: 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) => typeof FrameScope.Type;

package/dist/scope.js

@@ -0,0 +1,134 @@
+// What a layout reads. A MESH scope is flat and typed, so this is the one place that says what exists; `frame` fills it from the content and the current page. The author's own state fields
+// are added to it by name (see ./app.ts), so a layout reads `theme` if the application's state has a `theme`.
+import { Schema } from "effect";
+const SpanView = Schema.Struct({ id: Schema.String, kind: Schema.String, text: Schema.String, href: Schema.String });
+const ItemView = Schema.Struct({ id: Schema.String, spans: Schema.Array(SpanView) });
+const BlockView = Schema.Struct({
+    id: Schema.String,
+    kind: Schema.String,
+    level: Schema.Number,
+    anchor: Schema.String,
+    spans: Schema.Array(SpanView),
+    items: Schema.Array(ItemView),
+    ordered: Schema.Boolean,
+    lang: Schema.String,
+    text: Schema.String,
+    src: Schema.String,
+    alt: Schema.String,
+});
+const Ref = Schema.Struct({ href: Schema.String, label: Schema.String });
+export const FrameScope = Schema.Struct({
+    /** The application's name (`valance.json`). */
+    site: Schema.String,
+    /** The address of the first page, under the base. */
+    home: Schema.String,
+    /** The current page's title, and its description. */
+    title: Schema.String,
+    description: Schema.String,
+    /** False on the page shown for an address that is not a page. */
+    found: Schema.Boolean,
+    /** Pages grouped by directory. A top-level page is in a group with no title. `current` is `"page"` for the page being shown and `"false"` otherwise (the value of `aria-current`). */
+    sections: Schema.Array(Schema.Struct({
+        id: Schema.String,
+        title: Schema.String,
+        items: Schema.Array(Schema.Struct({ id: Schema.String, href: Schema.String, label: Schema.String, current: Schema.String })),
+    })),
+    /** 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 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. */
+    prev: Ref,
+    next: Ref,
+});
+/** The names a layout may read from the framework; an application's own state may not reuse them. */
+export const RESERVED = Object.keys(FrameScope.fields);
+const NONE = { href: "", label: "" };
+const view = (blocks) => blocks;
+const withBase = (base, path) => `${base}${path.replace(/^\//, "")}`;
+export const sectionLabel = (dir) => dir.replace(/[-_]+/g, " ").replace(/^./, (first) => first.toUpperCase());
+/** The page shown for an address that is not a page: `content/404.md` if the author wrote one. */
+export const notFoundPage = (content) => content.notFound ?? {
+    path: "/404",
+    file: "",
+    title: "Page not found",
+    description: "",
+    order: 0,
+    section: "",
+    outline: [],
+    blocks: [
+        {
+            id: "b0",
+            kind: "heading",
+            level: 1,
+            anchor: "page-not-found",
+            spans: [{ id: "b0.0", kind: "text", text: "Page not found", href: "" }],
+            items: [],
+            ordered: false,
+            lang: "",
+            text: "",
+            src: "",
+            alt: "",
+        },
+        {
+            id: "b1",
+            kind: "paragraph",
+            level: 0,
+            anchor: "",
+            spans: [
+                { id: "b1.0", kind: "text", text: "There is no page at this address.", href: "" },
+                { id: "b1.1", kind: "text", text: " ", href: "" },
+                { id: "b1.2", kind: "link", text: "Go to the start.", href: withBase(content.site.base, "/") },
+            ],
+            items: [],
+            ordered: false,
+            lang: "",
+            text: "",
+            src: "",
+            alt: "",
+        },
+    ],
+};
+export const pageAt = (content, path) => content.pages.find((page) => page.path === 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") => {
+    const page = pageAt(content, path);
+    const shown = page ?? notFoundPage(content);
+    const at = page === undefined ? -1 : content.pages.indexOf(page);
+    const ref = (to) => (to === undefined ? NONE : { href: withBase(content.site.base, to.path), label: to.title });
+    const groups = [];
+    for (const each of content.pages) {
+        let group = groups.find((candidate) => candidate.id === each.section);
+        if (group === undefined) {
+            group = { id: each.section, title: each.section === "" ? "" : sectionLabel(each.section), items: [] };
+            groups.push(group);
+        }
+        group.items.push({ id: each.path, href: withBase(content.site.base, each.path), label: each.title, current: each.path === path ? "page" : "false" });
+    }
+    return {
+        site: content.site.name,
+        viewport,
+        home: withBase(content.site.base, "/"),
+        title: shown.title,
+        description: shown.description,
+        found: page !== undefined,
+        sections: groups,
+        hasToc: shown.outline.length > 0,
+        toc: shown.outline.map((heading) => ({ id: heading.id, href: `#${heading.anchor}`, label: heading.label, level: heading.level })),
+        blocks: view(shown.blocks),
+        prev: ref(content.pages[at - 1]),
+        next: ref(at < 0 ? undefined : content.pages[at + 1]),
+    };
+};

package/dist/server.d.ts

@@ -0,0 +1,20 @@
+import type * as Valance from "@valancex/valance";
+import type { Built } from "./app.js";
+import type { DefinedApp } from "./index.js";
+import type { Content } from "./model.js";
+import { routes } from "./routes.js";
+export type { Built };
+export { routes };
+export interface ServerParts {
+    readonly content: Content;
+    readonly program: Valance.Program;
+    readonly author?: DefinedApp | undefined;
+}
+export interface Rendered {
+    /** 200 for a page, 404 for an address that is not one (rendered as the not-found page). */
+    readonly status: number;
+    readonly html: string;
+}
+export declare const createRenderer: ({ content, program, author }: ServerParts) => (pathname: string, built: Built) => Promise<Rendered>;
+/** The pathnames a static export writes, under the base. */
+export declare const pathsOf: (content: Content) => ReadonlyArray<string>;

package/dist/server.js

@@ -0,0 +1,22 @@
+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 { routes } from "./routes.js";
+export { routes };
+const safe = (json) => json.replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+export const createRenderer = ({ content, program, author }) => {
+    const app = application(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, author)], state }));
+        const boot = safe(JSON.stringify({ state: served.state, built }));
+        return {
+            status: table.known(pathname) ? 200 : 404,
+            html: `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${renderHead(served.head)}</head><body><div id="app">${served.html}</div><script id="valance-boot" type="application/json">${boot}</script><script type="module" src="${built.script}"></script></body></html>`,
+        };
+    };
+};
+/** The pathnames a static export writes, under the base. */
+export const pathsOf = (content) => routes(content).paths();

package/dist/state.d.ts

@@ -0,0 +1,13 @@
+import { Schema } from "effect";
+import type { DefinedApp } from "./index.js";
+export interface State {
+    /** The struct of the state's fields. */
+    readonly schema: Schema.Struct<Schema.Struct.Fields>;
+    readonly initial: Readonly<Record<string, unknown>>;
+    /** Whether it was declared field by field (so each default can be checked against its own type). */
+    readonly declared: boolean;
+}
+/** The state a definition declares, or `undefined` for none. */
+export declare const stateOf: (author: DefinedApp | undefined) => State | undefined;
+/** The fields whose default is not a value of the field's own type (only for a state declared field by field). */
+export declare const badDefaults: (author: DefinedApp | undefined) => ReadonlyArray<string>;