Skip to content

Latest commit

 

History

History
551 lines (486 loc) · 28.3 KB

pages.md

File metadata and controls

551 lines (486 loc) · 28.3 KB

+++ title = "Pages as files" description = "A view written as a file — TSX or JS on QuickJS (in a browser, a Web Worker), Luau elements, A2UI JSON — re-rendered live on save, on a thread of its own, drawn as the same edit stream a process view sends; one API defined once in Rust, its TypeScript and Luau types generated from it." weight = 68 +++

Status: landed (2026-11, #273) in architect-pages (features/pages): the API, the QuickJS and Luau runners, TSX by oxc with source maps, A2UI JSON pages, workers and timers in both script runners, reload on save with the last good page kept, overrides in the app's folder, and the sandbox's Board tab as a file (with an A2UI page and a Luau page beside it). In a browser (#325): TSX/JS pages in a Web Worker on the browser's own engine, the same file and types ("On the web" below). A framework's own DOM (#326): architect/dom, so Preact runs in a page's runtime, natively and in a browser ("A framework's own DOM" below). Actions as files (#536): a typescript extension's actions and hooks as .ts modules on the same runtime ("Actions as files" below).

The model

A page is a view drawn from a file. Every user-facing feature is a linked extension (#272): its Rust crate is the model — data, actions, heavy work — and its pages can be files. A page shows instead of the extension's compiled view when there is one for it, in this order (features/pages/src/runner.rs Pages::resolve):

  1. an override in the app's folder, <app dir>/pages/<extension>/<view>.tsx (or .ts, .jsx, .js, .luau, .a2ui.json; pages/<view>.tsx for short) — it replaces the view live, and deleting it brings the built-in back;
  2. the extension's own page, [[views]] page = "pages/board.tsx" in its manifest (features/extensions/src/manifest.rs ViewDecl);
  3. a built-in's page, written read-only under <app dir>/pages/.builtin/<extension>/ (features/pages/src/files.rs write_builtin) and edited by cloning it to the override's place (clone_to_edit, the PAGES_CLONE action);
  4. otherwise the compiled view.

The app provides ViewPages in its root (features/pages/src/ui.rs use_view_pages); ExtensionView asks it first (features/extensions/src/interface.rs ViewPages, PageAsk).

One API, defined once

The page API is two #[architect::rpc] services over facet types in features/pages/src/api.rs:

  • PageHost — the host service's subset that exists today: run an action, actions, setting / set_setting, theme, shared / set_shared (state every page shares), notify; #[subscribe] streams theme_changes, data and workers. The full host service, with consent, is #178's.
  • PageView — render(Element), overlays, and the events stream.

Element is the tree a page renders: a tag (#text for text), a key, attributes (style through the theme: var(--foreground)), handlers (Listener: an event and the number its runtime keeps the function under) and children. In process a runner binds these calls directly (features/pages/src/host.rs AppHost); under vox they are vox services, so a process or the web build speaks the same API.

Generated types. features/pages/src/codegen.rs writes architect.d.ts — vox's TypeScript codegen over the services' descriptors (named types and caller interfaces), plus the runtime's surface — and architect.d.luau from the same shapes. The app writes both into its folder with its agents' guide, which names them (features/control/src/guide.rs Guide::file; the sandbox's apps/ui/src/lib.rs page_types); write_types writes them on their own. The copies in features/pages/types/ are checked by features/pages/tests/types.rs, which fails when they drift (BLESS=1 writes them again).

A page

import { h, useData, useState, actions, worker, theme } from "architect";

export default function Board() {
  const board = useData<{ pins: string[] }>("LAB_BOARD_STATE", {}, { every: 500 });
  const [title, setTitle] = useState("");
  return (
    <div style={{ padding: 24, color: "$foreground" }}>
      <input value={title} onInput={(e) => setTitle(e.value ?? "")} />
      <button onClick={() => actions.run("LAB_BOARD_PIN", { title })}>Pin</button>
      {(board.value?.pins ?? []).map((p) => <div key={p}>📌 {p}</div>)}
      <small>{theme.scheme}</small>
    </div>
  );
}

The sandbox's Board tab is this, in full: apps/sandbox/board/pages/board.tsx with its worker apps/sandbox/board/pages/primes.js (apps/sandbox/board/tests/page.rs). A Luau page builds the same tree:

local n = 0
render(function()
  return div():style({ padding = 12 }):child(span():child("clicked " .. n))
    :child(button():child("+1"):on_click(function() n += 1 end))
end)

And an A2UI page declares it, bound to its extension's data and actions (apps/sandbox/board/pages/summary.a2ui.json is the Board's, in full):

{
  "components": [
    { "id": "root", "component": "Column", "children": ["draft", "pin", "pins"] },
    { "id": "draft", "component": "TextField", "label": "Title", "value": { "path": "/draft" } },
    { "id": "pin", "component": "Button", "child": "pin-label",
      "action": { "event": { "name": "LAB_BOARD_PIN", "context": { "title": { "path": "/draft" } } } } },
    { "id": "pin-label", "component": "Text", "text": "Pin" },
    { "id": "pins", "component": "List", "children": { "componentId": "pin-row", "path": "/board/pins" } },
    { "id": "pin-row", "component": "Text", "text": { "path": "" } }
  ],
  "data": { "draft": "" },
  "bind": { "/board": { "action": "LAB_BOARD_STATE", "every": 1000 } }
}

The runners

One thread per page (features/pages/src/runner.rs Pages::open, PageSession). The page's runtime is made on its thread and lives there; it waits on an inbox (the pane's events, host calls' answers, shared state, workers' news), calls into the page, and when the page asked to render, diffs the new tree against what it drew (features/pages/src/diff.rs Mirror: keyed children keep their nodes, a changed attribute or text is set in place, a handler whose function changed makes no edit) and sends the difference as a Frame of wire::Edits. The window applies frames to a Blitz sub-document — the RemoteDocument a process extension's view fills, with the host's live theme CSS, events, focus and IME (features/pages/src/ui.rs PageView). QuickJS replaces the socket with a channel; nothing else in that path changes, and no API gives a script the window's document.

QuickJS (features/pages/src/js/mod.rs JsEngine, rquickjs): one runtime per page; ES module imports inside the page's folder only (./list.tsx; no packages, nothing outside); "architect" is the runtime (features/pages/src/js/prelude.js: h, Fragment, hooks by component place, useData, useShared, timers, actions, theme, worker, Overlay); console.log goes to the page's log (features/pages/src/runner.rs Log, PAGES_STATUS). No Node APIs: require, process and fetch do not exist; files and the network only through actions the extension's capabilities reach (its gate, features/extensions/src/host.rs gate).

TSX on save (features/pages/src/tsx.rs transpile): oxc parses .ts/.tsx/.jsx, strips types and turns JSX into h(...) as each module loads — about a millisecond for a page — and a mistake is a SourceError with its file, line and column.

Source maps. oxc prints each module with its map (transpile_mapped, SourceMap: the printed module's places back to the file's), and the page's runtime keeps them by module. What a page throws as it runs — a render, a handler, a timer, a promise job, console.error(e), a worker — is remapped through them (remap) before it is written anywhere: its stack says board.tsx:13:3, not the transpiled module's line, its first line leads with that place, and the page's folder's paths are relative. <file>.error, APP_STATUS's problem, the banner and EXT_CHECK all say it so (features/pages/tests/js.rs a_tsx_pages_runtime_error_says_its_own_line_and_column).

Luau (features/pages/src/luau.rs LuauEngine): the element builder on the same edit path, Luau's sandbox, the theme read through. Its timers are a TSX page's: set_timeout(fn, ms), set_interval(fn, ms), clear_timeout(id), each run on the page's thread with a frame after. worker.spawn("count.luau", args) runs a .luau file of the page's folder as a Luau view's worker does (architect_scripting::worker, on its pool, Workers::install_owner): its handle has w:post, w:cancel, w:status, w:progress, w:result, and callbacks w:on_message, w:on_progress, w:on_done, which run as the worker's news wakes the page's thread (deliver), a frame after (features/pages/tests/luau.rs; the sandbox's apps/sandbox/board/pages/luau-primes.luau with its worker count.luau).

A2UI (features/pages/src/a2ui.rs A2uiEngine, feature a2ui, Pages::with_a2ui): a .a2ui.json page is A2UI v1.0 — the page form above (components, one of them root; data; bind), or the messages an agent sends (createSurface, updateComponents, updateDataModel, as A2UI_RENDER takes them). It is drawn through architect's catalog (features/a2ui/src/catalog.rs CATALOG, the security boundary: a component outside it is a labelled placeholder, only its props are read) onto the same Element tree, values read through a2ui-base's data context (paths, templates, its functions). Each bind path holds what its action answers, read as the page loads, every every ms, and after each of its buttons' actions; a Button's action runs its Action List action with its context read through the data model (the page's capabilities its reach, as a TSX page's actions.run), wantResponse / responsePath writing the answer back; a TextField, CheckBox, Slider, ChoicePicker or Tabs bound to a path writes it as the person changes it. A mistake in the file is said with its line and column (summary.a2ui.json:4:5: trailing comma), and a page with no root says so (features/pages/tests/a2ui.rs).

Reload. The page's thread looks at its folder every 200 ms (WATCH_EVERY); a save loads the page in a fresh runtime and swaps it in once it has rendered. One that fails keeps the last good page on screen under a banner and writes <file>.error; the next good save takes both away. A theme change renders the page again with the new snapshot (keyed by its revision, as Luau's ThemeModule). Measured in the sandbox: a save shows in about 150–300 ms, of which loading and rendering the page is 2–3 ms.

On the web

Which runner runs where. Natively (desktop, iOS) a TSX/JS page runs on QuickJS, a Luau page on Luau, an A2UI page through the catalog, each on a thread of its own. In a browser (wasm32-unknown-unknown) a TSX/JS page runs in a Web Worker on the browser's own engine — no QuickJS — from the same file, with the same runtime and the same architect.d.ts (features/pages/src/web/mod.rs WebPages, feature web). Luau and A2UI pages do not run in a browser yet (#187).

The same runtime, its bridge messages. The worker runs the prelude every native page gets (features/pages/src/js/prelude.js), its __host made of messages to the main thread (features/pages/src/web/page.js): a host call is a message answered by one, shared state and the embed's input are kept in the worker (each change comes from the main thread), worker.spawn("job.js") starts a nested Web Worker with the worker runtime (features/pages/src/web/job.js). The page's folder is given as text (PageFolder: the sandbox's are its files, include_str!'d); its scripts are transpiled by oxc in the main thread's wasm and their imports resolved by the native loader's rules (features/pages/src/modules.rs prepare: "architect", "architect/dom", "architect/worker", files of its own folder, nothing else), and the worker links them as blob: URLs.

The main thread only draws. What the worker renders comes back as the element tree; Mirror diffs it into wire::Edits and the extensions host's checked applier applies them under the pane's element (features/extensions/src/web.rs Pane, the one WASI views use: no on* attribute, no dangerous_inner_html, nothing outside the pane). No API gives the page the document. Its events go back to its handlers as natively (features/pages/src/frame.rs page_event).

The same capabilities. Every host call is answered by the page's extension's WebHost (features/extensions/src/web.rs), after the decision every host makes (hostcall::check): actions.run is its run (its own actions, and what capabilities.actions and .effect allow), net.fetch and the interface's calls its host-service calls (capabilities.hosts: a host not named is refused before the browser fetches), the actions a page lists only those it may run. What a browser host does not have it says (documents, ports, secrets). The worker has none of the browser's own network, storage or workers (fetch, XMLHttpRequest, WebSocket, importScripts, indexedDB, Worker… are taken away before the page loads), and the embedder's Content-Security-Policy, which the worker inherits, keeps import() of another host and eval out (the sandbox's: apps/sandbox/web/index.html).

Limits. A browser has no interrupt to stop one call, so the page's work is timed in units: a message (an event, a host call's answer, shared state) or a timer, with the promise jobs and renders it leads to. The worker says busy before one and idle after; past Limits::frame (500 ms) the main thread terminates it, the banner says it "ran past its time of 500 ms: hand heavy work to a worker (worker.spawn)", and the page starts again from its files (three times, then it stays stopped until it is reloaded). Loading has Limits::load (5 s), a worker Limits::worker_time. The main thread never waits on a page. A browser cannot cap one worker's memory.

Errors and reloads. A page that does not load, or whose render throws, keeps its last good frame under the banner, its error at its source's line and column (the worker says its modules' blob: URLs as /page/<file>, remapped through oxc's maps by tsx::remap). WebPage::reload is a save: the folder loads again in a fresh worker, swapped in once it has rendered.

Not on the web yet: a dynamic import() of the page's own files (only static imports are resolved), inline embeds' input, documents, ports and secrets (the browser host has none), and services (services.call).

The sandbox. just sandbox-web builds and serves the web lab (apps/sandbox/web): the Board's own apps/sandbox/board/pages/board.tsx (and primes.js, its worker) with the three Board actions it runs answered in the page (apps/sandbox/web/src/board.rs; the Board's Rust extension is not built for a browser), beside the WASI Counter; ?page=preact is the Board's Preact page; ?page=runaway and ?page=net are checks. just sandbox-web-test drives them in a headless Chrome (apps/sandbox/web/test/pages.test.mjs): the Board renders and its handlers and worker run, the Preact page answers clicks and typing, a runaway is stopped while the main thread keeps drawing, a host outside the page's capabilities is refused, and a broken save keeps the last good page.

Actions as files

Status: landed (2026-11, #536) in architect-pages: natively (feature actions, desktop and iOS) and in a browser (feature web, WebPages::register_actions; the web lab runs the showcase's Recipe scaler, apps/sandbox/web/test/actions.test.mjs). The web app hosting installed extensions at all is #495's.

An extension with any logic of its own once needed a compiled part: a page could call actions, but an action ran as Rust, a process or a WASI component. A typescript extension writes them as files beside its pages, on the same runtime, so a light extension is a manifest and some .ts files — no Rust, no WASM toolchain. Most of what we build stays Rust; this is the option for light ones.

id = "showcase.recipes"
kind = "typescript"

[capabilities]
actions = ["VAULT_READ", "VAULT_CREATE"]
effect = "mutating"
ui = ["prompts", "notify"]

[[actions]]
id = "SHOWCASE_RECIPES_SCALE"
name = "Recipe scaler: scale"
params = '{"type":"object","properties":{"path":{"type":"string"},"servings":{"type":"number"}}}'
script = "actions/scale.ts"

[[hooks]]
on = "app:recipes.cooked"
script = "hooks/cooked.ts"   # or one export of it: function = "cooked"

[[views]]
id = "scaler"
page = "pages/scaler.tsx"
import { defineAction, actions, ui } from "architect";
import { scale } from "../lib/scale";

type Args = { path?: string; servings?: number };

export default defineAction<Args>(async (args, ctx) => {
  const servings = args.servings ?? Number(await ui.input("Servings"));
  const note = await actions.run<{ properties: Record<string, unknown> }>("VAULT_READ", { path: args.path });
  return scale(note.properties, servings); // the run's answer, as JSON
});

The manifest (features/extensions/src/manifest.rs Kind, is_ts_script): kind = "typescript", and each [[actions]] script and [[hooks]] script a .ts, .mts, .tsx, .js, .mjs or .jsx module of the package. A Luau script in a typescript extension, or a TypeScript one in a luau extension, is refused and says which kind it needs. The action's id, name, params schema, effect, shortcut and toggle are the manifest's, as for any kind, so it is in ⌘K, keymaps, the CLI, MCP, the control socket, menus, toolbars and hooks like any action.

At load (features/pages/src/js/action.rs TsRunner, the extensions host's runner for the kind): every script of the folder is transpiled by oxc (features/pages/src/modules.rs prepare), and each action's and hook's module, with every file it imports, must compile and resolve — a mistake fails the load with its file, line and column (lib/scale.ts:1:24: …), the last good copy staying, as for every kind. A module imports "architect" and files of its own folder; no packages (bundle one into a file: esbuild src/x.ts --bundle --format=esm --outfile=actions/x.js), no fetch, fs, process or Node globals.

A run has a fresh QuickJS runtime of its own on a thread of its own (features/pages/src/js/mod.rs JsEngine::bare, JsEngine::run_action): the prelude every page gets, its module loaded, its default export (or the export a hook's function names) called with the arguments and a ctx, then its units of work — a host call's answer, a timer, a worker's news — until what it returned settles.

  • The whole host service, typed: the "architect" module is a page's (actions, documents, editor, net and secrets, ui prompts, pickers and menus, clipboard, events, settings, state, ports, worker), through the same bridge (features/pages/src/host.rs AppHost, EXT_PAGE_CALL), typed by the same architect.d.ts. Its calls are made as its extension acting for whoever ran it, through its gate and its granted capabilities: what a page or a Luau script of it may do, no more.
  • Typed end to end: defineAction<Args, Answer>(handler) and ActionHandler, ActionContext (action, extension, source — the door it was run from — and a hook's event and detail) are in architect.d.ts; architect-ext types writes each action's Args from its manifest's params (#535), so the manifest and the code cannot drift silently.
  • Its answer is what the handler returns, as JSON (a value that is not JSON fails the run and says so). What it throws is the run's error, at its .ts file's own line and column (its source maps), and in its extension's log (EXT_LOGS) with its console.log lines.
  • Limits (ActionLimits): memory (64 MB); each unit of its work within unit (1 s) before the interrupt stops it ("hand heavy work to a worker"); its module's top level within load (5 s); its units in all within cpu (20 s), so a timer that renews itself for ever is stopped; the whole run, waits for the person included, within time (10 min); at most concurrent (8) runs of one extension at once. A run whose promise nothing will ever settle — no host call, timer or worker outstanding — is stopped and says so. Its answer is capped at 1 MB and its error at 4 KB, as a Luau script's (features/extensions/src/host.rs MAX_ANSWER, MAX_ERROR).
  • One undo step per run when the runner has transactions (TsRunner::with_transactions), taken back when it fails, as a Luau script's run is. The app gives both runners its documents (features/extensions/src/documents/crdt_docs.rs CrdtDocuments implements Transactions: what a run edited, made, renamed or deleted through documents.* is kept or taken back as one step; features/pages/tests/script_undo.rs). The vault's own actions (VAULT_*) write files and are not part of it.
  • On reload a running action finishes on the old code; the next run loads the module again.
  • In a browser (features/pages/src/web/actions.rs): each run is a Web Worker of its own on the browser's engine — the worker a page runs in (web/page.js, its action mode), with the same prelude and bridge — its host calls answered by the extension's WebHost. WebPages::run_action runs one; WebPages::register_actions puts a manifest's TypeScript actions on an Action List. No QuickJS and no JSPI, so Safari runs them. Its limits are a browser page's: each unit within Limits::frame (the worker terminated past it), loading within Limits::load; a browser cannot cap a worker's memory. What the browser's host does not answer yet (prompts, pickers, ui.notify) is refused there; the prelude's notify reaches the page's notify sink.
  • Where it stops: an interpreter. Not for heavy computation (engraving, parsing a DAW project, anything per frame) and never on the audio path (#528): those are Rust, called from TypeScript as actions.

Tooling (@fasttrackstudio/architect-cli, features/extensions/web/cli/ts.mjs): architect-ext new --typescript <id> writes a manifest, one action and one page that work on save; architect-ext types writes types/architect.d.ts and types/actions.d.ts (each action's Args from its params, as ActionArgs); architect-ext check checks the manifest and its files and runs tsc --noEmit; architect-ext pack --key <minisign key> writes the signed .archext the app installs, in the archive's format (features/extensions/archive/tests/npm_pack.rs opens one).

Tests: features/pages/tests/ts_actions.rs (typed answers through an import, line and column, capabilities, prompts and notices, fetch within its hosts, the limits, a hook, a broken module, EXT_CHECK).

Safety and performance

  • Limits (features/pages/src/runner.rs PageLimits): memory (64 MB), and each call into a page — a render, a handler, a timer — has frame (500 ms) before QuickJS's interrupt stops it with "hand heavy work to a worker"; its module's top level has load (5 s). The pane shows its last frame with the shell's busy mark once an event goes unanswered past a frame's budget (ViewMeter, FRAME_BUDGET), long before.
  • Workers: worker.spawn("job.js", args) runs a script of the page's folder in a QuickJS runtime of its own on its own thread (worker_memory, worker_time), spoken to by JSON messages; it ends with its page (or w.cancel()). A Luau page's worker.spawn("job.luau") runs one in a Luau state on the scripting pool, under the same limits. Their names are the other runners' (extensions.md, "Responsive by design").
  • Actions a page runs go to the app's Tokio runtime, never the page's thread (features/scripting/src/vm.rs Dispatch, as Luau scripts' do).
  • Pages are for panels, lists, forms, dialogs and dashboards. Dense or animated views — the paint kind, Studio's arrangement, a mixer — stay compiled: a page's every change crosses as JSON and a diff.

For agents

PAGES_STATUS lists every running page, whether it is the page as saved (or why not), its render and reload times and its log; PAGES_CHECK {file} loads a page off the window and renders it once; PAGES_CLONE {extension, view} makes a built-in's page editable (features/pages/src/actions.rs install). Pages' problems are in APP_STATUS: each page that is not the page as saved — open in a pane, or its <file>.error from its last run — with its file and view (features/pages/src/runner.rs Pages::status_problems, Pages::report_problems). EXT_CHECK renders an extension's [[views]] page files once through the app's pages (feature manager: features/pages/src/manage.rs Pages::page_checker, given to Host::set_page_checker), a broken one a page problem with its file and field.

In the extensions manager (feature manager) pages are a kind, pages (features/pages/src/manage.rs PagesKind, over Pages::entries): every view's page — a built-in's read-only copy, an extension's, an override — with whether an override wins, how it runs, its problems and its frame times, and the ops check, clone (a built-in's, to edit) and restore (the override removed: its own page shows again).

A framework's own DOM

A page may render with a framework that renders to the DOM — Preact, Solid — instead of h: import { document } from "architect/dom" gives the page a DOM of its own, in the spirit of AMP's worker-dom, in the page's runtime (features/pages/src/js/dom.js): QuickJS natively, the page's Web Worker in a browser. It is never the window's document. The framework builds and mutates it; each change marks the page dirty, and once the unit of work is over (the event, its promise jobs, the framework's own microtask) the runtime draws it as it draws a component's tree — every node keyed by its own id, so a node the framework moves stays itself — and Mirror diffs that into wire::Edits, applied by Blitz natively and by the extensions host's applier on the web. Nothing on the window's side changes.

import { h, render } from "./vendor/preact.js";
import { useState } from "./vendor/hooks.js";
import { document } from "architect/dom";

function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>Clicked {n}</button>;
}

render(<Counter />, document.body);
export default document.body;

The page's default export is the body it rendered into (mount in features/pages/src/js/prelude.js takes a component or that body). The framework comes from the page's folder, as any file does — no Node, no bundler: the sandbox's Board ships Preact 11 in apps/sandbox/board/pages/vendor/ (its hooks' import "preact" written as "./preact.js", since a page imports no packages) and its preact view is apps/sandbox/board/pages/preact.tsx.

What it has. createElement/createElementNS, createTextNode, createComment, createDocumentFragment; appendChild, insertBefore, removeChild, replaceChild, remove, append, before/after/replaceWith; siblings, childNodes, parentNode; attributes (and id, className, value, checked, disabled… as properties), classList, dataset, style (properties, cssText, setProperty); textContent, a text node's data; addEventListener (capture, once) and dispatchEvent; querySelector for compound selectors; innerHTML serialized (setting it only clears: there is no HTML parser). Nothing is laid out: getBoundingClientRect is zero. The prelude gives every page requestAnimationFrame (a 16 ms timer of the page's own) and queueMicrotask, so what a framework schedules runs in the page's units of work, timed as any.

Events. A node with listeners is drawn with handlers for their events; the pane's event comes back as a ViewEvent to the nearest element that has one (Mirror::handler), and the shim dispatches it as a DOM event through its own tree: captured from the document down, at the element, bubbled back up, with stopPropagation, preventDefault, the pointer's place and the keys. An input sets the element's value first and is followed by a change. Solid's delegated $$click handlers are drawn as listeners too (Solid is not tested yet).

Tests: features/pages/tests/dom.rs (Preact's tree and the edits each click makes; the DOM by hand: capture and bubbling, a move that keeps its node), apps/sandbox/board/tests/page.rs (the Board's Preact view), and the web sandbox's apps/sandbox/web/test/pages.test.mjs (?page=preact, in a headless Chrome).