@valancex/common 0.0.0-stage → 0.11.0

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @valancex/common
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What an application's `src/main.ts` imports (`defineApp`, `component`, `field`), and the runtime a built application runs. It describes the application; the [`vlx` command](../cli) builds, serves and checks what it describes.
+
+```console
+$ vlx init my-app --web      # a project that already depends on this package
+```
+
+```ts
+// src/main.ts
+import { component, defineApp, field } from "@valancex/common";
+import { Schema } from "effect";
+import layout from "./layout.mprx";
+import themeToggle from "./theme-toggle.js";
+
+export default defineApp({
+  layout: component(layout),
+  components: [themeToggle],
+  state: { theme: field(Schema.Literal("light", "dark"), "light") },
+  commands: (command) => ({
+    toggleTheme: command((state) => ({ ...state, theme: state.theme === "light" ? "dark" : "light" })),
+  }),
+});
+```
+
+| Export | Is |
+|---|---|
+| `defineApp({ layout?, components?, override?, state?, commands? })` | The application: its shell, its components, its state and the commands that change it. It starts nothing. |
+| `component(template, { props?, events? })` | A component: a `.mprx` template and, optionally, the interface it states (Effect Schemas). Which components its template uses is read from the template. |
+| `field(schema, initial)` | One field of the state: its type and its default, together. |
+
+`Schema` is [Effect's](https://effect.website/docs/schema/introduction/); import it from `effect`. This package types against it and does not re-export it.
+
+| Entry | Is |
+|---|---|
+| `@valancex/common` | The three exports above. No Node, bundler or terminal import: `src/main.ts` is loaded in the browser as well as at build time. |
+| `@valancex/common/client`, `/server` | The browser and server halves of a built application: `start` takes over the server's HTML, `createRenderer` turns a path into a document. The files `vlx` generates import these; you do not. |
+| `@valancex/common/internal` | What the build tools share with the runtime (content model, tag table, the scope a layout reads). For `@valancex/cli`, not for applications. |
+
+A built or deployed application depends on this package and `effect`; `@valancex/cli` is only needed to develop it. This package depends on `@valancex/valance`, `@valancex/mesh-runtime` and `@valancex/port-web`.
+
+Documentation: [`@valancex/cli`](../cli/README.md) (the project layout, components, state and commands).
+
+Pre-1.0: the API may change between minor releases; every change is in the [release notes](../../docs/releases/).

package/dist/app.d.ts

@@ -0,0 +1,35 @@
+import * as Valance from "@valancex/valance";
+import type { Plugin } from "@valancex/valance/web/plugin";
+import { Schema } from "effect";
+import type { DefinedApp, PageState } from "./index.js";
+import type { Content } from "./model.js";
+export type AppState = PageState & Record<string, unknown>;
+/** What the browser needs to know about the built page to keep the document's head in step. */
+export interface Built {
+    /** The address of the page script. */
+    readonly script: string;
+    /** Stylesheet addresses, in order. Empty in development, where the script brings its styles. */
+    readonly styles: ReadonlyArray<string>;
+}
+/** A mistake in `src/main.ts`, reported with what to change. */
+export declare class AppDefinitionError extends Error {
+    constructor(message: string);
+}
+/** Checks the author's definition against the names the framework owns. */
+export declare const checkDefinition: (author: DefinedApp | undefined) => void;
+/** The names `src/main.ts` adds: state fields (readable in the layout) and commands (runnable from it). */
+export declare const ownNames: (author: DefinedApp | undefined) => {
+    readonly state: ReadonlyArray<string>;
+    readonly commands: ReadonlyArray<string>;
+};
+/** The scope schema a layout is compiled against: the framework's names and the author's state fields. */
+export declare const scopeSchema: (author: DefinedApp | undefined) => Schema.Schema<any, any, never>;
+export declare const stateSchema: (author: DefinedApp | undefined) => Schema.Schema<any, any, never>;
+/** The command table: the framework's `go`, then the author's. */
+export declare const commandTable: (author: DefinedApp | undefined) => (state: Parameters<typeof Valance.command>[0]) => Valance.CommandTable<any, Valance.Ambient>;
+export declare const initialState: (author: DefinedApp | undefined) => AppState;
+export declare const application: (content: Content, program: Valance.Program, author?: DefinedApp) => Valance.ApplicationDefinition<AppState, any, Valance.Ambient, "layout">;
+/** The state a request for `pathname` starts from. */
+export declare const stateFor: (content: Content, pathname: string, author?: DefinedApp) => AppState;
+/** The plugin that makes the application a website: its tags, its URL policy, and its document head. */
+export declare const plugin: (content: Content, built: Built) => Plugin<AppState>;

package/dist/app.js

@@ -0,0 +1,96 @@
+// The application the framework assembles from the three things an author supplies: the content (built from `content/`), the program (built from the templates), and optionally
+// `defineApp`'s state and commands. This is one Valance application (`Valance.define`): the page is its state, going to a page is its `go` command, and the layout is its one view.
+// The server renders it and the browser runs it, from the same function.
+import * as Valance from "@valancex/valance";
+import { Schema } from "effect";
+import { documentTitle, frame, FrameScope, pageAt, RESERVED } from "./scope.js";
+import { primitives } from "./primitives.js";
+import { normalize, routes } from "./routes.js";
+import { badDefaults, stateOf } from "./state.js";
+const PageSchema = Schema.Struct({ page: Schema.String });
+/** A mistake in `src/main.ts`, reported with what to change. */
+export class AppDefinitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AppDefinitionError";
+    }
+}
+const authorFields = (author) => Object.keys(stateOf(author)?.schema.fields ?? {});
+/** Checks the author's definition against the names the framework owns. */
+export const checkDefinition = (author) => {
+    for (const name of authorFields(author)) {
+        if (RESERVED.includes(name)) {
+            throw new AppDefinitionError(`src/main.ts: the state field "${name}" is a name the layout already reads from the framework (${RESERVED.join(", ")}); choose another`);
+        }
+        if (name === "page") {
+            throw new AppDefinitionError('src/main.ts: the state field "page" is the framework\'s (which page is shown); choose another');
+        }
+    }
+    for (const name of badDefaults(author)) {
+        throw new AppDefinitionError(`src/main.ts: the default of the state field "${name}" is not a value of its type`);
+    }
+    // Building the table reads no state (a command reads it when it runs), so it can be built here, with nothing, to see its names.
+    if ("go" in (author?.commands?.(Valance.command({})) ?? {})) {
+        throw new AppDefinitionError('src/main.ts: "go" is the framework\'s command (it shows a page); choose another name');
+    }
+};
+/** The names `src/main.ts` adds: state fields (readable in the layout) and commands (runnable from it). */
+export const ownNames = (author) => ({
+    state: authorFields(author),
+    commands: Object.keys(author?.commands?.(Valance.command({})) ?? {}),
+});
+/** The scope schema a layout is compiled against: the framework's names and the author's state fields. */
+export const scopeSchema = (author) => {
+    const state = stateOf(author);
+    return state === undefined ? FrameScope : Schema.extend(FrameScope, state.schema);
+};
+export const stateSchema = (author) => {
+    const state = stateOf(author);
+    return state === undefined ? PageSchema : Schema.extend(PageSchema, state.schema);
+};
+/** The command table: the framework's `go`, then the author's. */
+export const commandTable = (author) => (state) => {
+    const command = Valance.command(state);
+    const own = author?.commands?.(command) ?? {};
+    if ("go" in own) {
+        throw new AppDefinitionError('src/main.ts: "go" is the framework\'s command (it shows a page); choose another name');
+    }
+    return { go: command(Schema.Struct({ id: Schema.String }), ({ id }, current) => ({ ...current, page: id })), ...own };
+};
+export const initialState = (author) => ({ page: "/", ...stateOf(author)?.initial });
+export const application = (content, program, author) => {
+    checkDefinition(author);
+    return Valance.define({
+        name: content.site.name,
+        state: { schema: stateSchema(author), initial: initialState(author) },
+        views: {
+            layout: {
+                program,
+                scope: (state) => {
+                    const { page, ...own } = state;
+                    return { ...frame(content, page), ...own };
+                },
+            },
+        },
+        view: () => "layout",
+        commands: commandTable(author),
+    });
+};
+/** The state a request for `pathname` starts from. */
+export const stateFor = (content, pathname, author) => ({ ...initialState(author), page: normalize(pathname, content.site.base) });
+/** The plugin that makes the application a website: its tags, its URL policy, and its document head. */
+export const plugin = (content, built) => ({
+    name: "valance-app",
+    primitives,
+    routes: routes(content),
+    head: (state) => {
+        const page = pageAt(content, state.page);
+        const shown = page ?? { description: "" };
+        const canonical = content.site.url === "" || page === undefined ? [] : [{ rel: "canonical", href: `${content.site.url}${content.site.base}${page.path.replace(/^\//, "")}` }];
+        return {
+            title: documentTitle(content, page),
+            meta: shown.description === "" ? [] : [{ name: "description", content: shown.description }],
+            links: [...built.styles.map((href) => ({ rel: "stylesheet", href })), ...canonical],
+        };
+    },
+});

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+import type * as Valance from "@valancex/valance";
+import type { DefinedApp } from "./index.js";
+import type { Content } from "./model.js";
+export interface ClientParts {
+    readonly content: Content;
+    readonly program: Valance.Program;
+    readonly author?: DefinedApp | undefined;
+}
+export declare const start: ({ content, program, author }: ClientParts) => Promise<void>;

package/dist/client.js

@@ -0,0 +1,29 @@
+// The browser half, for the generated entry (`.valance/client.ts`): start the MESH runtime and run the application, taking over the HTML the server wrote. An author never imports this.
+import { init } from "@valancex/mesh-runtime";
+import wasmUrl from "@valancex/mesh-runtime/mesh-runtime.wasm?url";
+import * as Web from "@valancex/valance/web";
+import { application, plugin } from "./app.js";
+export const start = async ({ content, program, author }) => {
+    const container = document.getElementById("app");
+    try {
+        const boot = JSON.parse(document.getElementById("valance-boot").textContent);
+        await init(wasmUrl);
+        const host = await Web.run(application(content, program, author), {
+            container,
+            present: "hydrate",
+            state: boot.state,
+            plugins: [plugin(content, boot.built)],
+            shutdown: { grace: "250 millis" },
+        });
+        container.dataset["valance"] = "running"; // readiness marker for whoever drives the page
+        addEventListener("pagehide", (event) => {
+            if (!event.persisted) {
+                void host.stop();
+            }
+        });
+    }
+    catch (error) {
+        container.dataset["valance"] = "failed";
+        console.error("the application did not start", error); // the server's HTML stays as drawn
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/// <reference path="../types/mprx.d.ts" preserve="true" />
+import type * as Valance from "@valancex/valance";
+import { Schema } from "effect";
+/** 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;
+}
+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;
+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 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,6 @@
+export * from "./app.js";
+export * from "./model.js";
+export * from "./primitives.js";
+export * from "./routes.js";
+export * from "./scope.js";
+export * from "./state.js";

package/dist/internal.js

@@ -0,0 +1,8 @@
+// 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";

package/dist/model.d.ts

@@ -0,0 +1,64 @@
+/** 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;
+}
+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,3 @@
+// 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.
+export {};

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,34 @@
+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 }) => {
+        // Land at the top of a new page, or at its heading when the address names one; Back and Forward are the browser's to restore.
+        if (kind !== "link" || typeof window === "undefined") {
+            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();
+        }
+    },
+});

package/dist/scope.d.ts

@@ -0,0 +1,77 @@
+import { Schema } from "effect";
+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;
+    }>>;
+    /** 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. */
+export declare const documentTitle: (content: Content, page: Page | undefined) => string;
+export declare const frame: (content: Content, path: string) => typeof FrameScope.Type;

package/dist/scope.js

@@ -0,0 +1,129 @@
+// 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 })),
+    /** 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. */
+export const documentTitle = (content, page) => page === undefined
+    ? `${notFoundPage(content).title} · ${content.site.name}`
+    : page.path === "/"
+        ? page.title === content.site.name
+            ? page.title
+            : `${page.title} · ${content.site.name}`
+        : `${page.title} · ${content.site.name}`;
+export const frame = (content, path) => {
+    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,
+        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)], 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>;

package/dist/state.js

@@ -0,0 +1,33 @@
+// The application's state beyond the page, however it was declared: field by field (`field(type, default)`), or as a hand-built schema with a separate initial value. Both become one thing here.
+// No Node and no Vite: the browser entry loads this too.
+import { Schema } from "effect";
+import { FIELD } from "./index.js";
+const isField = (value) => typeof value === "object" && value !== null && FIELD in value;
+/** The state a definition declares, or `undefined` for none. */
+export const stateOf = (author) => {
+    const state = author?.state;
+    if (state === undefined) {
+        return undefined;
+    }
+    const entries = Object.entries(state);
+    // A hand-built state is `{ schema, initial }` where `schema` is a Schema; a field named `schema` is a Field.
+    if (!entries.some(([, value]) => isField(value)) && "schema" in state && Schema.isSchema(state["schema"])) {
+        return { schema: state["schema"], initial: (state["initial"] ?? {}), declared: false };
+    }
+    const fields = entries.filter((entry) => isField(entry[1]));
+    return {
+        schema: Schema.Struct(Object.fromEntries(fields.map(([name, each]) => [name, each.schema]))),
+        initial: Object.fromEntries(fields.map(([name, each]) => [name, each.initial])),
+        declared: true,
+    };
+};
+/** The fields whose default is not a value of the field's own type (only for a state declared field by field). */
+export const badDefaults = (author) => {
+    const state = stateOf(author);
+    if (state === undefined || !state.declared) {
+        return [];
+    }
+    return Object.entries(state.schema.fields)
+        .filter(([name, schema]) => !Schema.is(schema)(state.initial[name]))
+        .map(([name]) => name);
+};

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@valancex/common",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.11.0",
+  "description": "The author's side of a VALANCE application (defineApp, component, field) and the runtime the vlx build runs: the browser and server entries. What src/main.ts imports; @valancex/cli builds what it describes.",
+  "keywords": [
+    "valance",
+    "defineApp",
+    "component"
+  ],
+  "homepage": "https://github.com/ValanceX/Valance/tree/main/packages/common#readme",
+  "bugs": {
+    "url": "https://github.com/ValanceX/Valance/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ValanceX/Valance.git",
+    "directory": "packages/common"
+  },
+  "license": "MIT",
+  "author": "Jack Miller <jackmiller0899@gmail.com>",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "types"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@valancex/mesh-runtime": "^0.11.0",
+    "@valancex/port-web": "^0.4.0",
+    "@valancex/valance": "^0.11.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "effect": "^3.10.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run"
+  }
 }

package/types/mprx.d.ts

@@ -0,0 +1,5 @@
+// What importing a template file gives the author's TypeScript: the file's address (see `Template` in src/index.ts, which this is structurally). The bundler (vite.ts) makes the import.
+declare module "*.mprx" {
+  const template: { readonly mprx: string };
+  export default template;
+}