AGENTS.md

# WE — Codebase & Schema Reference

This file is auto-generated by `@we/ai-context`. Do not edit manually.
Regenerate with: `pnpm --filter @we/ai-context generate-context`

This reference serves two modes:
- **Working in the codebase?** Start with **Architecture Orientation** below — what WE is, its
  AD4M runtime, the core concepts, the package layering, and the render pipeline. Then
  **Contribution Surfaces**, which routes what you are about to build to the slot it belongs in,
  and names the file that registers it — the step whose omission fails silently.
- **Authoring a WE UI schema (JSON)?** Skip to the **Schema Structure**, **Component Registry**,
  and **Design Tokens** sections. All schemas must be valid JSON using only the components, props,
  tokens, and patterns documented there.

---

## Architecture Orientation (codebase work — not for JSON schema authoring)

### What WE is

WE is **social infrastructure that lets communities own their data and shape their own tools** —
the interface layer of a three-part stack: **WE** (design system + schema-driven UI + module
marketplace) on **AD4M** (data, meaning, agent coordination) on **Holochain** (trust/sync).

The core move: **the app is not the unit.** An experience is not compiled code — it's a
**template**: a JSON schema rendered live against a component registry. Because a template is
data rather than code, it is inspectable, forkable, safe to share from untrusted sources, and
editable by AI in place. Data lives separately, in AD4M perspectives the user owns, so changing
the interface never costs you your history.

Contributions form a ladder: most are **templates and themes** (authored in-browser, often
AI-assisted, no code). **Modules** (tokens → primitives → components → widgets, plus
blocks and feature modules) are the developer layer beneath — lower volume, but they raise the
ceiling on what every template above can express. A deployment is described by a **seed file**
(`we-seed.json`): which modules to include, how to arrange/theme them, platform settings.
(Flux is the reference application built on WE.) See VISION.md for the full rationale.

### Runtime: built on AD4M

WE's data layer is **AD4M** — an agent-centric, local-first, peer-to-peer meta-ontology.
Data is yours, stored locally and synced P2P (via Holochain) with no central server. The Solid
app (`@we/app-shell`, hosted by the web/electron/tauri targets) talks to an **AD4M executor**
(the ad4m runtime; `@coasys/ad4m` + `ad4m-connect`) that holds perspectives and syncs
neighbourhoods. Stores (`sessionStore`, `datasetStore`, `spaceStore`, …) expose reactive state to schemas.

AD4M is reached through the **backend contract** rather than directly: `@we/backend-shared` declares
the ports (`DataSource` + `QueryAdapter`, ephemeral, presence, transcription, model manifest) and
`@we/backend-ad4m` implements them. The renderer, the design system and the module contract never
import `@coasys/*` — which is why a template, a component or a feature module can be reasoned about
without knowing what holds the data.

Glossary (these terms pervade stores, models, and `$query`/`perspective` in schemas):
- **Agent / DID** — a user identity; addressed by a DID (`sessionStore.me.did`).
- **Perspective** — a local knowledge graph (links/triples). Each Space is backed by one;
  `datasetStore.currentDataset` is the active one, `datasetStore.rootDataset` holds we-root (the app's
  configuration), and `datasetStore.personalDataset` holds we-personal (the agent's notes and Pocket).
- **Neighbourhood** — a *shared* perspective, synced peer-to-peer. A shared Space is a neighbourhood.
- **SDNA (Social DNA)** — SHACL schemas installed into a perspective that define its data model.
  WE's models are SDNA-typed; `initializeAsWeSpace` installs WE's Space SDNA into a foreign perspective.
- **Expression / Language** — an AD4M content object addressed by a URL, stored/retrieved via a
  Language plugin (e.g. images go through FILE_STORAGE_LANGUAGE → an expression URL).
- **Model (Ad4mModel)** — WE's ORM over perspective links (`Space.create`, `findAll`, `include`, …);
  SDNA/SHACL-typed classes. See dev-patterns for CRUD conventions.

### Core product concepts

- **Space** — a community/context, backed by an AD4M perspective. *Personal* (local) or *shared*
  (a neighbourhood). Has a default template + theme.
- **Template** — a full UI **schema** (the JSON node tree). A Space renders a Template. Installable/shareable.
- **Theme** — token overrides + CSS layered over a template for visual identity. Installable/shareable.
- **Block** — a composable content unit (TextBlock, ImageBlock, EmbedBlock, …) authored via the block
  composer and stored as models. Blocks compose into posts/pages.
- **Signal** — a per-community reaction/vote. A `SignalType` (created per space) defines it; `Signal`
  instances attach to any `WeNode`.

### Package Map

| Package | Dir | Role | Framework coupling |
|---|---|---|---|
| `@we/tokens` | design-system/1-tokens | Design tokens (spacing, color, radius, …) as CSS vars / JS | Agnostic |
| `@we/themes` | design-system/2-themes | Theme definitions layered over tokens | Agnostic |
| `@we/primitives` | design-system/3-primitives | UI primitives (`we-button`, `we-input`, …) | **Lit web components — agnostic** |
| `@we/components` | design-system/4-components | Layout & composite components (Column, Row, Card, …) | Solid (`.types.ts` + `.solid.tsx`) |
| `@we/widgets` | design-system/5-widgets | Generic widgets (graph, sidebar) — feature widgets live in their module family | Solid |
| `@we/design-utils` | design-system/utils | Shared DS-props → style computation; token resolvers | Neutral core + `/solid` binding |
| `@we/design-types` | design-system/types | Shared DS prop/type definitions | Agnostic |
| `@we/schema-kit` | schema-system/kit | Portable fragments — authoring-time helpers that expand to plain nodes, naming no store | Agnostic |
| `@we/template-kit` | templates/kit | The same, for fragments that read WE's own stores (`profileStore`, `spaceStore`) | Agnostic |
| `@we/template-shell` · `@we/template-default` | templates/* | WE's shell surfaces and built-in space templates, as data | Agnostic |
| `@we/editor` | packages/editor | Template/theme editing surface, embeddable via `EditorHost` | Solid (mount fn at the boundary) |
| `@we/schema-shared` | schema-system/shared | Schema semantics: prop resolvers, validation, indexer, registry types, reactivity port | **Agnostic** |
| `@we/schema-solid` | schema-system/frameworks/solid | The schema renderer (walks the tree, mounts components) | Solid (thin adapter) |
| `@we/backend-shared` | backend-system/shared | The backend contract: `DataSource`, query IR + engine, ephemeral, presence & transcription ports, model manifest | **Agnostic** |
| `@we/backend-ad4m` | backend-system/ad4m | The AD4M adapter: query adapter, ports, agent identity, SDNA install — and the AD4M model classes, generated from @we/entities' manifest (src/models) | Agnostic |
| `@we/backend-inmemory` | backend-system/inmemory | In-memory adapter — the reference implementation, and how stores test without an executor | Agnostic |
| `@we/backend-conformance` | backend-system/conformance | One suite of the contract's behaviour every backend runs, with each backend's known gaps listed and run inverted | Agnostic |
| `@we/module-shared` | module-system/shared | The feature-module contract — manifest, contributions, kernels, store markers, `lintModule` — what a module author installs | Agnostic |
| `@we/module-testing` | module-system/testing | Fakes for testing a module store without a host: `fakeDeps`, `fakeRecords`, `fakePresence`, `buildStore` | Agnostic |
| `@we/module-globe` · `-call` · `-notes` · `-pocket` · `-polls` · `-transcribe` · `-graph` | module-system/* | Bundled feature modules — each exports `createModule(host)` and the seed's `modules` list generates the registry; globe is a *family* (module · protocol · layers · widget) | Agnostic (components injected) |
| `@we/graph-protocol` · `-core` · `-expanders` · `-layouts` · `-solid` | graph-system/* | The graph engine: expander/layout/renderer contracts, the neutral engine, first-party plugins, and the Solid adapter | **Agnostic** (Solid only in the adapter) |
| `@we/block-shared` | block-system/shared | Block content types + serialization | Agnostic |
| `@we/optimism` | packages/optimism | A write drawn before it has been seen come back — hold, baseline, settle, and when to stop believing it | Agnostic (signal injected) |
| `@we/clock` | packages/clock | A moment being looked at and the playback that moves it — clocks by name, so a globe, a scrubber and a module follow the same one | Agnostic |
| `@we/history` | packages/history | Undo as a stack of this agent's own inverse writes, replayed **forwards** — the only shape that is safe on shared, last-write-wins data | Agnostic (signal injected) |
| `@we/drag` | design-system/drag | The drag session and its payload — references, never DOM — plus the ghost, the zone registry and the press-to-drag threshold | Agnostic |
| `@we/entities` | packages/entities | WE's domain models: the authored neutral manifest (src/manifest, the source of truth), the neutral type contract, and the entity proxies backends register into | **Agnostic** |
| `@we/app-shell` | packages/app-shell | App shell, stores, registries, built-in template schemas | Solid |
| `@we/ai-context` | packages/ai-context | Generates this reference (CLAUDE.md et al.) from code + fragments | Build tool |

Apps (`apps/we-web`, `apps/we-electron`, `apps/we-tauri`) are thin hosts over `@we/app-shell`.
Each supplies two things: a `PlatformAdapter` (where am I running) and a `BackendConnector`
(how do I reach the data layer).

**Dependency direction:** `templates → shell → backend-shared ← backend-ad4m`, and
`modules → shell → backend-shared`. Dependencies point inward toward the contract packages; there are
no sideways edges. `@coasys/*` may be imported by `@we/backend-ad4m`, `@we/entities`, and any module
that declares `backends: ['ad4m']` — nothing else. See `docs/architecture/package-conventions.md`.

### The Three Seams (why the layering holds)

1. **Primitives are the framework-neutral currency.** `@we/primitives` are Lit web components, so
   they render as plain custom-element tag strings in any framework. The schema renderer sets their
   props/events generically — no per-framework wrapper is needed for the render path. (Typed
   per-framework *declarations* are generated from the Custom Elements Manifest for hand-authored
   code — a DX layer, not a runtime one.)

2. **Schema semantics live in `@we/schema-shared`, parameterized by a reactivity port.** All token
   resolution (`{ $ }` expressions, `$action`, `$query`, `$setLocal`, …) is in `propResolvers/`.
   `resolveProp(value, stores, context, memo)` takes a framework-injected memoization function
   (`memo`), and `markReactive()` (see `propResolvers/reactive.ts`) tags accessors so a renderer
   knows a prop is reactive. The entire schema engine AND its reactivity wiring are framework-neutral;
   a framework only injects its signal primitive.

3. **The renderer is a thin per-framework adapter over a component registry.** `@we/schema-solid`
   walks the schema tree, resolves props with Solid's `createMemo` as `memo`, maps
   `$each`/`$if`/`$routes` onto `<For>`/`<Show>`/`<Dynamic>`, and mounts each node — a tag string
   for primitives, a registered component for layer-4/5. Adding a framework = a new adapter of this
   shape, NOT re-implementing the semantics.

### Render Pipeline (schema JSON → DOM)

1. A schema node has `type` (component/tag name), `props`, `children`, optional
   `routes`/`slots`/`$localState`/`$queries`.
2. Props are resolved by the shared dispatcher (`propResolvers/dispatcher.ts`): token objects
   (`{ $ }` expressions, `$query`, handlers) become values or reactive accessors via the injected `memo`;
   event-handler arrays resolve lazily at call time.
3. The renderer looks up `type` in the `ComponentRegistry` — a custom-element tag for
   `@we/primitives`, a framework component for `@we/components`/`@we/widgets`.
4. It mounts the node, binds resolved accessors as reactive props, wires custom events, and recurses
   into children. Block-level `$`-types (`$each`, `$if`, `$single`, `$animate`, `$routes`) map to the
   framework's control-flow primitives.

### Where to look

- Change how a token/operator resolves → `packages/schema-system/shared/src/propResolvers/`.
- Change tree-walking / mounting / control flow → `packages/schema-system/frameworks/solid/src/`.
- Add/adjust a primitive → `packages/design-system/3-primitives/src/` (Lit).
- Add/adjust a layout/composite component → `packages/design-system/4-components/src/` (Solid).
- DS-props → CSS logic (shared) → `packages/design-system/utils/src/index.ts`; Solid binding → `.../src/solid/index.ts`.
- Stores / app shell / registries → `packages/app-shell/src/`.
- Built-in templates (data) → `packages/templates/`.
- The editing surface → `packages/editor/src/`.
- The backend contract (ports, query IR) → `packages/backend-system/shared/src/`.
- AD4M wiring (query adapter, SDNA install, agent identity) → `packages/backend-system/ad4m/src/`.
- The feature-module contract → `packages/module-system/shared/src/module.ts`; a module → `packages/module-system/<id>/`.
- Data models (Space, blocks) → `packages/entities/src/` (see packages/entities/CONVENTIONS.md).
- A space's sections (views) → `packages/templates/views/`; how they resolve →
  `packages/app-shell/src/shared/viewResolution.ts` (see docs/architecture/views.md).
- Graph engine (expanders, layouts, expansion state) → `packages/graph-system/` (see its README);
  its data binding lives at `packages/app-shell/src/frameworks/solid/components/GraphHost.tsx`.
- App chrome and module panels (the sidebar, the module rail, floating vs displacing, who moves for
  whom) → `packages/app-shell/src/shared/dockGeometry.ts` (see docs/architecture/chrome-and-panels.md).
- What no template may replace — the password field, the safety prompts, safe mode — and the one
  place each is enforced → docs/architecture/protected-pieces.md. Read it before touching the boot
  screen, a confirmation the host raises, or how a template becomes the live one.

**Where a new thing goes** — module or host store, panel or fragment, who decides placement, and how
two capabilities cooperate without depending on each other — is
docs/architecture/capabilities-and-surfaces.md. Read it before adding a module, a panel or a store:
it is four rules, and half of it is the shapes that are refused on purpose.

For deeper detail (data sync/persistence, block & editor internals, the local dev/test loop),
see docs/architecture/codebase-map.md.
For how reusable template fragments work and where they are going, see
docs/architecture/template-fragments.md.

**A template is one of two things.** A *shell* owns a space's chrome, arrangement and route table;
a *view* renders one section inside one. `meta.role` says which, and absent means shell. A shell
marks where its sections go with `{ path: '$views' }` and the host expands that per space, from
`Space.enabledViews` (the community's list, and its order) minus `SpacePreference.hiddenViews`
(each agent's own). Do **not** hardcode a space's sections as routes, and do not write a nav strip
from a literal array — read `spaceStore.viewNav`, which is the same resolved list the routes are
built from. See docs/architecture/views.md.

**Before adding a relation between two models, read docs/architecture/relations.md.** A connection
can live in three places — a free-text label, a community-named `RelationshipType`, or a relation
declared on the model class — and they are not interchangeable. The short version: a declared
relation gets the full query surface and can carry nothing about itself (no author, no date, nothing
to comment on or rate); a reified one carries all of that and has no query pushdown at all. Declare
what is a fact about the *type*; reify what is a claim about a *pair*.

**Before changing anything about boards, read docs/architecture/boards.md.** A board's columns are
records, and a column is *a saved query with an arrangement*: what is in it comes from each task's
`status`, and the column's ordered `children` are only where the cards sit. That split is why work an
extraction pass writes appears on every board without anyone placing it, why deleting a column must
never delete its cards, and why the link state can be inconsistent after a partition and the board
still renders one answer. The same doc records where new per-column state goes, so the entity does
not accrete a scalar per feature.

---

## Contribution Surfaces (codebase work — not for JSON schema authoring)

Where a change belongs. Work down the routing table and stop at the first row that fits: the earlier
rows are cheaper for everyone, and a contribution one rung too high costs more forever.

The spine of every one of these decisions is a single rule, from `packages/templates/kit/CONVENTIONS.md`:

> **Code owns only what data cannot express.** Behaviour and focus management, accessibility
> semantics, browser APIs, measurement, performance-critical rendering — that is the whole list.
> Everything above it is arrangement, and arrangement stays data.

### Routing — intent to surface

| The intent | The surface |
|---|---|
| Change how a space looks | **Theme** |
| Change what one section of a space *is* | **View** |
| Change a space's whole chrome, arrangement and route table | **Shell template** |
| Reuse an arrangement across templates | **Fragment** |
| A visual element a library already ships — a chart, a rating, a map | **Foreign element** (seed `elements`) |
| Stateless UI needing measurement, focus or a browser API | **Primitive** (Lit) or **component** (Solid) |
| Computation the expression library lacks | **Expression function** |
| A new kind of content composed into a page | **Block type** |
| A stateful capability a community turns on | **Feature module** |
| A new source of nodes, or arrangement, in a graph | **Graph plugin** |
| A new kind of thing that gets stored | **Entity** |
| State or an action a template needs to reach | **Store** |
| A differently-shaped deployment | **Seed** (write nothing — select what exists) |

Three distinctions that have each been got wrong at least once:

- **Component vs fragment.** `AvatarStack` is a component (overlap maths); the count beside it is a
  fragment. `we-modal` is a primitive (focus trap, top layer); the confirm dialog inside it is a
  fragment. The question is never how complicated it is — it is whether it must *do* something or
  merely be *arranged*.
- **Fragment vs operator.** `field` stayed a fragment because *which event carries the value* is
  design-system knowledge; an operator would smuggle that table into the schema resolver.
- **Module vs everything else.** A module is **stateful capability** that talks to ports.
  `@we/module-notes` and `@we/module-call` contain no framework code at all — every piece of their
  UI is a schema fragment. Presentation is not a module.

And overriding all of them: **never extract speculatively.** Three real uses of the same shape, or a
divergence that is already a bug. Two is a coincidence.

**The four reuse units on their axes.** Fragment, primitive, component and widget are all "a reusable
piece of UI"; what separates them is two questions asked in order. *Does it need to do something, or
only be arranged?* Arranged → a **fragment**, whatever the framework, because data is neutral by
construction. Must do something — *can it be neutral?* Focus, top layer, measurement, keyboard →
a **primitive** (Lit). Only what needs the host's reactive framework in its implementation is a
**component** (Solid); a **widget** is a component big enough to own a protocol (`GraphView` and its
plugin catalogue) and lives with its feature. Nothing that is arrangement is ever framework-bound;
a "component" that turns out to be arrangement is a fragment in the wrong language. The left side of
that line crosses the trust boundary as data; the right side merges.

### The surfaces

Each row: where it lives → its rules → **what registers it** → what checks it. The registration
column is the one that gets skipped, and its failure is silent — a view that is written but not in
the seed's list is correct code that never appears.

| Surface | Lives in | Rules | Register | Verify |
|---|---|---|---|---|
| Theme | `design-system/2-themes/src/<name>/` | its `CONVENTIONS.md` | `themeRegistry.ts` | `--filter @we/themes test` |
| Shell template | `templates/showcase/src/` | `docs/architecture/views.md` | seed `templates` + `--filter @we/app-shell generate-templates` | `validate:schemas`, `role-audit` |
| View | `templates/views/src/views/` | `docs/architecture/views.md` | `CATALOGUE` in `generateViewRegistry.mjs` + seed `views` + `generate-views` | `validate:schemas` |
| Portable fragment | `schema-system/kit/src/` | `templates/kit/CONVENTIONS.md` | export from `index.ts` | `--filter @we/template-kit test` |
| WE-domain fragment | `templates/kit/src/we/` | `templates/kit/CONVENTIONS.md` | export from `index.ts` | `--filter @we/template-kit test` |
| Design token | `design-system/1-tokens/src/` | its `CONVENTIONS.md` | — (generated, snapshot-tested) | `--filter @we/tokens test` |
| Foreign element | a package in `app-shell/package.json` | its library's docs | seed `elements` + `--filter @we/app-shell generate-elements` | `validate:schemas`, then `generate-context` |
| Primitive | `design-system/3-primitives/src/primitives/` | its `CONVENTIONS.md` | — (CEM generated by its build) | `--filter @we/primitives test`, then `generate-context` |
| Component | `design-system/4-components/src/components/` | `design-system/CONVENTIONS.md` | `componentRegistry.tsx` | `--filter @we/components test`, then `generate-context` |
| Block type | `block-system/shared/` + `frameworks/solid/` | `block-system/CONVENTIONS.md` | `registerBlock()` in `core-blocks.ts` | `--filter @we/block-shared test` |
| Expression function | `schema-system/shared/src/expressions/functions.ts` | `schema-system/CONVENTIONS.md` ("Adding a function") | `defineFunction()` — the registry feeds the validator, the evaluator and the generated context | `--filter @we/schema-shared test`, then `generate-context` |
| Store | `app-shell/src/frameworks/solid/stores/` | `app-shell/CONVENTIONS.md` | classify in `templateSurface.ts` **and** describe in `fragments/stores.ts` — both fail the build if you don't | `--filter @we/app-shell test`, then `generate-context` |
| Entity | `entities/src/manifest/` | `entities/CONVENTIONS.md` + `docs/architecture/relations.md` | `--filter @we/entities generate:types` **and** `--filter @we/backend-ad4m generate:classes` | `--filter @we/backend-ad4m test` |
| Feature module | `module-system/<id>/` (or any package exporting `createModule`) | `docs/guides/writing-a-module.md`, then `module-system/shared/src/module.ts` | seed `modules` — the registry is generated from it by `--filter @we/app-shell generate-modules` | `--filter @we/module-shared test`, `validate:schemas`, then `generate-context` |
| Graph plugin | `graph-system/expanders/src/`, `layouts/src/` | `graph-system/CONVENTIONS.md` | package index **and** `GRAPH_PLUGIN_CATALOG` in `module-system/graph/src/catalog.ts` | `--filter @we/graph-core test`, then `generate-context` |
| Globe layer | `module-system/globe/layers/src/` | its `README.md` / `EXAMPLES.md` | export from `index.ts`, `layerKinds` in `module-system/globe/module/src/layers.ts`, `maplibreLayerKinds` in `module-system/globe/layers/src/maplibre/index.ts` **and** `GLOBE_LAYER_CATALOG` in `module-system/globe/module/src/catalog.ts` | `--filter @we/app-shell test` (`globeModule`), then `generate-context` |
| Seed | `we-seed.json` | `docs/getting-started/seed-system.md` | — | `pnpm validate:seed` |
| Backend adapter | `backend-system/<name>/` | `backend-system/shared/README.md` | entity proxy registry | `describeBackendConformance` from `@we/backend-conformance` |
| Platform host | `apps/<name>/` | — | — | `--filter <app> build` |

Widgets (`design-system/5-widgets`) are the nineteenth and are **currently empty by design**: the one
widget there was retired once template-kit's rail fragments replaced it, and feature widgets live
with their module family. Treat that as a strong prior that what you have is a fragment or a module.

**A store member is public API, and classifying it is a security decision.** Every member is
reachable from any template through an expression or `$action`, so name it for template authors and treat removal
as breaking. Before `templateSurface.ts` existed, all 388 members were in the bag a template rendered
against — including `runtimeStore.trustAgent` and the settings holding the API key — so a template
that merely *painted* could trust an attacker's DID. Put a new member in the narrowest group that
works.

**The graph catalog entry is not bookkeeping.** Props tell an author that `layout.type` is a string;
nothing in a prop list says which strings exist, so a plugin nobody can name might as well not be
registered. The globe was the cautionary case — a good layer protocol, no catalog of layer names in
the generated context, and so no LLM could author a globe template until it got one.

### Distribution — what is real

**Templates and themes install at runtime**, from a stranger, through a real trust boundary:
`templateSurface.ts` allowlists what a template may name (grouped into capabilities written in the
words a person reads at install time; anything not granted is *absent* rather than blocked, leaving
no error channel to probe), and `templateAcceptance.ts` refuses structurally broken schemas outright
while admitting-and-reporting references past the tier.

**Every other surface ships by merging into this repo.** Feature modules are bundled rather than
dynamically loaded, and the reason is trust, not reactivity: `createStore(deps)` already injects the
reactive primitives, but a store factory is arbitrary code with the host's ports, and the capability
model covers what a schema may *name*, not what code may *do*.

Three of nineteen surfaces (templates, themes, views) have an out-of-repo path. Do not describe the
marketplace as though it covers the rest. `docs/internal/plans/module-marketplace.md` places every
surface on a **distribution ladder** — pure data, declared data + fragments, sandboxed embed,
host-provided capability kernels, code — and says which rung each can reach. Nothing `import()`s a
bundle from an expression, at any rung; a contribution that needs code merges here.

The long-form guide — reference example per surface, the reasoning, the full distribution status —
is `docs/contributing/surfaces.md`. `CONTRIBUTING.md` covers the workflow.

---

## Schema Structure

A schema is a tree of nodes. Each node can have:
- type: The component to render (string, e.g. "we-button", "Column")
- props: An object of props for the component
- children: An array of child nodes, strings for text, or expressions like { "$": "post.title" } (rendered as text).
- slots: Named slots for advanced composition (optional)
- slot: The name of the slot this node should be rendered into (optional)
- routes: For routing components, an array of nestable route objects (optional)
- $localState / $queries: ephemeral state and hoisted subscriptions declared on the node (optional; see Dynamic Logic)
- styles: Raw CSS escape hatch — Record<string, string | number> applied as inline styles on a **wrapper div** that surrounds the component. Use only for CSS that must live on a wrapper: filter, clip-path, backdrop-filter, mix-blend-mode. When present the wrapper participates in layout (no display:contents), so CSS effects apply correctly. **Important:** this is NOT the same as props.styles. If you want to apply custom CSS to a Column, Row, or Grid's own element (e.g. a background image), put it in props.styles instead — node-level styles go on a wrapper div around the component and will be hidden behind the component's own background.

The ROOT node carries one more, and it is required:

- meta: { name, description, icon } — what the template is called and how it is listed. Optional
  keys: role: 'view' for a section rather than a shell (absent means shell), themeId for a theme the
  template was designed with, panels for the surfaces the interface has (see Panels), and
  chromeReserve for a band the shell pins over the content. A root node without meta is refused.

## Shapes the template says once: $defs and $ref

A template often uses the same shape in several places — a card drawn in two display modes, a
column arrangement that appears per person and per status. The root may carry those shapes in
**$defs**, with a **$ref** node standing at each place one is used:

{
  "type": "Column",
  "meta": { "...": "..." },
  "$defs": { "d1": { "type": "Card", "children": ["…the whole card…"] } },
  "children": [
    { "type": "$ref", "props": { "def": "d1" } },
    { "type": "$ref", "props": { "def": "d1" } }
  ]
}

Those two render exactly what two copies of the card would. The definitions live INSIDE the
template, so everything that will render is still in the document — nothing is fetched, and a
template can be read as the thing it will be.

**You will meet these; you rarely need to write them.** Write ordinary nodes. Shapes are hoisted
automatically, so a thing you write out twice becomes one definition without you doing anything.

**Editing one is two different acts, and the difference is which node you patch:**

- Patch a node **inside a definition** and the change shows at EVERY use of that shape. This is
  usually what is wanted — "make the cards wider" is one shape and every card.
- To make a single use differ, send a patch of { "targetId": "<the $ref's id>", "split": true }. That use
  gets a copy of the shape to itself and everything else carries on sharing. The tool result lists
  the copy's nodes by id, so the patch that changes one of them follows in the same turn. **Never
  re-send the shape to do this** — it is thousands of tokens, and a shape retyped from memory loses
  something every time, for a copy the editor is already holding and has just named for you.

The tool result says which happened: a patch that reached a shared shape comes back naming how
many places it changed. If that is not what the request meant, fix it in the same turn.

**Where the words do not decide between the two, ask rather than guess.** "Make the card blue",
said about a card on screen, is as likely to mean that one as all of them, and the two are not
equally easy to undo: changing one of six is a split and a patch, where changing six when one was
meant has already repainted five things somebody did not look at. Say which places are involved —
the count is in the tool result — and let them choose. Guess only where the request names the
scope itself ("all the cards", "this one").

Example node:
{
  "type": "we-button",
  "props": {
    "onClick": { "$action": "routeStore.navigate", "args": ["/home"] }
  },
  "children": [
    { "type": "we-icon", "props": { "name": "house" } },
    { "type": "we-text", "props": { "size": "600" }, "children": ["Home"] }
  ]
}

## Prop-level Dynamic Logic & Expressions

Two kinds of token go in props: an EXPRESSION, { "$": "…" }, for anything computed (a store read, a
condition, a label, a list), and a HANDLER ($action, $setLocal, …) for anything that happens on an
event. A plain string is always text. There are no other value tokens.

Store reference:
{ "$": "storeName.property.path" }
Reads a value from a named store, supporting nested paths — reactive, so the prop follows the store.

Action/event:
{ "$action": "storeName.method", "args": [...] }
Calls a method on a store, optionally with arguments (which can themselves be tokens).
IMPORTANT — omitting "args" does NOT call the method with no arguments: the handler's own arguments are
forwarded, so a click handler passes the DOM event as the first parameter. That is deliberate (it is how
{ "onChange": { "$action": "store.method" } } passes a value straight through), but it means a method whose
first parameter is OPTIONAL receives a PointerEvent from a button written the obvious way. Pass the argument
you mean explicitly when the method has an optional leading parameter — note "args": [] does not help, since
an empty list is treated as "no args given" and forwards the event too.
Supports async lifecycle callbacks — fired after the store method's Promise resolves/rejects:
  onSuccess: [...actions]  — fired on resolve; { "$": "result" } (and result.<path>) in args refers to the resolved value
  onError: [...actions]    — fired on reject; { "$": "result.message" } etc. refers to the error object
  onFinally: [...actions]  — fired regardless of outcome
Non-promise (synchronous) methods are unaffected — lifecycle keys are ignored.
Example — close modal after async submission:
{ "$action": "spaceStore.createSpace", "args": [...], "onSuccess": [{ "$setLocal": "modalOpen", "value": false }] }
Example — navigate to newly created item:
{ "$action": "spaceStore.createSpace", "args": [...], "onSuccess": [{ "$setLocal": "modalOpen", "value": false }, { "$action": "routeStore.navigate", "args": [{ "$": "`/space/${result.uuid}`" }] }] }

An action runs only when somebody asked for it. A press, a key, typing, a drop or a paste that reaches
the element whose handler calls it counts as asking — and so does whatever the element does in answer,
even a moment later, once. An event that happens to the element by itself does not: onLoad, onError,
onToggle, onFocus, onMouseEnter, onAnimationEnd, a component reporting its size. Wired there, an action
that stores something, publishes something or reaches a device is refused and does nothing; put it on
the press instead. Navigating, opening and closing surfaces and editing an unsaved draft are exempt, so
they work anywhere. onSuccess, onError and onFinally count as part of the press that started them, and
so does onBlur on a field somebody typed into. The validator warns about a write on an event nobody causes.

Record mutations via $action (use these for creating/updating/deleting records):
A RECORD is one stored thing; an ENTITY is its type. Every one of these takes the entity name first
and acts on a record of it.

record.create — creates a record in the current dataset (default) or a specified one:
{ "$action": "record.create", "args": ["EntityName", { "field": "value" }, { "dataset": "datasetStore.rootDataset" }] }
The third argument is an options object. Omit it to write into the space on screen.

record.update — updates one record:
{ "$action": "record.update", "args": ["EntityName", { "$": "item.id" }, { "field": "newValue" }] }
To target another dataset: { "$action": "record.update", "args": ["EntityName", { "$": "item.id" }, { "field": "value" }, { "dataset": "datasetStore.rootDataset" }] }

record.delete — deletes one record:
{ "$action": "record.delete", "args": ["EntityName", { "$": "item.id" }] }

Use dataset: 'datasetStore.rootDataset' for we-root entities (AgentSettings, ChatSession, etc.), and
'datasetStore.personalDataset' for the agent's own content (a note, a Pocket folder). Both are chrome-tier.
Use the default (no dataset) for space-scoped entities (Space, Signal, etc.). The same key $query
takes, and it names the same accessors.

record.* writes directly; recordStore is the form surface over the same job — it derives a form from
the entity's own declaration, so a community's newest entity is creatable with no schema written for
it. Reach for record.create when the template knows the fields, recordStore when a person is filling
them in.

Expressions:
{ "$": "<expression>" }
Every computed value — a condition, a label, a number, a filtered list — is one expression string in a
{ "$": … } token. This is the value layer's whole vocabulary. The node layer ($each, node-level $if,
$routes, $animate…), queries ($query, $queries) and handlers ($action, $setLocal, $toggleLocal…) stay
as tokens; an expression goes anywhere a VALUE goes — a prop, a condition, $each's items, a children
array (rendered as text), a where value, an $action argument.

References — what a name starts from:
  spaceStore.members             a store member (any store in the Stores section; modules.<id>.<key> for a module)
  local.searchText               a $localState or $queries field; dot paths read into object fields
  post.title                     a name bound by $each / $single / $agent through "as" — the default is item
  index, prev                    $each's row position, and the previous row
  me.did, currentDataset         the current agent, and the active dataset
  surface.tier, surface.width    the responsive boundary
  event, arg, result             the callback argument inside a handler, and a settled $action's value
A plain string in an expression is ALWAYS a literal: 'item.name' is five words, item.name is a read.
A plain string in a PROP or in children is text too: "$item.name" renders those ten characters. A
reference is always written { "$": "item.name" }; the validator rejects the old string spelling.
A store's actions are unreachable — spaceStore.createPost reads as nothing; only $action calls.

Operators, in JavaScript's spelling and precedence:
  == !=                          strict equality
  < > <= >=                      numeric comparison
  in                             list membership:  item.role in ['admin', 'moderator']
  ! && ||                        boolean logic. && and || ANSWER WITH A BOOLEAN, never with an operand,
                                 so name || 'Untitled' is true, not a name — the validator warns
  ??                             the fallback-value idiom:  local.name ?? 'Untitled' — for absent only;
                                 an empty string stays empty, so write name ? name : 'Untitled' for both
  test ? a : b                   conditional value
  + - * / %                      arithmetic; + joins strings when either side is one; / by 0 is 0
  `…${expr}…`                    interpolation
  a.name   a[i]                  property and index reads; a missing path is undefined, never an error
  [a, b]   { key: value }        list and object literals — the where-object below is one

Comprehensions — the one place a name is bound, over a list:
  items.filter(x, x.done)          items.map(x, x.name)          items.find(x, x.id == local.selected)
  items.exists(x, x.role == 'admin')                            items.all(x, x.read)
Over something that is not a list: filter and map give [], find gives undefined, exists false, all true.

Functions — the library. f(a, b) and a.f(b) are the same call; a value's own methods are never callable.
Nothing is ever added to the grammar above: a new capability is a function here, or one the host
registers (listed last). Wrong-typed input answers with the empty value of its kind, never an error.
  Lists:
    count(items) — How many entries a list has. Anything that is not a list counts as 0.  e.g. count(spaceStore.members)
    distinct(...lists) — The entries of every list given, each once, in the order first seen. Records compare by `id`, other values by value. Anything that is not a list contributes nothing.  e.g. distinct(local.found.map(r, r.__subjectClass), local.placements.map(p, p.nodeType))
    filter(items, where, limit?) — The entries matching a where-object — the same grammar $query takes. `limit` keeps the first N. Prefer the comprehension `items.filter(x, …)` when the test is not a where-object.  e.g. filter(spaceStore.members, { role: 'admin' }, 5)
    find(items, where?) — The first entry matching a where-object, or undefined. Without `where`, the first entry. Read a field off the result directly: `find(…).id` is undefined when nothing matched.  e.g. find(local.signalTypes, { slug: 'like' }).id
    first(items) — The first entry of a list, or undefined when it is empty.  e.g. first(local.posts).title
    join(items, separator?) — The entries of a list as one string, separated by `separator` (default ', ').  e.g. join(item.tags, ' · ')
    last(items) — The last entry of a list, or undefined when it is empty.  e.g. last(item.messages).text
    reverse(items) — The entries of a list, back to front. A new list — the one given is untouched, so a store array or a query result can be reversed without disturbing anything else reading it.  e.g. reverse(local.utterances)
    split(text, separator?) — The text cut into a list at each `separator` (default ','), each piece trimmed, empty pieces left out — so an empty string is an empty list. The inverse of `join`, for a list held in one string, such as a URL parameter.  e.g. split(routeStore.params.hide).filter(k, k != kind)
    sum(items) — The numbers in a list added together. Anything that is not a number counts as 0, and anything that is not a list sums to 0.  e.g. sum(local.replies.map(r, count(r.comments)))
  Text:
    contains(text, needle) — Whether the text contains `needle`, ignoring case — the same test the where-object `contains` makes.  e.g. contains(item.name, local.search)
    endsWith(text, suffix) — Whether the text ends with `suffix`, case-sensitively.  e.g. endsWith(item.url, '.png')
    lower(text) — The text in lower case.  e.g. lower(item.handle)
    plural(count, one, other) — `one` when count is exactly 1, otherwise `other`.  e.g. plural(count(spaceStore.members), 'Member', 'Members')
    startsWith(text, prefix) — Whether the text starts with `prefix`, case-sensitively — for structured strings such as an ISO date or a URI.  e.g. startsWith(item.startDate, '2026-08')
    trim(text) — The text without leading and trailing whitespace.  e.g. trim(local.search) != ''
    upper(text) — The text in upper case.  e.g. upper(item.code)
  Numbers:
    max(...values) — The largest of the numbers given. Non-numbers count as 0.  e.g. max(local.page - 1, 0)
    min(...values) — The smallest of the numbers given. Non-numbers count as 0.  e.g. min(count(local.rows), 20)
    round(value, digits?) — The number rounded to `digits` decimal places (default 0). Non-numbers round to 0.  e.g. round(item.progress * 100)
  Objects:
    pick(object, keys) — A new object holding only the named keys of `object`. Anything that is not an object gives `{}`.  e.g. pick(profileStore.ownProfile, ['handle', 'avatar'])
  Form state:
    error(field) — A field's first validation message, once it has been touched; empty otherwise. The field is named as a string.  e.g. error('email')
    formValid() — Whether every validated field in the enclosing $localState scope passes.  e.g. formValid()
    touched(field) — Whether the field has been blurred or marked with $touch.  e.g. touched('email')
    valid(field) — Whether every validation rule on the field passes, touched or not. True for a field with no rules.  e.g. valid('email')
  Host functions (this deployment registers them):
    calendarMonth(options?) — The days of a month as rows — { date, day, inMonth, isToday, weekday } — padded to whole weeks. Options: month (YYYY-MM-DD, default today), offset (months from it), weekStartsOn (0 Sunday … 6), fixedWeeks (six rows, default on).  e.g. calendarMonth({ offset: local.monthOffset, weekStartsOn: 1 })
    calendarMonths(options?) — The twelve months of the year an offset lands in — { label, month, year, offset, isThisMonth, isShown } — each carrying its own offset from today, for a jump-to-month picker.  e.g. calendarMonths({ offset: local.monthOffset })
    monthLabel(options?) — The month a calendar is showing, as "August 2026" in the viewer’s language. Same options as calendarMonth.  e.g. monthLabel({ offset: local.monthOffset })
    yearLabel(options?) — The year a calendar is showing, on its own. Same options as calendarMonth.  e.g. yearLabel({ offset: local.monthOffset })
    arrangedBoard(options) — A board worked out from its three subscriptions — { ready, gathers, columns, contents, unplaced, unplacedStates, available, total, involved, filtering, show, dimmed, cardCount, matchedCount, unplacedTotal, rows, cells, rowCounts, flow, awaiting, awaitingOnly }. columns are the caller’s own column records in the board’s order; contents[columnId] is { label, icon, color, lane, arranged, unarranged, count, shown, matched, order }; unplaced is work no column here shows. Options: board (the record with children hydrated), columns (its kind: "column" children), records (everything in scope), states (spaceStore.taskStates). To read it by who is on the work, also pass involvements (an Involvement query), kinds (spaceStore.involvementTypes), people (the chosen DIDs), me (me.did — involved is everyone on a card here, the viewer first) and show: "dim" lists the others in dimmed and moves nothing; "hide" drops them from arranged, unarranged and unplaced while count stays true and shown says how many are drawn; "rows" adds a row per person plus "nobody" — rows are keys, cells[row][columnId] is { arranged, unarranged, count }. A drag in a column showing only part of itself passes contents[columnId].order to arrangeColumn, so the hidden cards keep their places. Where the space’s states ask for agreement (spaceStore.taskFlowEnabled) a card is drawn where its run is, and three more fields answer: flow[cardId] is { to, voters, counted, needs, mine, canApprove, approverKind } for a card waiting on a move — counted is how many of voters count toward needs; awaiting is the cards whose waiting move the viewer’s approval would help; pass awaitingMe: true to draw only those (awaitingOnly says it is on).  e.g. arrangedBoard({ board: first(local.board), columns: local.columns, records: local.pool, states: spaceStore.taskStates }).columns
    involvement(options) — Who is on each record, from the Involvement rows — { byNode, answers, dids }. byNode[recordId] is { people, dids, responsible, reviewing, committed, interested, declined, pairs }: people are { did, kind, name, semantic, reflexive, icon, color, tone }, assignees first then reviewers and so on, and tone is the avatar ring the part wears ("warning" for reviewing, empty otherwise) — pass it as an AvatarStack avatar’s tone; the five lists are DIDs grouped by what each kind means, so a renamed or added kind still lands in the right one; dids is everyone not declined; pairs is every "did|kind" present, for a menu tick with `in`. answers[recordId] is the viewer’s own reflexive answer (going, maybe, …). Options: rows (an Involvement query), types (spaceStore.involvementTypes), me (me.did, who then leads the top-level dids), nodes (record ids the top-level dids is limited to).  e.g. involvement({ rows: local.involvements, types: spaceStore.involvementTypes, me: me.did }).byNode[card.id].responsible
    involvementMenu(options) — The entries of a "who is on this" DropdownMenu for one record: the member a conversation named, when `said` matches exactly one and nobody is doing it yet; "Assign to me" while the viewer is not already on it, then a group per kind the entity is offered that anybody may give (the first open, the rest closed unless somebody holds them), each listing members with their faces — current holders ticked and first, then the viewer, then everyone by name. Every entry carries `kind`, and a toggle `checked`, so one handler serves all: setInvolvement(record, arg.id, arg.kind, !arg.checked). Options: node, entity, rows (an Involvement query), types (spaceStore.offeredInvolvementTypes), members (spaceStore.members), profiles (profileStore.profiles), me (me.did), said (a name somebody said — TaskBlock.assignee).  e.g. involvementMenu({ node: card.id, entity: 'TaskBlock', rows: local.involvements, types: spaceStore.offeredInvolvementTypes, members: spaceStore.members, profiles: profileStore.profiles, me: me.did })
    signalTally(options) — What a record's reactions say, as one number. With `type`, the number THAT type is read as — a toggle counts, a vote nets out, a rating averages, and a community's own `aggregate` wins unless the mode cannot express it. Without a type, how many people reacted at all: records, never values, since a total summing likes and stars and downvotes is not a number. Retired types still count — somebody reacted, and a total that fell when a vocabulary was tidied would be reporting the tidying. Options: signals (the record's `signals`, hydrated), type (a SignalType row).  e.g. signalTally({ signals: row.signals, type: sig })
    reactions(options) — A record's reactions with this agent's own newest answer in place, whether or not it has been read back yet. Every reaction surface draws through it: a press writes a record and the subscription answers about a second later, so without it the glyph stays unfilled and the count stays put and the press reads as having failed. The LIST rather than the count, because the tally, the mark and the control all read it — overlay the count alone and the heart sits unfilled beside a number that moved. Options: signals (the record's `signals`, hydrated), record (its id), type (the SignalType's id), me (me.did).  e.g. reactions({ signals: filter(row.signals, { signalTypeId: sig.id }), record: row.id, type: sig.id, me: me.did })
    reactors(options) — Who reacted with one type and what each gave — { people, total, unresolved }. `people` are { did, name, avatar, value, mine }, the reader first and then by name; `total` counts everybody before any search, which is what "12 people" says. The record already carries this — `include: { signals: true }` hydrates each Signal's author and value — so nothing is fetched; what a schema cannot do is join a DID to a face and a name. `search` narrows by name, and `unresolved` says how many could not be judged because their profile has not arrived. Options: signals (one type's signals, hydrated), profiles (profileStore.profiles), me (me.did), search.  e.g. reactors({ signals: filter(row.signals, { signalTypeId: sig.id }), profiles: profileStore.profiles, me: me.did })
    signalTypesByUse(options) — Reaction types ordered by how many PEOPLE reacted with each, most first — never by what they said, since a total of values cannot compare a rating with a vote and a downvoted type would sort below one nobody has used. Ties keep the order they arrived in, so a panel does not reshuffle as reactions come in. Muted authors are left out of the count. It orders and nothing else: which types a surface draws is a filter, and stays in the schema — which is what keeps an overflow count evaluable, since reordering a list cannot change how long it is. Sorting is here because the expression language has no sort, the grammar is closed, and these types come from a subscription rather than a query that could carry an `order`. Pass `of` — the record's id — and the order SETTLES: it is worked out the first time that record's reactions are drawn and then held, so a reaction somebody withdraws does not slide down the column under their cursor. It has to be held outside the template, because a reaction surface sits inside an `$each` over a query and a subscription hands the renderer fresh objects, which remounts the row and takes any `$localState` with it. Types the settled order has never seen are appended by use, so nothing new is hidden; the order is dropped when the space changes. Options: of (the record whose order this is), types (the rows to order), signals (the record's `signals`, hydrated), muted (spaceStore.mutedDids), limit (keep the first N of that order).  e.g. signalTypesByUse({ of: row.id, types: filter(local.signalTypes, { retired: { not: true } }), signals: row.signals, muted: spaceStore.mutedDids, limit: 4 })
    voices(options) — Whose reactions a weighted score was made from, as a list a reader turns voices up and down in — { did, name, avatar, cards, mean, weight, share, mine, pretend }, the busiest first. `weight` is how much the voice counts (0–100) and `share` its part of everybody's say. Options: summary (what a GraphView's onSeedSummary reported — the canvas seed's `{ type, voices }`), param (the weights as the address holds them, `did=50,did=0`), profiles (profileStore.profiles), me (me.did).  e.g. voices({ summary: local.voiceSummary, param: local.voices, profiles: profileStore.profiles, me: me.did })
    voicesParam(options) — The weights address form with one voice changed — options param, did and weight (0–100) — or, with only (a DID) and voices (the listed rows), every voice at nothing but that one. A voice back at full is left out, so putting everything back leaves a clean address.  e.g. voicesParam({ param: local.voices, did: voice.did, weight: event.detail })
    formatJson(options) — A JSON string indented for reading, or the text unchanged when it will not parse — which is the case worth showing rather than swallowing. Options: text. For displaying a stored blob (an extraction pass’s prompt and response); a schema has no JSON.stringify of its own.  e.g. formatJson({ text: pass.prompt })

The where-object — one grammar shared by filter(), find(), and $query's where. Keys are field names;
values may be expressions (in an expression) or tokens (in a $query):

  { field: 'value' }                       — strict equality
  { field: ['a', 'b'] }                    — set membership (IN); matches any of them
  { field: { not: 'value' } }              — inequality; a list excludes several values
  { field: { contains: 'text' } }          — case-insensitive substring match (strings only)
  { field: { startsWith: 'text' } }        — anchored prefix match, case-SENSITIVE
  { field: { endsWith: 'text' } }          — anchored suffix match, case-SENSITIVE
  { field: { exists: true } }              — non-null / non-undefined presence check
  { field: { exists: false } }             — null or undefined check
  { field: { gte: 10, lt: 50 } }           — a range; lt, lte, gt, gte, any of them together
  { relation: { some: {…} } }              — has at least one linked record matching the clause
  { relation: { none: {…} } }              — has no linked record matching it; { none: {} } is "has none at all"
  { OR: [ {…}, {…} ] }  { AND: [ … ] }  { NOT: {…} }   — combinators; sibling keys are implicitly ANDed

"some" and "none" ask about LINKED RECORDS rather than a field's value, and are the only way to do
so: "posts with no comments", "nodes carrying a relationship of this kind". Without them the caller
fetched everything with its children and counted client-side. An empty clause means "any", so
{ comments: { some: {} } } is "has at least one". They nest — the clause inside one may itself
contain a quantifier — and they run natively in a $query, so nothing is fetched to count.

A key is read as a quantifier because it carries "some" or "none", not because the model says it is
a relation. So a scalar property can never be compared with those two words, and everything else on
a relation-named key stays an ordinary field compare.

A bare list is the positive counterpart of "not" with a list, and the way to fetch a known set:
{ id: ['id1', 'id2', 'id3'] }. Native in a $query. An empty list matches nothing, which is what
"none of these" should mean.

An ABSENT property is the trap worth knowing, and "not" is where a $query and filter() disagree.

A record that never had a property written carries no value for it — a property is stored as a
link, so an unwritten one is simply not there. Three cases, and the middle one differs by where it
is evaluated:

  { field: 'x' }             — does NOT match an absent value. Both agree.
  { field: { not: 'x' } }    — does NOT match an absent value in a $query, on any backend: !=
                               over an unbound value excludes the row, exactly as SQL's
                               three-valued logic excludes NULL. Inside filter() it DOES match
                               (undefined !== 'x'), because filter() is plain client-side
                               comparison — so the same where-object can answer differently in
                               the two places.
  { field: { exists: false } } — means absent, unambiguously — but see the warning below about
                               where it can be used.

A declared "default" does not rescue this. The manifest's default is applied when a record is
CONSTRUCTED, so anything created normally does carry it — but a field added to an entity after
some records already existed reads as absent on every one of them, and the query layer never
consults the default when filtering.

CLEARING is the other way to end up with no value. Writing '' to a property that has one removes
it: the record then reads back as the field's default — usually '' — but no $query matches it, not
{ field: '' } and not { field: { not: 'x' } }. A '' written at CREATION, a declared default of ''
included, is different: it is stored, and both of those match it. So a task nobody was ever
assigned is found by { assignee: { not: 'Ann' } }, and one whose assignee was removed is not.

"exists" IS NOT AVAILABLE IN A $query — only inside filter(), where it is evaluated client-side.
The backend has no such operator, so a $query using one is refused rather than run.

That rules out the obvious idiom for "absent counts as the default":

  { OR: [ { retired: false }, { retired: { exists: false } } ] }   ← NOT usable in a $query

Until the operator exists, the ways to say it are: give the field a default and write the plain
comparison; fetch the candidates and filter() client-side, where "exists" works; or, where the field
is a relation rather than a scalar, ask { relation: { none: {} } }, which IS native.

startsWith/endsWith are case-sensitive where contains is not: they match structured strings against
a known prefix (an ISO date, an id out of a URI). They are NOT native to the backend either, so a
$query using one is refused — use contains there; inside filter() they are evaluated client-side.

lt/lte/gt/gte compare a number with a number, and a string with a string as text. Text order is
what makes dates work: WE writes a day as YYYY-MM-DD and a moment as YYYY-MM-DDTHH:mm, and those sort
in time order, so { dueDate: { gte: '2026-09-15', lt: '2026-10-01' } } is "due in the second half of
September" — including a task due '2026-09-30T18:00'. A mixed pair never matches: a number bound
against a field holding the string '12' answers false, rather than guessing which you meant.

In a $query a NUMBER bound is native and a STRING bound is refused — the backend compares numbers
only. So a date range in a $query does not run yet; fetch the candidates and filter() client-side,
where it works, or bound the query by something numeric. A numeric range (a price, a count, a
rating) runs natively either way.

OR/AND/NOT cost a query nothing in sort pushdown: a filter with an OR and a sort behaves like any
other.

Examples:
{ "$": "filter(spaceStore.members, { role: 'admin' })" }
{ "$": "filter(spaceStore.members, { location: { exists: true }, handle: { contains: local.searchText } })" }
{ "$": "filter(local.dayEvents, { startDate: { startsWith: cell.date } }, 2)" }        — the first two only
{ "$": "filter(local.tasks, { dueDate: { gte: local.weekStart, lt: local.weekEnd } })" }
{ "$": "find(local.signalTypes, { slug: 'like' }).id" }                                — undefined when nothing matches
{ "$": "count(local.rows) > 0 && local.searchText != ''" }
{ "$": "item.author == me.did ? 'mine' : 'theirs'" }
{ "$": "`${count(spaceStore.members)} ${plural(count(spaceStore.members), 'Member', 'Members')}`" }
{ "$": "spaceStore.members.filter(m, m.did != me.did).map(m, m.handle).join(', ')" }
{ "$": "post.author in spaceStore.mutedDids" }

Rules:
- An expression naming event/arg/result at the TOP LEVEL of an $action's args, or as a $setLocal
  "value", is evaluated when the handler fires. Nested inside another token it is evaluated at render
  time against no event and becomes a constant — the validator rejects that.
- The validator reports every mistake with a column: an unknown name (with "did you mean"), an unknown
  store member, an undeclared local, an unknown function, a wrong argument count, prototype access.
- No new value operators will be added and no new syntax. Computation the library lacks is a function
  the host registers, catalogued under "Host functions" above.

Query (data retrieval):
{ "$query": { "entity": "EntityName", "where": { "field": "value" }, "limit": 10, "order": { "field": "asc" } } }
Queries the current dataset for entity instances. Always returns an array.
Options: entity (required), where, order, limit, offset, include, scope, dataset, subscribe.
select names the fields each row carries — properties, and relations as their target ids — and
`id` always comes: { "select": ["title", "createdAt", "participants"] }. Without it a row carries
every field, relation id lists included, and a container's children is the id of everything in it.
A list of containers (CollectionBlock) names what its rows draw; a single-record read need not.
A field left out reads as absent, so select what every expression on the row reads.
subscribe defaults to true — reactive live updates. Set subscribe: false to do a one-time fetch.
subscribe may also be an EXPRESSION, which is how a surface follows its subject only while the
subject is still changing: { "subscribe": { "$": "modules.transcribe.callOnScreenLive" } } reads a
finished call's transcript with no subscription at all, and follows a live one. Reach for it on
anything whose record settles — a past call, an archived thread — where a live query would have the
backend re-running it for an answer that cannot change. Turning falsy releases the subscription
rather than merely ignoring it; an expression that has not resolved yet counts as not live, so the
worst case is one fetch and a re-ask rather than a subscription nobody wanted.
By default $query targets the current dataset. Use dataset to query a different dataset — required
when reading entities from an external app (e.g. Flux) that is open as a WE space:
{ "$query": { "entity": "Channel", "dataset": { "$": "currentDataset" } } }

entity may be an expression rather than a literal name — what lets a list render records of a type
the template was not written for. Put the query inside an $each over a list of model names and read
the row:
{
  "type": "$each",
  "props": { "items": { "$": "shapeStore.extractionTargets" }, "as": "target" },
  "children": [{
    "type": "Column",
    "$queries": { "found": { "entity": { "$": "target" }, "order": { "createdAt": "asc" } } },
    "children": ["…one group per model, each with its own subscription…"]
  }]
}
Pair it with recordStore.displays[target] to draw the rows, and the group renders a model a
community defined this morning with no template change (see "A record of any type").
USE A LITERAL WHEREVER THE TYPE IS KNOWN. The validator cannot check a name it only sees at
runtime, so a typo fails as a silently empty list rather than as an error — and a name that has not
resolved yet reads as "not ready", so the query simply waits. Note the counts of such a set cannot
be totalled: each group is its own subscription and a schema cannot sum a list of queries whose
length it does not know, so put a count inside each group rather than above them.

entity may also be a LIST of names — literal, or an expression answering with one — which asks the
same question of every entity in it and answers with ONE list. Reach for it when the rows belong
together rather than in a group per model: a mixed feed, "what did this call produce", "which kinds
are on this canvas", or anything whose total or emptiness you need to read above the rows.
{
  "$queries": {
    "produced": {
      "entity": { "$": "shapeStore.extractionCandidates" },
      "scope": { "anchor": "CollectionBlock", "via": "children", "anchorId": { "$": "local.callId" } },
      "order": { "createdAt": "desc" },
      "limit": 50
    }
  }
}
- Every row carries the entity it came from as __subjectClass — { "$": "row.__subjectClass" } — the
  same key a polymorphic include already sets, so recordStore.displays[row.__subjectClass] draws it.
- order and limit apply to the WHOLE list, not to each entity. offset is refused.
- A record two entities both answer with (an abstract model and a concrete one) is listed once, as
  the first entity in the list.
- Nothing is shown, and local.<name>Loaded stays false, until every entity has answered once.
- An EMPTY list is an answer: loaded, no rows. So { "$": "local.producedLoaded && !count(local.produced)" }
  is a sound empty-state condition even when the list of kinds is computed.
- One entity that cannot be read is reported and counts as having no rows; the others still show.
- A literal list is checked name by name, like a literal name.
To read the distinct kinds out of it, or merge them with kinds from another list, use distinct():
{ "$": "distinct(local.produced.map(r, r.__subjectClass), local.placements.map(p, p.nodeType))" }

Backend-neutral identity & dataset refs — prefer these over backend-store paths inside $query and conditions:
- currentDataset — the currently active dataset. Use as a dataset value.
  A host store's dataset accessor (e.g. `dataset: 'datasetStore.marketplaceDataset'`) works as a dataset value too.
  When passing a dataset to a *component prop* rather than a query, append `.handle` — component props take the
  backend's own dataset handle: { "dataset": { "$": "datasetStore.currentDataset.handle" } }.
- me — the current agent's identity object. Use me.did for their DID (ownership checks, author filters, e.g. { "$": "post.author == me.did" }); me.handle / me.avatar for profile fields once loaded.

Eager-loading relations with include (most common relational pattern):
include hydrates related model instances in the same query — no extra fetches needed.
Relation names come from the HasMany relations listed for each model in externalEntities.

Simple include — hydrate all related instances:
{ "$query": { "entity": "Channel", "include": { "conversations": true } } }
Each item in the result will have a conversations array of hydrated Conversation objects.

An included relation is the RECORD, not its id — and without the include the same field is the id.
So a comparison written for one breaks silently against the other: with include: { item: true },
row.item == x never matches and a where-object { item: x } finds nothing. Compare row.item.id, or
in a where-object over included rows, use a comprehension: local.loans.find(l, l.item.id == x).
The validator warns about both.

Sub-query include — filter, sort, or limit the related records:
{ "$query": { "entity": "Channel", "include": { "conversations": { "order": { "createdAt": "desc" }, "limit": 10 } } } }

Nested include — hydrate relations of relations:
{ "$query": { "entity": "Channel", "include": { "conversations": { "include": { "messages": true } } } } }
Nesting can go as deep as needed. Each level adds one batched fetch (not N+1). Two limits, both silent
rather than refused, so keep clear of them:
- A $-prefixed projection (below) works only at the TOP level of include. Written inside a nested
  include it is dropped: the query succeeds and the field is simply absent.
- Below an UNTYPED relation (see "include works with an UNTYPED relation" below), only a TYPED
  relation can be nested. Nesting another untyped one fails the whole query the moment any member has
  something in it — so it works on an empty board and breaks on the first card.

Count projection — add a derived numeric field:
{ "$query": { "entity": "Post", "include": { "$likeCount": { "from": "likes", "count": true } } } }
The $-prefixed key becomes a new field on each result item (e.g. item.$likeCount = 42).

Sorting by a count projection — order can reference a $-prefixed count key directly, sorting by the aggregate:
{
  "$query": {
    "entity": "Post",
    "limit": 20,
    "order": { "$likeCount": "desc" },
    "include": { "$likeCount": { "from": "likes", "count": true } }
  }
}
Requirements: only a single order key is supported when it targets a projection (mixing it with a second sort key falls back
to a plain property sort), and the query must also specify limit or offset — without one the count isn't computed yet at
sort time and the order silently has no effect. Always pair count-projection ordering with a limit.
Combine with a ternary for a user-togglable sort field (e.g. "newest" vs "most liked"):
{
  "order": { "$": "local.sortField == 'likes' ? { $likeCount: local.sortDirection } : { createdAt: local.sortDirection }" }
}

Sorting by a related model property — order can reference a dotted "relation.property" path for a HasOne/HasMany
relation declared on the model, sorting by a scalar property on the related instance:
{
  "$query": {
    "entity": "Space",
    "limit": 20,
    "order": { "location.country": "asc" },
    "include": { "location": true }
  }
}
Same requirements as count-projection ordering above: only a single order key, and pair with limit/offset — without
one the relation data isn't attached yet at sort time and the order silently has no effect. include isn't required
for the sort itself (the relation is resolved from the model's declared shape), but you'll usually want it anyway to
read the field in the UI (e.g. { "$": "space.location.country" }).
Combine with a ternary the same way as count-projection ordering to let the user toggle between sort fields.

Single-item projection — add a derived field that resolves to one instance or null:
{ "$query": { "entity": "Post", "include": { "$myLike": { "from": "likes", "where": { "author": { "$": "me.did" } }, "limit": 1 } } } }
With limit: 1 the field unwraps to T | null instead of an array.

include works with an UNTYPED relation too — one whose target model class is not declared, like a
collection's children. Each member is read as the class it actually is, so one query returns a
post's text blocks, images and tasks together, each with its own fields. Every member carries its
type, so a card can pick a display per row rather than assuming one.

That makes include the right tool for a FEED, where the alternative is one drill-down per parent:
{ "$query": { "entity": "CollectionBlock", "where": { "type": "root" }, "include": { "children": true } } }

A scope drill-down is still right on a DETAIL route, where the parent is fixed and its children are
the whole subject — it is a narrower question, not a worse one. For external models, check the
externalEntities listing: relations marked "→ EntityName" name their target, and untyped ones are
read polymorphically.

An ORDERED collection comes back in the order somebody arranged it — CollectionBlock.children is the
one that matters, since the blocks of a post are a sequence its author chose rather than the order
they happened to be typed in. Nothing to write in the query; the model declares it.

Relational queries — fetch a parent record's children (drill-down navigation):
{ "$query": { "entity": "Conversation", "scope": { "anchor": "Channel", "via": "conversations", "anchorId": { "$": "channel.id" } } } }
scope.anchor is the parent entity type; scope.via is its relation whose targets are this query's entity (the
HasMany relation listed for that entity in externalEntities); scope.anchorId is the parent record's id (typically
from a $each context variable or a route segment). The adapter resolves the relation to a backend handle —
no protocol details live in the template.
Use this pattern when navigating to a detail route and loading only that record's children.
For external-app datasets, always add dataset: { "$": "currentDataset" }.

Reading a TREE rather than one record's children — the same scope, with one more key:

  anchorId may be a LIST, which asks the same question of every anchor at once. One query for a
  whole level of a tree rather than one per parent, which also means one subscription instead of
  one per parent.
  { "scope": { "anchor": "CollectionBlock", "via": "comments", "anchorId": { "$": "local.replies.map(r, r.id)" } } }

  "levels": [10, 5, 3] walks the relation depth by depth — ten children, five under each of those,
  three under each of THOSE — and the backend answers once. This is how to read a comment thread, a
  knowledge map's neighbourhood, or any nested containment: bounded at every depth and one request,
  where asking level by level from the template costs a round trip each and draws the tree a layer
  at a time.
  { "scope": { "anchor": "CollectionBlock", "via": "comments", "anchorId": { "$": "card.id" }, "levels": [10, 5, 3] } }

  "transitive": true is the same walk with no bound — every descendant, however deep. Right for a
  count, and for a small tree you mean to draw whole; wrong as a default, since it fetches a subtree
  to draw part of one.

  "limitPerAnchor": 5 caps results per anchor for a single level. Note it is NOT a substitute for
  "levels": a walk from one anchor has one group, so it would cap the total instead of the breadth
  at each depth.

  "direction": "in" searches among the records that point AT the anchor, rather than the ones it
  points at.

A walked or transitive result is FLAT and does not describe its own shape — a row says it is under
the anchor, never where. Include the inverse relation to rebuild the tree: every WeNode carries
inReplyTo, the reverse of comments, so a row names its own parent.
  "include": { "inReplyTo": true }
Then each level is a filter over the one result:
  { "$": "local.threadRows.filter(r, r.inReplyTo.id == (card.id))" }
PARENTHESISE the anchor when it is anything but a plain path — `==` binds tighter than `?:`, so a
ternary spliced in bare turns the predicate into its own result, which is truthy for every row.

A count over a whole subtree is the same idea in a projection:
  "include": { "$descendants": { "from": "comments", "count": true, "transitive": true } }
It rides in the read already being made, so "42 replies" on a collapsed branch costs no extra query
— where count(row.comments) is the direct children only and would say 3.

Local state (scoped ephemeral state):
Declare on any node: "$localState": { "name": { "type": "string", "initial": "" } }
Supported types: "string", "boolean", "number", "function", "object", "array".
"array" is a set of values — the type $toggleLocalIn writes and `in` reads. Use it for per-row state
(which rows are open, which are selected) where the rows come from data.
Two opt-in persistence tiers (see docs/architecture/routing-and-view-state.md for the full rules):
- "syncParam": "<param>" mirrors the field into a URL query parameter — for VIEW STATE (selected
  content type, sort, filters, search): what a shared link's recipient should see exactly as the
  sender does. Object form { "name": "type", "push": true } adds a Back entry on change (use for
  content-type switches; sort/filter changes keep the default replace). A field back at its
  declared initial removes its param, keeping URLs clean.
  Example: { "type": "string", "initial": "posts", "syncParam": { "name": "type", "push": true } }
- "persist": "<key>" keeps the field on the device (localStorage) — for PREFERENCES (display
  density, collapsed rails): things a shared link must NOT impose on its recipient. The key is
  explicit and deployment-global (namespace it, e.g. "cards.displayMode").
Precedence on mount: URL param > persisted value > declared "initial"; $resetLocal clears both.
Neither applies to "file"/"function" fields. Open-modal and in-flight flags stay plain (ephemeral).
The deciding question: "if I sent this URL to someone, should they see the effect?" — yes: syncParam;
no but future-me should: persist; no one: plain.
Links may also carry ?template=<id> and ?theme=<id> — the shell applies them when the recipient has
them and warns (toast) when not. Templates never handle these params themselves.
Read:  { "$": "local.name" } — the signal value (reactive).
       { "$": "local.name.nested.path" } — dot paths read into object-typed fields (reactive).
Write: { "$setLocal": "name", "value": { "$": "event.target.value" } } — event handler that sets what the expression computes when it fires, with event in scope.
       { "$setLocal": "name", "value": "literal" } — sets to a literal value (string, number, boolean, null, object).
       { "$setLocal": "name", "merge": { "field": { "$": "event.detail" } } } — shallow-merges fields into an object-typed signal; each field is a literal or an expression. Use for partial updates to object state.
       { "$setLocal": "name", "value": { "$": "local.name + 20" } } — arithmetic on the current value, for paging and counters.
Note "value" is a LITERAL unless it is an expression: any other token object inside it is stored as the object, not as what it would resolve to.
Toggle: { "$toggleLocal": "fieldName" } — toggles a boolean field (equivalent to setting it to !current). Use for show/hide, open/close, expand/collapse patterns.
Toggle one of many: { "$toggleLocalIn": "fieldName", "value": { "$": "group.id" } } — adds the value to an
  array-typed field, or removes it if already there. Read it back with `in`:
  { "$": "group.id in local.collapsedGroups" }.
  This is how PER-ROW state works when the rows come from data. $localState field names are fixed
  when the template is written, so "expanded?" cannot be a boolean per row for rows that come from a
  $query or a store — there is no name to give them. Hold the ids instead:
    "$localState": { "collapsedGroups": { "type": "array", "initial": [] } }
  A fixed, known-in-advance set of sections is still better served by one boolean each.
Call function: { "$callLocal": "fieldName" } — event handler that calls the function stored in a function-typed local field.
  Used when a child component needs to trigger a callback passed in via $localState.
  The field must be declared as type: 'function' and set via $setLocal.
  Example: { "onClick": { "$callLocal": "onConfirm" } }
State is created on mount and destroyed on unmount. Nested $localState declarations merge, inner fields shadow outer.
Local values can be used in $action args: { "$action": "store.method", "args": [{ "$": "local.name" }] }

Object-typed local state (consolidating related scalar fields):
When several related fields share a common condition on their initial values (e.g. all null/empty when a store value is absent), prefer a single "object" field seeded from the store, then read sub-fields with dot-notation and write with merge.
Example — location object (replaces 5 separate scalar fields with conditional initials):
  "$localState": { "location": { "type": "object", "initial": { "$": "spaceStore.currentSpace.location" } } }
  Read:  { "$": "local.location.latitude" }, { "$": "local.location.city" }
  Write (picker confirm): { "$setLocal": "location", "value": { "$": "event.detail" } }
  Write (partial edit):   { "$setLocal": "location", "merge": { "city": { "$": "event.detail" } } }
  Write (clear):          { "$setLocal": "location", "value": null }
  Condition (has location): { "$": "local.location" }
Use "object" whenever you would otherwise write 3+ related scalar fields each needing a conditional initial value.

Hoisted query state ($queries):
Declare on any node to run reactive subscriptions at the node root and expose results under local.
Solves two problems: avoids N duplicate subscriptions inside $each loops, and makes query results available to conditions.
"$queries": { "signalTypes": { "entity": "SignalType", "subscribe": true } }
Results are injected into local as read-only reactive arrays, read as { "$": "local.signalTypes" }.
Query options are identical to $each's $query prop (entity, where, order, limit, include, dataset, subscribe).
Each entry also exposes a read-only boolean local.<name>Loaded — false until the first result set (or
error) arrives, then true for good. Gate a loading skeleton on it so the empty state only ever
asserts "loaded and empty", never "not answered yet":
{ "type": "$if", "props": { "condition": { "$": "local.signalTypesLoaded" }, "then": <list-or-empty>, "else": <skeleton> } }
$queries and $localState share the same local namespace — avoid duplicate names across both.
$setLocal will warn and no-op on $queries entries (they are read-only).
A query's where or scope may read a sibling declared on the same node — { "anchorId": { "$":
"first(local.board).gathers" } } — and re-runs when that sibling answers. The order the entries are
written in does not matter.
An operand that has not resolved yet is PRUNED rather than sent, and pruning WIDENS: a where loses
the condition, a scope is dropped and the query is space-wide. Right for an optional filter; wrong
for a query whose scope is about to exist, which would draw everything for a frame and then narrow.
Give such a query "when": { "$": "local.boardLoaded" } and it is not asked until the condition is
truthy — the result stays empty and local.<name>Loaded stays false, so a loading state can hold.
A BOUND is the exception, and the only one: an unresolved "limit" or "offset" does NOT widen — the
query is not asked at all, exactly as a falsy "when" leaves it unasked, and it runs once the bound
arrives. Widening a filter answers a broader question, which is visible; widening a bound asks the
backend for everything there is, which is not. So an expression-valued limit costs at worst one
empty frame, never an unbounded fetch.
A $query cannot be read inside an expression — a question for the backend is hoisted here and read
back through local. Use count() for conditional visibility:
{ "condition": { "$": "count(local.signalTypes)" } }
Example:
{
  "$queries": { "signalTypes": { "entity": "SignalType", "subscribe": true } },
  "type": "Column",
  "children": [
    {
      "type": "$each",
      "props": { "items": { "$": "local.signalTypes" }, "as": "sig" },
      "children": [...]
    }
  ]
}

Boolean toggle pattern (show/hide comments, expand/collapse sections, etc.):
{
  "$localState": { "showComments": { "type": "boolean", "initial": false } },
  "children": [
    {
      "type": "we-button",
      "props": {
        "variant": "ghost",
        "onClick": { "$toggleLocal": "showComments" }
      },
      "children": [{ "type": "we-icon", "props": { "name": "chat-circle" } }]
    },
    {
      "type": "$if",
      "props": {
        "condition": { "$": "local.showComments" },
        "then": { "type": "Column", "children": [{ "type": "we-text", "children": ["Comments visible"] }] }
      }
    }
  ]
}

Form validation (extends $localState):
Declare validation rules on fields:
"$localState": {
  "email": {
    "type": "string",
    "initial": "",
    "validate": [
      { "rule": "required", "message": "Email is required" },
      { "rule": "pattern", "value": "^[^@]+@[^@]+$", "message": "Invalid email" }
    ]
  }
}

Built-in rules: required, minLength (value: N), maxLength (value: N), min (value: N), max (value: N), pattern (value: regex string), match (field: otherFieldName). All accept optional "message" override.

Read functions (in an expression):
{ "$": "error('fieldName')" } — first validation error message (only shown after field is touched), or "".
{ "$": "valid('fieldName')" } — true if all rules pass (regardless of touched state).
{ "$": "touched('fieldName')" } — true after the field has been blurred/touched.
{ "$": "formValid()" } — true if ALL validated fields in the current $localState scope pass.

Action tokens:
{ "$touch": "fieldName" } — marks a single field as touched (in onBlur; opt-in, see below).
{ "$touch": "$all" } — marks all fields in scope as touched (use before submit guard).
{ "$resetLocal": "$scope" } — resets all fields to initial values and clears touched state.

Handler arrays (compose multiple actions on one event):
{ "onClick": [{ "$touch": "$all" }, { "$if": { "condition": { "$": "formValid()" }, "then": { "$action": "store.submit", "onSuccess": [{ "$setLocal": "modalOpen", "value": false }] } } }] }
Array entries execute sequentially. { "$if": { "condition", "then", "else" } } in a handler position runs one side or the
other when the event fires — its condition may read event. It is the one place $if is a token rather than a node.
Prefer onSuccess over a bare $setLocal before the $action — the bare form closes the modal immediately (losing the loading spinner); onSuccess waits for the Promise to resolve.

Typical form pattern — validate on submit:
{
  "$localState": {
    "name": { "type": "string", "initial": "", "validate": [{ "rule": "required" }] },
    "submitting": { "type": "boolean", "initial": false }
  },
  "children": [
    {
      "type": "we-form-field",
      "props": { "label": "Name", "error": { "$": "error('name')" } },
      "children": [{
        "type": "we-input",
        "props": {
          "value": { "$": "local.name" },
          "onInput": { "$setLocal": "name", "value": { "$": "event.detail" } }
        }
      }]
    },
    {
      "type": "we-button",
      "props": {
        "loading": { "$": "local.submitting" },
        "disabled": { "$": "local.submitting" },
        "onClick": [
          { "$touch": "$all" },
          { "$if": { "condition": { "$": "formValid()" }, "then": { "$action": "store.save", "args": [{ "$": "local.name" }], "onSuccess": [{ "$setLocal": "submitDone", "value": true }] } } }
        ]
      },
      "children": ["Submit"]
    }
  ]
}

The submit button is disabled only while the request is in flight — NOT on { "$": "!formValid()" }.
Those two are mutually exclusive. A button disabled while the form is invalid can never be clicked in the one
state where { "$touch": "$all" } would reveal something, so the guard chain becomes dead code and blur is left
as the user's only feedback path. Choose one shape:
  - Validate on submit (above). The button is always clickable and the errors appear on the click that was
    refused, which is where the user asked the question.
  - Hard gate: "disabled": { "$": "!formValid()" }, and then drop { "$touch": "$all" } as dead
    and wire "onBlur": { "$touch": "fieldName" } per field — otherwise no error is ever reachable.

"onBlur": { "$touch": "fieldName" } is an opt-in, not boilerplate. It earns its place on long multi-field forms
where a field is worth judging the moment it is left — a "match" rule on a confirm-password field, say. On a
short form it fires an error at someone who merely clicked through a field they had not filled in yet.

No validation, just a precondition (sign-in, search, any single-field submit):
When nothing about the value is locally judgeable — a password is only wrong once the backend says so — skip the
validation machinery and gate on the value itself:
{
  "$localState": { "password": { "type": "string", "initial": "" } },
  ...
  "disabled": { "$": "!local.password" }
}
A "required" rule here would exist only to drive "disabled", and its message is then one stray { "$touch": … }
away from telling the user "Password is required" about a field they simply have not typed into yet.

## Block-level Dynamic Structures

Block-level structures use "type" starting with "$" for dynamic rendering of schema nodes.

Each loop:
{ "type": "$each", "props": { "items": { "$": "storeName.arrayProperty" }, "as": "itemName" }, "children": [ ... ] }
Renders children once for each item. The "as" name becomes a name expressions read — { "$": "itemName.title" }. Defaults to "item" — omit "as" unless you need a different name.

Each row also gets two names describing its position in the list:
- index — the 0-based position.
- prev — the previous item, absent on the first row. Read fields off it like any name: { "$": "prev.author" }.

prev is what makes **grouping** expressible — collapsing consecutive rows by the same author so
a run of messages shows one avatar and byline instead of repeating them. Without it a row can only
ask about itself, and the compact form is unreachable by any prop or theme:
{
  "type": "$if",
  "props": {
    "condition": { "$": "message.author == prev.author" },
    "then": { "...": "compact row — no avatar, no byline" },
    "else": { "...": "full row" }
  }
}
The first row has no prev at all, so the condition is false there and it keeps its byline —
which is what a feed wants, and why absent must not read as "same as the last item".

Both shadow in a nested $each, exactly as the item does: the inner index restarts at 0.

Conditional rendering:
{ "type": "$if", "props": { "condition": ..., "then": { ... }, "else": { ... } } }
Renders "then" node if condition is truthy, else renders "else" node.
Supports enterTransition / exitTransition for CSS animations when the node mounts/unmounts.
TransitionConfig = TransitionEffect | TransitionEffect[]
TransitionEffect = { type: 'fade'|'slide'|'scale'|'reveal'|'pulse', duration?: ms, easing?: string, delay?: ms, direction?: 'left'|'right'|'up'|'down', distance?: string, axis?: 'block'|'inline' }
fade controls opacity only; slide/scale control transform only. pulse is a persistent looping animation (not a one-shot transition) — starts once entered, stops on exit; direction/distance don't apply (default duration 1200ms, easing 'ease-in-out'). Compose fade/slide/scale together in an array; pulse is typically used alone.
Example: enterTransition: [{ type: 'fade', duration: 300 }, { type: 'slide', direction: 'up', distance: '40px', duration: 400 }]
Example (pulse): enterTransition: { type: 'pulse', duration: 1500 }

reveal — opening and closing in place:
reveal is the size axis the others lack: it eases the element open to the size its content actually
wants, and closed again. Use it for anything that opens in place — a disclosure, an accordion
section, a "show more", a sidebar label appearing as the rail expands. axis: 'block' (the default)
opens downward; axis: 'inline' opens sideways.
Example (disclosure): enterTransition: [{ "type": "reveal", "duration": 300 }, { "type": "fade", "duration": 180 }]
Example (label beside an icon): enterTransition: { "type": "reveal", "axis": "inline", "duration": 250 }
Do NOT hand-roll this with maxHeight and a transition string. A guessed maxHeight applies the easing
curve to the guess rather than to the real height, so most of the duration is spent crossing space
that isn't there, and it breaks silently the day the content grows past the guess.
reveal composes with fade exactly as slide does. Pair them: opening a box that is fully opaque from
the first frame reads as a jump, however smooth the size change is.
A reveal in an exitTransition also decides when the node unmounts — the node stays mounted for the
longest effect in the config, so the collapse finishes before the content is removed.

Viewport / mount / condition animation (child always in DOM):
{ "type": "$animate", "props": { "condition"?: SchemaProp, "scrollReveal"?: true | number, "scrollLeave"?: true | number, "scrollPast"?: string, "enterTransition"?: TransitionConfig, "exitTransition"?: TransitionConfig }, "children": [<node>] }
The child is always mounted. fade/slide/scale are CSS transitions (opacity/transform); reveal animates the element's own size; pulse is a real CSS @keyframes loop — use this for scroll-reveal effects.
Do NOT use $animate when the child should be absent from the DOM. Use $if for conditional DOM presence.
For an open/close that must NOT destroy what is inside it — a section holding a scroll position, a
half-typed field, or a live subscription a collapsed row shouldn't tear down — use $animate with
condition rather than $if, which unmounts the content when closed.
condition works like $if's condition (an expression), except the child
is never unmounted: only enterTransition/exitTransition replay as it changes. The initial render
already matches whatever the condition is at mount — a node that starts open does not flash
closed-then-open, and one that starts closed does not briefly show its content first.
When exitTransition is omitted, closing reuses enterTransition (mirrored), the same fallback $if uses.
A reveal clips a closed section to zero size, so it is already unreachable; without one (a plain fade),
the wrapper's pointer-events follow the condition too, so a fully transparent closed section can't be
clicked through.
condition is mutually exclusive with the scroll triggers below and, when present, takes over as the
sole trigger — scrollReveal/scrollLeave/scrollPast are ignored on that node.
scrollReveal: true fires enterTransition when the element enters the viewport.
scrollReveal: -100 fires 100px before the element would enter (negative = earlier reveal).
scrollLeave fires exitTransition when the element leaves the viewport.
scrollPast: "element-id" watches a sentinel element (by DOM id) go past the $animate element itself.
  enterTransition fires once the sentinel has scrolled above the $animate element's top edge (or out of
  the viewport) — so a sentinel sliding under a sticky bar counts as gone the moment it does.
  exitTransition fires when the sentinel comes back below it (user scrolled back up).
  The sentinel may mount later than the $animate node; it is picked up when it appears.
  Use this for sticky headers: place a zero-height sentinel div at the bottom of the non-sticky header section,
  then wrap the mini-profile in $animate with scrollPast pointing to that sentinel's id.
  scrollPast is mutually exclusive with scrollReveal/scrollLeave.
Without condition or a scroll trigger, the enterTransition runs once on mount.
Only one child node is supported.
Example (condition-driven disclosure — a collapsible group whose rows hold live store bindings and
must not resubscribe every time it opens):
{
  "type": "$animate",
  "props": {
    "condition": { "$": "!local.sectionCollapsed" },
    "enterTransition": { "type": "reveal", "duration": 250 }
  },
  "children": [{ "type": "$each", "props": { "items": { "$": "listStore.items" }, "as": "item" },
    "children": [{ "type": "we-text", "children": [{ "$": "item.name" }] }] }]
}
Example (scroll-reveal):
{
  "type": "$animate",
  "props": {
    "scrollReveal": -100,
    "enterTransition": [
      { "type": "fade", "duration": 600, "easing": "ease-in-out" },
      { "type": "slide", "direction": "left", "distance": "200px", "duration": 1000, "easing": "ease-in-out" }
    ]
  },
  "children": [{ "type": "SomeCard", "children": [] }]
}
Example (sticky header mini-profile):
Place a sentinel at the bottom of the header, reference it in the sticky nav:
{ "type": "div", "props": { "id": "header-sentinel" }, "styles": { "height": "0px", "pointerEvents": "none" } }
{
  "type": "$animate",
  "props": {
    "scrollPast": "header-sentinel",
    "enterTransition": { "type": "fade", "duration": 250 },
    "exitTransition": { "type": "fade", "duration": 200 }
  },
  "children": [{ "type": "Row", "props": { "ay": "center", "gap": "300" }, "children": [
    { "type": "we-avatar", "props": { "image": { "$": "space.avatar" }, "size": "sm" } },
    { "type": "we-text", "props": { "fontWeight": "600" }, "children": [{ "$": "space.name" }] }
  ]}]
}

Single model item (load one record, render children with it in context):
{
  "type": "$single",
  "props": {
    "item": { "$query": { "entity": "EntityName", "params": { ... }, "subscribe": true } },
    "as": "profile"   // context key for children — default: 'item'
  },
  "children": [{ "type": "we-text", "children": [{ "$": "profile.username" }] }]
}
Renders nothing until a matching record is found. Like $each but for a single result.
query options (entity, params, include, dataset, subscribe) work identically to $query.

Route outlet:
{ "type": "$routes" }
Indicates where nested routes should render within a layout.

Responsive boundary:
{ "type": "$surface", "props": { "as": "pane" }, "children": [ ... ] }
A box the content inside it measures itself against. Everything inside it — `*UpProps` on any
descendant, and `surface.tier` read in an expression — is answered by THIS box rather than by the
window or the page.

The host already puts one wherever it mounts a schema tree (the template area, the shell overlays,
every docked module panel), so an ordinary template needs none: `mdUpProps` works out of the box.
Declare one when a *part* of your layout should adapt to itself — a two-pane workspace whose right
pane is narrow while the page is wide. Nesting works; the innermost surface wins.

`as` names the context key (default `surface`), so a nested one can be addressed separately.
Read it with `surface.tier` (`base` | `sm` | `md` | `lg`) or `surface.width` (px):

{ "type": "$if", "props": { "condition": { "$": "surface.tier == 'base'" }, "then": <drawer>, "else": <sidebar> } }

USE THIS SPARINGLY, and only for a genuinely different tree. `$if` unmounts and rebuilds its
subtree when the condition changes, which loses scroll position, half-typed input and any live
resource inside it. For different *values* — padding, gap, width, font size — use `*UpProps`, which
is pure CSS and remounts nothing. See "Which mechanism to reach for" in the Design System Props
section.

Module slot outlet:
{ "type": "$slot", "props": { "anchor": "call-controls" } }
Renders whatever other feature modules have contributed to that anchor, in order. Only meaningful
inside a module's own chrome: the module declares the anchor name in its `anchors` list and marks
where contributions land with this. Resolves to nothing when no module has contributed — no empty
container, no gap. Templates have no use for it; chrome is the host's and the modules', not a
template's.

---

## Component Registry

Most @we/primitives also accept Design System Props (see next section for details and exceptions).

@we/primitives:
- we-alert (DesignSystemElement)
  Props: variant: 'neutral' | 'primary' | 'success' | 'warning' | 'danger' = 'primary', appearance: 'soft' | 'accent' = 'soft', dismissible: boolean = false
- we-audio (LayoutVisualElement)
  Props: src: string = '', controls: boolean = false, preload: 'none' | 'metadata' | 'auto' = 'metadata', autoplay: boolean = false, loop: boolean = false, muted: boolean = false, stream?: MediaStream | null | undefined
- we-avatar (LayoutVisualElement)
  Props: image: string = '', hash: string = '', initials: string = '', icon: string = '', size?: 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | '{css-length}' | undefined, clickable: boolean = false, ringColor: string = '', ringWidth: string = '', edgeColor: string = ''
- we-badge (DesignSystemElement)
  Props: variant: 'neutral' | 'primary' | 'success' | 'warning' | 'danger' = 'neutral', appearance: 'soft' | 'solid' = 'soft', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md'
- we-blockquote (DesignSystemElement)
- we-button (DesignSystemElement)
  Props: variant: 'primary' | 'secondary' | 'ghost' | 'success' | 'danger' | 'outline' | 'bare' = 'primary', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md', text?: string | undefined, label: string = '', expanded?: boolean | undefined, href?: string | undefined, disabled: boolean = false, loading: boolean = false, gradient: boolean = false, square: boolean = false
- we-checkbox (DesignSystemElement)
  Props: checked: boolean = false, disabled: boolean = false, name: string = '', label: string = '', value: string = '', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md'
- we-code (DesignSystemElement)
  Props: block: boolean = false
- we-color-picker (DesignSystemElement) — A colour, chosen from the theme's tokens or picked by hand.
  Props: value: string = '#000000', disabled: boolean = false, name: string = '', palette: array = [ '#000000', '#434343', '#666666', '#999999', '#b7b7b7', '#cccccc', '#d9d9d9', '#ffffff', '#980000', '#ff0000', '#ff9900', '#ffff00', '#00ff00', '#00ffff', '#4a86e8', '#0000ff', '#9900ff', '#ff00ff', '#e6b8af', '#f4cccc', '#fce5cd', '#fff2cc', '#d9ead3', '#d0e0e3', '#c9daf8', '#cfe2f3', '#d9d2e9', '#ead1dc', ], tokens: boolean = false, alpha: boolean = false, clearable: boolean = false, confirm: boolean = false
- we-date-picker (DesignSystemElement)
  Props: value: string = '', showTime: boolean = false, placeholder: string = 'Select date', disabled: boolean = false, name: string = '', label: string = '', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md'
- we-divider (LayoutElement)
  Props: orientation: 'horizontal' | 'vertical' = 'horizontal', variant: 'solid' | 'dashed' | 'dotted' = 'solid', color?: string | undefined, thickness?: string | undefined
- we-draggable (LayoutElement) — Makes whatever is inside it something that can be picked up and carried somewhere else.

#### Why this exists as a primitive

A post card, a member row and a space in the sidebar are rendered by **templates**, which are
data. If making one draggable were a code change, every future draggable surface would be a code
change too, and the contribution ladder says arrangement stays data. This is the same rung
`we-sortable` occupies: two custom elements and an existing `$action`, with no new prop resolver,
no new operator, and nothing added to the expression grammar.

```json
{ "type": "we-draggable",
  "props": { "entity": "CollectionBlock", "recordId": { "$": "post.id" }, "label": { "$": "post.title" } },
  "children": [ "…the card…" ] }
```

#### What it carries

A **reference** — `{ dataset?, entity, id }` — never DOM, and never the row object. `dataset` is
deliberately left empty here: a card fragment cannot name its own dataset without reading a
store, and portable fragments name no store by construction. The receiver stamps it, from
whichever dataset was current when the drop happened.

#### Text inside it stays selectable

A press on the words of a rendered composition — anything inside a `data-we-text` region — selects
them rather than picking the card up. The rest of the card, including the space around those
words, still drags. See `shared/textHit.ts`.

#### Nesting

A draggable inside a draggable is how a picture is taken out of a post rather than the whole post:
the innermost one under the press claims it, and the outer one sees the claim and stands aside.

#### `display: contents`

The wrapper must not exist as a box. A card inside a grid track, a row inside a flex column: a
real element in between would take the track and leave the card laid out against the wrapper
instead of the grid. What is dragged is therefore the *child*, which is also what the ghost and
the geometry are measured from.
  Props: entity: string = '', recordId: string = '', datasetKey: string = '', label: string = '', icon: string = '', preview?: { thumbnail?: string; content?: string; author?: string; date?: string } | undefined, origin?: unknown | undefined, within?: DragWithin | undefined, effect: 'move' | 'copy' | 'link' = 'copy', disabled: boolean = false
- we-drawer (OverlayElement)
  Props: hideclosebutton: boolean = false, label: string = '', close: () => void
- we-drop-zone (LayoutElement) — Anything a `we-draggable` can be dropped into.

The receiving half of the pair, and the same rung: two custom elements and an existing `$action`,
so a template can make a region a drop target without a code change.

```json
{ "type": "we-drop-zone",
  "props": { "accepts": "CollectionBlock,Space,Agent",
             "onDropped": { "$action": "modules.pocket.gather", "args": [{ "$": "event.detail" }] } },
  "children": [ "…the panel…" ] }
```

#### It emits intent, it never mutates

Exactly `we-sortable`'s rule, and for the same reason: what a drop *means* differs. A panel writes
a record, a composer inserts a block, a board records a position. A primitive that assumed one of
those would be useless to the others.

#### `accepts` is a list of entity names, as a string

A comma-separated string rather than an array because that is what an HTML attribute is, and
because a schema writing `"accepts": "CollectionBlock,Space"` needs no expression. Empty means
"anything", which is right for a general-purpose tray and wrong for a composer — say what you
take.

#### Zones nest, and the innermost one wins

A folder inside a panel, a card inside a board. Hit-testing picks the innermost accepting zone
and fires exactly one drop — and these events **do not bubble**, so that decision survives the
DOM. See `_zone` for what happened when they did.

Give every nested zone `noArm`, so picking something up speaks once about the container rather
than once about every row inside it.
  Props: accepts: string = '', disabled: boolean = false, noArm: boolean = false, noSelf: boolean = false, hint: string = ''
- we-file-upload (DesignSystemElement)
  Props: accept: string = '', multiple: boolean = false, disabled: boolean = false, name: string = ''
- we-form-field (DesignSystemElement)
  Props: label: string = '', description: string = '', error: string = '', required: boolean = false, size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md'
- we-html (DesignSystemElement) — Renders a raw HTML string safely via DOMPurify sanitization.

Use this instead of `we-text` when content is stored as HTML (e.g. rich-text
editor output such as Flux messages). The `content` prop accepts any HTML
fragment; it is sanitized before rendering so XSS payloads are stripped.

#### SVG animation: CSS keyframes, not SMIL

Inline SVG passes through, and so does animation written as CSS — a `<style>` block with
`@keyframes` inside the SVG, or a `<animateMotion>` following a path. **A SMIL `<animate>` or
`<set>` element does not**: DOMPurify's default allowlist excludes them, so they are removed and
the drawing renders static.

That exclusion is deliberate and stays. `<set attributeName="href" to="javascript:…">` is a real
XSS vector against an `<a>`, which is precisely the shape of payload this element exists to
strip — and SMIL is a dead end besides, deprecated in spirit and unevenly implemented, where CSS
animation is neither.

What was wrong was not the policy but the silence: an author wrote something reasonable, it
typechecked, it validated, and it did nothing, with no diagnostic anywhere. warnAboutSmil
is the diagnostic. It says what was dropped and what to write instead, once per element, in
development only.
  Props: content: string = ''
- we-icon (LayoutElement)
  Props: name: string = '', color: string = '', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '{css-length}' = '', weight: 'thin' | 'light' | 'regular' | 'bold' | 'fill' | 'duotone' = 'regular', gradient: string = ''
- we-icon-picker (DesignSystemElement)
  Props: value: string = '', disabled: boolean = false, name: string = '', label: string = '', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md', placeholder: string = 'Pick icon'
- we-iframe (LayoutVisualElement)
  Props: src: string = '', title: string = 'Embedded content', allow: string = '', sandbox?: string | undefined
- we-image (LayoutVisualElement)
  Props: src: string | File = '', alt: string = '', fit: '' | 'cover' | 'contain' | 'fill' | 'none' | 'scale-down' = '', loading: 'eager' | 'lazy' = 'eager', gradient: string = '', objectPosition: string = ''
- we-input (DesignSystemElement)
  Props: value: string = '', max: string = '', min: string = '', maxlength: unknown = Infinity, minlength: number = 0, pattern: string = '', name: string = '', label: string = '', step: string = '', placeholder: string = '', autocomplete: string = '', autofocus: boolean = false, disabled: boolean = false, required: boolean = false, readonly: boolean = false, type: string = 'text', revealable: boolean = false, size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md'
- we-link (DesignSystemElement)
  Props: href: string = '', target: string = '', rel: string = '', download: string = '', disabled: boolean = false
- we-live-cursor (DesignSystemElement)
  Props: name: string = '', hash: string = '', image: string = '', color: string = ''
- we-location-picker (DesignSystemElement)
  Props: latitude?: number | undefined, longitude?: number | undefined, placeholder: string = 'Set location…', disabled: boolean = false, reverseGeocode: boolean = true
- we-markdown (DesignSystemElement)
  Props: content: string = '', markdownGap: string = ''
- we-menu (DesignSystemElement) — Vertical list container for menu items inside a popover.
Not a standalone selector — wrap in we-popover for dropdown behavior.
- we-menu-group (LayoutElement)
  Props: collapsible: boolean = false, open: boolean = false, heading: string = ''
- we-menu-item (DesignSystemElement) — Single actionable item inside a we-menu.
Supports selected, active, and danger states.
  Props: selected: boolean = false, active: boolean = false, variant: 'default' | 'danger' = 'default', label: unknown, value: unknown
- we-modal (OverlayElement)
  Props: size: 'sm' | 'md' | 'lg' | 'fullscreen' = 'md', hideclosebutton: boolean = false, close: () => void
- we-move-handle (LayoutElement)
  Props: step: number = 24, dragging: boolean = false, label: string = 'Move'
- we-number (DesignSystemElement) — Displays a number, optionally abbreviated (1 200 → 1.2K, 1 500 000 → 1.5M).
  Props: value: number = 0, shorten: boolean = false, precision: number = 1, locale: string = 'en', formattedValue: string
- we-number-input (DesignSystemElement)
  Props: value: number | '' = 0, min: number = -Infinity, max: unknown = Infinity, step: number = 1, disabled: boolean = false, name: string = '', label: string = '', placeholder: string = '', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md'
- we-pagination (DesignSystemElement)
  Props: page: number = 1, total: number = 1, siblings: number = 1, size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md'
- we-popover (LayoutElement) — Low-level floating panel anchored to a trigger element.
Use DropdownMenu component for dropdown menus.
  Props: open: boolean = false, placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' = 'bottom', popoverElement: HTMLElement, triggerElement: HTMLElement
- we-progress-bar (DesignSystemElement)
  Props: value: number = 0, max: number = 100, variant: 'neutral' | 'primary' | 'success' | 'warning' | 'danger' = 'primary', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md', label: string = ''
- we-radio (DesignSystemElement)
  Props: checked: boolean = false, disabled: boolean = false, name: string = '', label: string = '', value: string = '', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md'
- we-resize-handle (LayoutElement) — A drag target that reports how far it has moved, and nothing else.

#### Why it reports a delta rather than owning a size

The obvious design is a handle that resizes its neighbour. It is the wrong one, because "what does
this drag mean" is never the handle's business: the editor's panel rails grow *leftwards* from a
width that starts at zero when the panel is closed, clamp at a minimum, and close the panel again
below a threshold — while a docked call panel grows from whichever edge it is attached to. A
handle that owned the size could serve one of those and not the other.

So it emits `resizestart`, `resize` and `resizeend`, each carrying `delta`: pixels moved along its
axis **since the drag began**, signed in screen direction (right and down positive). The consumer
captures its own starting size and applies whatever sign and limits it has. Delta-from-start
rather than incremental, because every consumer would otherwise have to accumulate, and one of
them would get it wrong after a dropped event.

#### Why a primitive rather than a hook

There were two implementations of this before it existed and they diverged in ways nobody chose:
the editor's is mouse-only, so it does not work on a touchscreen at all, and its rail is a plain
div — not focusable, so there is no way to resize a panel from the keyboard. Pointer events and a
`separator` role fix both once, for every consumer, in the layer where imperative DOM work belongs.
  Props: orientation: 'vertical' | 'horizontal' = 'vertical', align: 'start' | 'center' | 'end' = 'center', line: 'auto' | 'none' = 'auto', step: number = 16, dragging: boolean = false
- we-scroll-area (DesignSystemElement)
  Props: maxHeight: string = '', maxWidth: string = '', pin: '' | 'end' = '', jump: '' | 'start' | 'end' | 'both' = '', nearStart: number = 0, nearEnd: number = 0
- we-select (DesignSystemElement) — Pick a single value from a list of options. Custom-rendered dropdown.
Use for form fields, settings, filters. Set searchable=true for type-to-filter.
  Props: options: SelectOption[] = [], value: string = '', placeholder: string = '', disabled: boolean = false, searchable: boolean = false, fit: boolean = false, name: string = '', label: string = '', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md'
- we-skeleton (DesignSystemElement)
  Props: width: string = '100%', height: string = '20px', animation: 'pulse' | 'wave' = 'pulse'
- we-slider (DesignSystemElement)
  Props: value: number = 0, min: number = 0, max: number = 100, step: number = 1, disabled: boolean = false, name: string = '', label: string = '', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md', showValue: boolean = false, ticks: 'auto' | 'on' | 'off' = 'auto', marks: SliderMark[] = [], valueText: string = ''
- we-sortable (DesignSystemElement) — A drop zone whose items can be picked up, reordered, and moved to other zones.

#### One element, not two

A zone *is* the container and its children *are* the items, which is what makes nesting free: a
sortable inside an item of another sortable is simply a zone inside a zone, with no special case
anywhere. A separate `we-drag-item` would buy nothing and cost boilerplate at every call site.

#### It emits intent, it never mutates

A drop fires SortableMoveDetail — "this item moved from there to here, at this index" —
and nothing else. What that *means* is the consumer's business, and it differs: a kanban route
keyed on `status` writes a scalar, a board built from containment relinks two `children` edges, an
outline reparents a node. A primitive that assumed one of those would be useless to the others.

This is also why the element does not reorder its own DOM. The list is rendered from data; the
data changes; the list re-renders. A primitive that moved nodes itself would fight whatever
renders them.

#### Nesting, and why cycles are not a problem

The hard part of nested drag-and-drop is refusing to drop a container into its own descendant.
Because nesting here is expressed *in the DOM*, that check is `dragged.contains(zone)` — correct
by construction, needing no knowledge of the consumer's data shape. The innermost matching zone
under the pointer wins, so dropping into a nested list does not also count as dropping into its
parent.

#### A zone that can be empty needs a size

Hit-testing is by the zone's own bounding rectangle, so a zone holding nothing is a zero-height
rectangle and nothing can be dropped into it — which is precisely the zone a person most wants to
drop into. **Give any zone that can empty a `flex` or a `minHeight`**; without one the surrounding
box may look like the target while not being it, which is worse than looking undroppable.

Left to the consumer rather than defaulted here, because how much room an empty list should hold
is a design decision and differs per surface — a kanban column reserves a trough, a reorderable
settings list should collapse. What the primitive owes is that the rule is written down where
somebody wiring one up will read it.

#### Keyboard

Space or Enter picks up the focused item; the arrow keys move it, along the list and across
zones; Space drops and Escape cancels. Built in rather than added later, because a board that can
only be operated by dragging is a board some people cannot operate at all — and because the
events are identical, a consumer gets it for nothing.

#### Items that contain form controls: `[data-we-handle]`

By default the whole item is the grab area, which is right for a card or a nav row. It is wrong
the moment an item contains a text field: dragging to select text would start a drag, and — worse
— the keyboard pickup would read a **space typed into an input** as "pick this up", so the field
could not accept spaces at all.

So two rules, both no-ops for an item without form controls:

- Mark one or more descendants `data-we-handle`, and only a press that begins inside a handle
  starts a drag. An item with no handle keeps dragging from anywhere, so existing consumers are
  unaffected.
- A Space or Enter that originates in a text-entry element (`input`, `textarea`, `select`,
  `contenteditable`, including inside a component's shadow root) is typing, never a pickup. This
  applies whether or not the item declares handles, because an unfocusable-by-design input that
  swallows spaces is a bug in every consumer that could hit it.

Make the handle itself focusable (a `we-button` will do) so the keyboard path stays open: Space
on a focused handle picks the row up exactly as it does on a plain item.

#### Overlays opened from an item are not part of it

A press that begins inside an `OverlayElement` — a modal, a drawer, a popover — never drags the
item that overlay happens to sit inside, and no consumer has to declare anything for that.

It is worth knowing why the case exists at all. A modal opened from a row is usually *declared* in
that row, because it needs the row's data to say what it is renaming; overlays are promoted to the
browser's top layer rather than reparented, so the sheet paints above the whole page while DOM
containment still says it is inside the row. Without this rule, dragging to select text in a rename
field dragged the column behind the modal.

Same principle as nested zones, one layer up: the innermost thing under the pointer owns the
gesture. A sortable *inside* an overlay is unaffected — only the path between the press and the
item is considered.
  Props: direction: 'vertical' | 'horizontal' = 'vertical', gap: string = '', zone: string = '', group: string = '', locked: boolean = false
- we-spinner (LayoutElement)
  Props: size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | (string & {}) = 'md', color: string = ''
- we-switch (DesignSystemElement)
  Props: checked: boolean = false, disabled: boolean = false, name: string = '', label: string = '', value: string = '', size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md', labelOff: string = '', labelOn: string = ''
- we-tab (DesignSystemElement)
  Props: key: string = '', selected: boolean = false, label?: string | undefined, selectedProps?: Partial<DesignSystemProps> | undefined
- we-tabs (DesignSystemElement)
  Props: selectedKey: string = ''
- we-tag (DesignSystemElement)
  Props: variant: 'neutral' | 'primary' | 'success' | 'warning' | 'danger' = 'neutral', dismissible: boolean = false
- we-text (DesignSystemElement)
  Props: text?: string | undefined, variant: '' | 'body' | 'label' | 'footnote' | 'subheading' | 'ingress' | 'heading-sm' | 'heading-md' | 'heading-lg' | 'heading-xl' = '', tag: 'p' | 'span' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'small' | 'b' | 'i' | 'label' | 'div' = 'span', inline: boolean = false, uppercase: boolean = false, italic: boolean = false, truncate: boolean = false, gradient: string = '', loading: boolean = false, loadingWidth: string = '100%'
- we-textarea (DesignSystemElement)
  Props: value: string = '', name: string = '', label: string = '', placeholder: string = '', rows: number = 3, maxlength: unknown = Infinity, minlength: number = 0, disabled: boolean = false, required: boolean = false, readonly: boolean = false, resize: 'none' | 'vertical' | 'horizontal' | 'both' = 'vertical', autoGrow: boolean = false, maxRows: number = 6, submitOnEnter: boolean = false, size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md'
- we-timestamp (DesignSystemElement) — Displays a formatted or relative timestamp that self-updates each minute
when `relative` is enabled.
  Props: value: string = '', relative: boolean = false, relativeStyle: 'long' | 'short' | 'narrow' = 'long', locale: string = 'en', dateStyle: 'full' | 'long' | 'medium' | 'short' | null = null, timeStyle: 'full' | 'long' | 'medium' | 'short' | null = null, weekday: 'long' | 'short' | 'narrow' | null = null, year: 'numeric' | '2-digit' | null = null, month: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow' | null = null, day: 'numeric' | '2-digit' | null = null, hour: 'numeric' | '2-digit' | null = null, minute: 'numeric' | '2-digit' | null = null, second: 'numeric' | '2-digit' | null = null, timeZone: string | null = null, hourCycle: 'h11' | 'h12' | 'h23' | 'h24' | null = null, formattedTime: string
- we-tooltip (LayoutElement)
  Props: open: boolean = false, content: string = '', placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' = 'top', tooltipEl: HTMLElement, arrowEl: HTMLElement
- we-video (LayoutVisualElement)
  Props: src: string = '', poster?: string | undefined, controls: boolean = false, preload: 'none' | 'metadata' | 'auto' = 'metadata', fit: '' | 'cover' | 'contain' | 'fill' | 'none' | 'scale-down' = '', autoplay: boolean = false, loop: boolean = false, muted: boolean = false, playsinline: boolean = false, stream?: MediaStream | null | undefined

@we/components:
- AudioDisplay
  Props: title: string | undefined, artist: string | undefined, audioUrl: string | undefined, duration: number | undefined, albumArt: string | undefined
- BlockComposer (DesignSystemElement)
  Props: editorState?: EditorStateInput, dataset?: unknown, onSave?: ((document: ContentDocument) => void), onReady?: ((api: { save: () => void; }) => void), onDirtyChange?: ((dirty: boolean) => void), mentions?: MentionCandidate[], collaborate?: string, autoFocus?: boolean, handles?: boolean
- BlockRenderer (DesignSystemElement)
  Props: editorState?: EditorStateInput, dataset?: unknown, blockDrag?: BlockDragSource, rootClass?: string
- CalloutDisplay
  Props: text: string | undefined, variant: string | undefined, icon: string | undefined
- CodeDisplay
  Props: code: string | undefined, language: string | undefined, title: string | undefined
- EmbedDisplay
  Props: url: string | undefined, target: string | undefined, targetType: string | undefined, displayMode: string | undefined, label?: string, thumbnail?: string, sourceAuthor?: string, sourceName?: string, onOpenRef?: ((ref: string) => void)
- EventDisplay
  Props: title: string | undefined, description: string | undefined, startDate: string | undefined, endDate: string | undefined, location: string | undefined, allDay: boolean | undefined
- FileDisplay
  Props: title: string | undefined, name: string | undefined, url: string | undefined, mimeType: string | undefined, size: number | undefined
- ImageDisplay
  Props: src: string | undefined, altText: string | undefined, width: number | undefined, height: number | undefined
- LinkDisplay
  Props: url: string | undefined, title: string | undefined, description: string | undefined, thumbnail: string | undefined
- LocationDisplay
  Props: name: string | undefined, latitude: number | undefined, longitude: number | undefined, address: string | undefined
- TagDisplay
  Props: name: string | undefined, color: string | undefined
- TaskDisplay
  Props: title: string | undefined, description: string | undefined, status: string | undefined, priority: string | undefined, dueDate: string | undefined, assignee: string | undefined
- VideoDisplay
  Props: url: string | undefined, title: string | undefined, thumbnail: string | undefined, provider: string | undefined, width: number | undefined
- AvatarStack
  Props: avatars: AvatarInfo[], max?: number, size?: "xs" | "sm" | "md" | "lg" | "xl" | "xxs" | "xxl", overlap?: number, edge?: string, ringWidth?: string, styles?: Record<string, string | number>
- Calendar
  Props: value?: string, events?: CalendarEvent[], onSelect?: ((date: string) => void), styles?: Record<string, string | number>
- Canvas (DesignSystemElement)
  Props: artboard: { width: number; height: number; }, fit?: "contain" | "none" | "stretch" | "scale", onMeasure?: ((box: { width: number; height: number; scale: number; }) => void)
- Card (DesignSystemElement)
- CodeEditor
  Props: code: string, language?: CodeEditorLanguage, readOnly?: boolean, onChange?: ((code: string) => void), onSave?: ((code: string) => void), maxHeight?: string, onReady?: ((api: { find: () => void; }) => void), onSearchMatches?: ((result: { query: string; matches: number; capped: boolean; }) => void), styles?: Record<string, string | number>
- CollapsedContent
  Props: collapsed: boolean, onExpandClick?: (() => void), showToggle?: boolean, icon?: string, maxHeight?: string, fadeColor?: string, children?: JSX.Element, class?: string, styles?: Record<string, string | number>
- Column (DesignSystemElement)
- Combobox (DesignSystemElement)
  Props: options: string[] | ComboboxOption[], value?: string, placeholder?: string, size?: "xs" | "sm" | "md" | "lg" | "xl", onChange?: ((value: string) => void)
- CountMark
  Props: icon: string, count?: number, mine?: boolean, size?: "xs" | "sm" | "md", countTone?: "text" | "glyph", countFirst?: boolean, emphasis?: "quiet" | "present", onPress?: (() => void), label?: string, disabled?: boolean, class?: string, styles?: Record<string, string | number>
- DropdownMenu — Flexible dropdown menu for actions, toggles, and grouped items. Use for context menus, settings panels, layer controls, and command palettes.
  Props: styles?: Record<string, string | number>, class?: string, onSelect?: ((item: DropdownMenuAction | DropdownMenuToggle) => void), searchable?: boolean, searchPlaceholder?: string, placement?: Placement, triggerLabel?: string, triggerIcon?: string, triggerVariant?: "primary" | "danger" | "secondary" | "ghost" | "outline" | "bare", triggerTitle?: string, size?: "xs" | "sm" | "md" | "lg" | "xl", itemSize?: "xs" | "sm" | "md" | "lg" | "xl", items: SolidDropdownMenuEntry[], children?: JSX.Element
- EditableImage (DesignSystemElement)
  Props: src?: string, alt?: string, fit?: "cover" | "contain" | "none" | "fill" | "scale-down", placeholderIcon?: string, onImageChange?: ((file: File) => void), onImageRemove?: (() => void), uploadLabel?: string, editLabel?: string, class?: string, aspect?: number, maxSize?: number
- FlipCard
  Props: front?: JSX.Element, back?: JSX.Element, width?: string, height?: string, flipOnHover?: boolean, flipDuration?: string, wobbleOnHover?: boolean, wobbleDegree?: number, class?: string, styles?: Record<string, string | number>
- Grid (DesignSystemElement)
  Props: template?: string, columns?: number, minChildWidth?: string, rows?: string, childAspect?: string | number, onMeasure?: ((box: { width: number; height: number; }) => void), onArrange?: ((tiling: Tiling) => void)
- ImageLightbox
  Props: srcs: string[], initialIndex: number, onClose: () => void
- Row (DesignSystemElement)
- Search (DesignSystemElement)
  Props: placeholder?: string, value?: string, onSearch?: ((value: string) => void), debounce?: number
- Select (DesignSystemElement)
  Props: options: SelectOption[], value?: string, placeholder?: string, searchable?: boolean, label?: string, size?: "xs" | "sm" | "md" | "lg" | "xl", onChange?: ((value: string) => void)
- SignalControl
  Props: signalType: SignalTypeData, size?: "xs" | "sm" | "md", signals?: SignalData[], myDid?: string, onSignal?: ((value: number | null) => void), disabled?: boolean, preview?: boolean, class?: string, styles?: Record<string, string | number>
- ToastContainer
  Props: position?: "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center", styles?: Record<string, string | number>

@we/widgets:
- GraphView — A general-purpose graph view: knowledge maps, schema maps, hierarchies, cluster maps and
free-positioned canvases, all from the same engine.

The shape of a graph is set by four independent choices: where it starts (`seeds`), how much of it
opens (`expansion`), how it is arranged (`layout`), and how it looks (`nodeStyle` / `edgeStyle`).

Common recipes:
- **Knowledge map** — `seeds: { source: 'query', options: { entity: 'Belief' } }` with
`expansion: { defaultDepth: 1 }` and `layout: { type: 'force' }`.
- **Schema map** — `seeds: { source: 'schema' }`, which draws the dataset's own entity types and
the relations between them. Picks up model types added later with no template change.
- **Hierarchy** — `layout: { type: 'tree' }` with a `collection` expansion for nested content.
- **Static diagram** — `seeds: { literal: true, nodes: [...], edges: [...] }` and no expansion at all.
  Props: seeds?: SeedSpec | SeedSpec[], expansion?: ExpansionSpec, revision?: string | number | boolean, live?: boolean, layout?: LayoutSpec, nodeStyle?: NodeStyleRules, edgeStyle?: EdgeStyleRules, behaviours?: BehaviourSpec[], reified?: Record<string, { source: string; target: string; type?: string; sourceType?: string; targetType?: string; }>, width?: string, height?: string, bg?: string, showStatus?: boolean, empty?: string, emptyIcon?: string, emptyGradient?: string, emptyAction?: JSX.Element, showControls?: boolean, controls?: string[], onNodeClick?: ((node: GraphNode & { recordId?: string; recordType?: string; fields: { name: string; value: string; }[]; }) => void), expandRequest?: { id: string; expanders?: string[]; direction?: "in" | "out" | "both"; } | null, onNodeDoubleClick?: ((node: GraphNode & { recordId?: string; recordType?: string; }) => void), onEdgeClick?: ((edge: GraphEdge & { recordId?: string; recordType?: string; }) => void), onEdgeRetarget?: ((payload: { id: string; end: "source" | "target"; nodeId: string; nodeType: string; recordId?: string; recordType?: string; }) => void), onEdgeReroute?: ((payload: { id: string; points: EdgeWaypoint[]; recordId?: string; recordType?: string; }) => void), onEdgeAnchor?: ((payload: { id: string; end: "source" | "target"; side: "" | "n" | "e" | "s" | "w"; recordId?: string; recordType?: string; }) => void), onEdgeCreate?: ((payload: { source: GraphNode; target: GraphNode; sourceId: string; sourceType: string; targetId: string; targetType: string; sourceLabel: string; targetLabel: string; }) => void), onCanvasDoubleClick?: ((payload: { x: number; y: number; }) => void), onSelectionChange?: ((ids: string[]) => void), onNodeDragEnd?: ((payload: { id: string; x: number; y: number; recordId?: string; recordType?: string; carried?: { recordId: string; recordType: string; x: number; y: number; }[]; }) => void), onSeedSummary?: ((payload: { source: string; } & Record<string, unknown>) => void), onNodeArrange?: ((payload: { id: string; into: "child" | "sibling" | "loose"; recordId: string; recordType: string; targetId?: string; targetType?: string; before?: boolean; order?: string[]; x: number; y: number; }) => void), resizable?: boolean, onNodeResize?: ((payload: { id: string; x: number; y: number; width: number; height: number; recordId?: string; recordType?: string; }) => void), onDrop?: ((payload: { entity: string; id: string; dataset?: string; label: string; x: number; y: number; within?: { entity: string; id: string; }; preview?: { thumbnail?: string; author?: string; source?: string; }; }) => void), nodeActions?: NodeAction[], onNodeAction?: ((payload: { action: string; id: string; recordId?: string; recordType?: string; value?: unknown; preview?: boolean; x: number; y: number; }) => void), focus?: string, folded?: string[], onNodeFold?: ((payload: { id: string; recordId?: string; recordType?: string; folded: boolean; count: number; }) => void), onDeleteSelection?: ((payload: { recordId?: string; recordType?: string; kind?: "node" | "edge"; count: number; records?: { recordId: string; recordType: string; }[]; }) => void), carry?: boolean, selectionActions?: NodeAction[], onSelectionAction?: ((payload: { action: string; records: { recordId: string; recordType: string; }[]; count: number; value?: unknown; preview?: boolean; }) => void), onUndo?: (() => void), onRedo?: (() => void), onPointerAt?: ((at: { x: number; y: number; } | null) => void), onViewport?: ((region: GraphRegion) => void), region?: GraphRegion | null, reframeOn?: string | number | boolean | null, host?: GraphHostBindings

---

## Component Plugin Registries

Some components resolve named plugins from their props. These are the names each accepts —
a name not listed here does not exist, and the component will warn rather than render.

### CesiumGlobe

Layers are listed in two props: planetLayers (drawn on the earth) and backgroundLayers (the space around it). Each entry is { factory, id?, enabled?, zIndex?, options? }: factory names the kind below; id is required when one kind appears twice, or the two collide and one is not drawn; enabled takes an expression, so a layer can follow a toggle; zIndex is a planet layer's stacking order, which each kind interprets. Options take expressions and handlers like any prop, so a layer can draw what a $queries entry fetched: read it with { "$": "local.rows.map(…)" }. The imagery is the globe's own and is not a layer. A globe is drawn by one of two engines, which the deployment or the person chooses and a template never names: Cesium, the full 3D globe, or MapLibre, a lighter one for phones. Both draw every planet kind; only Cesium draws the background kinds. Read modules.globe.drawsSpace to leave the background kinds out of a menu where they would do nothing. A kind an engine does not draw is simply absent there, so place them as you would anyway. The data kinds (pointsLayer, pathsLayer, areasLayer, hexbinLayer) each take rows as `data`, field paths saying where in a row its geometry is (dotted for nested fields: "location.latitude"), and `style`: rules in the GraphView's dialect, [{ when?, style }], applied in order with later matches winning per property. A rule's `when` reads a row's fields as "data.<field>"; a style value is a literal, { "from": "data.<field>" } to read it off the row, or { "metric": "field", "options": { "from": "<field>" }, "range": [min, max] } (a number) or "scale": { "from": colour, "to": colour } (a colour) to scale it across all the rows. Colours are roles or tokens ("accent", "warning-500") or CSS. For a heat, use { "from": "success-500", "to": "danger-500" }, green to red, which reads the same way round in a light and a dark theme; the graph's named scales ("heat") follow the page's theme and turn around in a dark one, which is wrong over satellite imagery. Start a height range above 0 so the least still shows. Pressing a feature calls onSelect. A globe can follow a clock, to play its data through time: give it clock: "<name>" (or { id, duration, loop, autoplay }), and give a data kind time: "<field>" naming each row's moment. Rows from after the clock's moment are not drawn, and the clock's range is worked out from the rows. The controls are ordinary nodes beside the globe reading clockStore.clocks.<name> — playing, progress (0–1), atIso for a we-timestamp, canPlay — and calling clockStore.toggle and clockStore.seekProgress. Until somebody plays or scrubs, the clock has no moment and every row is drawn. Statistics a style scales across the rows (a heat, a height) are relative to the rows drawn at that moment; give the metric min and max to hold its scale still while it plays.

**planet**

- `pointsLayer` — A marker per row: a dot, or a picture, with a label. For members, spaces, events, sightings — anything with a place. Thousands are fine; close together they can cluster into one marker with a count.
  - data: object[] — The rows. Rows without a place are left out.
  - latitude: string — Field path to the latitude. Default "latitude".
  - longitude: string — Field path to the longitude. Default "longitude".
  - id: string — Field naming each row, so an update restyles rather than redraws. Default "id".
  - label: string — Field shown beside each marker. Default "name"; "" for none.
  - labelMaxAltitude: number — Labels show only while the camera is below this many metres — e.g. 2000000 to hide them from orbit.
  - style: rules — Properties: size (pixels, default 12), color, opacity, borderColor (default white), borderWidth (default 2), image (a picture instead of a dot, usually { "from": "data.avatar" }), labelColor.
  - cluster: boolean | { radius?, color? } — Draw markers within radius pixels (default 60) of each other as one, with a count; pressing one zooms in.
  - time: string — Field path to each row's moment — a date, a date-time or milliseconds ("createdAt", "startDate"). On a globe with a clock, only rows up to the clock's moment are drawn, so playing it shows them arriving; a row with no readable moment is drawn throughout. A rule reads a row's age in days as "data.age".
  - window: string | number — With time: only rows this recent are drawn — "7d", "12h", "30m", or milliseconds — so the layer shows what is happening at the moment rather than everything up to it.
  - fade: boolean — With window: rows fade out over the last quarter of the window rather than vanishing. Default true.
  - onSelect: handler — Runs when a marker is pressed, with its row as event.
  - Example: `{ "factory": "pointsLayer", "id": "members", "options": { "data": { "$": "spaceStore.members.filter(m, m.location)" }, "latitude": "location.latitude", "longitude": "location.longitude", "label": "name", "style": [{ "style": { "color": "accent", "image": { "from": "data.avatar" } } }, { "when": { "data.role": "admin" }, "style": { "borderColor": "warning-500" } }], "cluster": true, "onSelect": { "$setLocal": "selected", "value": { "$": "event" } } } }`
- `pathsLayer` — A line per row: between two places, or along a list of them. Follows the earth's curve, and can arc — a share of its own length, so longer routes arc higher. For travel, routes between events, who replied to whom across the world.
  - data: object[] — The rows. Rows without both ends are left out.
  - from: { latitude, longitude } — Field paths to where each line starts. Default "from.latitude" / "from.longitude".
  - to: { latitude, longitude } — Field paths to where it ends. Default "to.latitude" / "to.longitude".
  - coordinates: string — Instead of from/to: a field holding the whole line as [longitude, latitude] pairs.
  - id: string — Field naming each row. Default "id".
  - style: rules — Properties: width (pixels, default 2), color, opacity, dashed (true/false; an arc is drawn solid), arcHeight (0 flat … 0.5 tall, a share of the line's length; default 0; only a line between two places arcs). A rule can read a line's length in kilometres as "data.length".
  - time: string — Field path to each row's moment — a date, a date-time or milliseconds ("createdAt", "startDate"). On a globe with a clock, only rows up to the clock's moment are drawn, so playing it shows them arriving; a row with no readable moment is drawn throughout. A rule reads a row's age in days as "data.age".
  - window: string | number — With time: only rows this recent are drawn — "7d", "12h", "30m", or milliseconds — so the layer shows what is happening at the moment rather than everything up to it.
  - fade: boolean — With window: rows fade out over the last quarter of the window rather than vanishing. Default true.
  - onSelect: handler — Runs when a line is pressed, with its row as event.
  - Example: `{ "factory": "pathsLayer", "id": "trips", "options": { "data": { "$": "local.trips" }, "from": { "latitude": "origin.latitude", "longitude": "origin.longitude" }, "to": { "latitude": "destination.latitude", "longitude": "destination.longitude" }, "style": [{ "style": { "color": "accent", "width": 2, "arcHeight": 0.2 } }, { "when": { "data.length": { "gt": 5000 } }, "style": { "color": "warning-500" } }] } }`
- `areasLayer` — Filled shapes. Either each row carries its own (GeoJSON), or the rows name countries and are grouped into them: rows naming the same country become one shaded country, with how many rows (or the sum, mean, least or greatest of a field) as data.value — shaded green to red by it when no style is given. For choropleths: members per country, posts per country, a region somebody drew.
  - data: object[] — The rows.
  - area: "countries" — Group the rows into the countries they name, rather than drawing their own shapes.
  - key: string — With area: the field naming a row's country. Default "country".
  - match: "iso_a2" | "iso_a3" | "name" — With area: what key holds — "FR", "FRA" or "France". Default "iso_a2". Case does not matter.
  - aggregate: "count" | "sum" | "mean" | "min" | "max" — With area: how a country's rows become data.value. Default "count".
  - value: string — With area: the field summed, averaged or compared.
  - geometry: string — Without area: the field holding each row's shape as a GeoJSON Polygon or MultiPolygon. Default "geometry".
  - style: rules — Properties: color (the fill), opacity (default 0.6), borderColor, borderWidth (default 1 with a border colour), height (metres to raise it as a solid; default 0, flat). With area, a rule reads "data.value", "data.count" and "data.name".
  - time: string — Field path to each row's moment — a date, a date-time or milliseconds ("createdAt", "startDate"). On a globe with a clock, only rows up to the clock's moment are drawn, so playing it shows them arriving; a row with no readable moment is drawn throughout. A rule reads a row's age in days as "data.age".
  - window: string | number — With time: only rows this recent are drawn — "7d", "12h", "30m", or milliseconds — so the layer shows what is happening at the moment rather than everything up to it.
  - fade: boolean — With window: rows fade out over the last quarter of the window rather than vanishing. Default true.
  - onSelect: handler — Runs when a shape is pressed: with the row, or with area, { key, name, rows, count, value }.
  - Example: `{ "factory": "areasLayer", "id": "members-by-country", "options": { "data": { "$": "spaceStore.members.filter(m, m.location)" }, "area": "countries", "key": "location.countryCode", "style": [{ "style": { "color": { "metric": "field", "options": { "from": "value" }, "scale": { "from": "success-500", "to": "danger-500" } }, "opacity": 0.7, "height": { "metric": "field", "options": { "from": "value" }, "range": [30000, 400000] } } }] } }`
- `hexbinLayer` — Rows gathered into hexagonal H3 cells, one shaded cell per place with rows in it, so density reads without placing every row. A cell's data.value is how many rows (or the sum, mean, least or greatest of a field); shaded green to red by it when no style is given, and raised into a column by a height rule. Different from h3HexagonsLayer, which draws the empty grid.
  - data: object[] — The rows. Rows without a place are left out.
  - latitude: string — Field path to the latitude. Default "latitude".
  - longitude: string — Field path to the longitude. Default "longitude".
  - resolution: number — Cell size: 2 is countries, 4 (default) about 22 km across, 7 a town, 10 a few streets.
  - aggregate: "count" | "sum" | "mean" | "min" | "max" — How a cell's rows become data.value. Default "count".
  - value: string — The field summed, averaged or compared.
  - style: rules — Properties: color, opacity (default 0.7), height (metres to raise the cell; default 0). A rule reads "data.value" and "data.count".
  - time: string — Field path to each row's moment — a date, a date-time or milliseconds ("createdAt", "startDate"). On a globe with a clock, only rows up to the clock's moment are drawn, so playing it shows them arriving; a row with no readable moment is drawn throughout. A rule reads a row's age in days as "data.age".
  - window: string | number — With time: only rows this recent are drawn — "7d", "12h", "30m", or milliseconds — so the layer shows what is happening at the moment rather than everything up to it.
  - fade: boolean — With window: rows fade out over the last quarter of the window rather than vanishing. Default true.
  - onSelect: handler — Runs when a cell is pressed, with { cell, rows, count, value }.
  - Example: `{ "factory": "hexbinLayer", "id": "post-heat", "enabled": { "$": "local.showHeat" }, "options": { "data": { "$": "local.posts" }, "latitude": "location.latitude", "longitude": "location.longitude", "resolution": 3, "style": [{ "style": { "color": { "metric": "field", "options": { "from": "value" }, "scale": { "from": "success-500", "to": "danger-500" } }, "height": { "metric": "field", "options": { "from": "value" }, "range": [30000, 300000] } } }], "onSelect": { "$setLocal": "cell", "value": { "$": "event" } } } }`
- `heatmapLayer` — Rows as a continuous glow, bright where they gather and fading out around them, green through amber to red. Where a hexbin gives cells to count and press, a heatmap shows at a glance where things concentrate, with no cell edges to read as boundaries — and nothing to press. For dense points: posts, sightings, check-ins.
  - data: object[] — The rows. Rows without a place are left out.
  - latitude: string — Field path to the latitude. Default "latitude".
  - longitude: string — Field path to the longitude. Default "longitude".
  - weight: string — A field whose number is how much each row adds. Default: each row adds the same.
  - radius: number — How far one row's glow spreads, in pixels on screen. Default 30.
  - intensity: number — Multiplies every row's heat: raise it for sparse data, lower it for dense. Default 1.
  - opacity: number — 0 to 1. Default 0.8.
  - colors: string[] — The ramp, coolest to hottest, as roles, tokens or CSS. Default ["success-500", "warning-500", "danger-500"].
  - time: string — Field path to each row's moment — a date, a date-time or milliseconds ("createdAt", "startDate"). On a globe with a clock, only rows up to the clock's moment are drawn, so playing it shows them arriving; a row with no readable moment is drawn throughout. A rule reads a row's age in days as "data.age".
  - window: string | number — With time: only rows this recent are drawn — "7d", "12h", "30m", or milliseconds — so the layer shows what is happening at the moment rather than everything up to it.
  - fade: boolean — With window: rows fade out over the last quarter of the window rather than vanishing. Default true.
  - Example: `{ "factory": "heatmapLayer", "id": "post-glow", "enabled": { "$": "local.showGlow" }, "options": { "data": { "$": "local.posts" }, "latitude": "location.latitude", "longitude": "location.longitude", "radius": 40, "time": "createdAt", "window": "14d" } }`
- `satelliteOverlayLayer` — NASA's satellite imagery of one day, laid over the earth beneath the data: the day's photograph from orbit with its clouds, active fires, snow, rain, smoke and dust, sea ice, or the lights at night. No account needed. On a globe with a clock it shows the clock's day, so scrubbing moves the weather; otherwise the most recent day there is.
  - product: "true-color" | "fires" | "snow" | "precipitation" | "aerosols" | "sea-ice" | "night-lights" — What to show. Default "true-color", the day's photograph. "aerosols" is smoke and dust; "night-lights" is one picture rather than a day each.
  - date: string — A day as YYYY-MM-DD, which overrides the clock. Kept between the first day the product has and the most recent.
  - opacity: number — 0 to 1. Default 1 for the photograph, fires and night lights, a little less for the others.
  - Example: `{ "factory": "satelliteOverlayLayer", "id": "fires", "enabled": { "$": "local.showFires" }, "options": { "product": "fires" } }`
- `pointLocationsLayer` — Markers at places on the earth, each with a label, drawn as the avatar when one is given and as a coloured dot otherwise. Pressing one calls onLocationClick with that location, every field included, so a location can carry what a modal needs (a kind, an id).
  - locations: { id, name, latitude, longitude, avatar?, color? }[] — What to mark. Usually an expression over a query or a store — any extra fields ride along to onLocationClick.
  - markerSize: number — Diameter in pixels. Default 15.
  - defaultColor: string — CSS colour of a dot with no avatar or color. Default "#00ffff".
  - onLocationClick: handler — Runs when a marker is pressed, with the location as event.
  - Example: `{ "factory": "pointLocationsLayer", "id": "space-locations", "enabled": { "$": "local.showSpaces" }, "options": { "locations": { "$": "local.spaceRows.map(s, { id: s.id, kind: 'space', name: s.name, latitude: s.location.latitude, longitude: s.location.longitude, avatar: s.avatar })" }, "markerSize": 20, "defaultColor": "#a855f7", "onLocationClick": { "$setLocal": "selectedPin", "value": { "$": "event" } } } }`
- `countryOutlinesLayer` — Country borders, from Natural Earth 1:50m. The app serves the data itself, so the borders draw offline. Draped on the surface, so markers and hexagons always sit above them.
  - color: string — CSS colour of the lines. Default "#ffffff".
  - opacity: number — 0 to 1. Default 0.5.
  - width: number — Line width in pixels. Default 2.
  - dataUrl: string — Another GeoJSON of boundaries to draw instead. Only a URL on the app's own origin is fetched; any other is ignored, with a warning, and the default drawn.
  - Example: `{ "factory": "countryOutlinesLayer", "options": { "color": "#ffffff", "opacity": 0.5, "width": 2 } }`
- `h3HexagonsLayer` — The H3 hexagon grid, finer as the camera comes closer: each zoom draws the resolution whose cells suit it. A hovered cell is highlighted.
  - maxResolution: number — Finest H3 resolution drawn, 0–15. Default 8.
  - color: string — CSS colour of the cell edges. Default "#3388ff".
  - opacity: number — Edge opacity, 0 to 1. Default 0.6.
  - width: number — Edge width in pixels. Default 2.
  - hoverColor: string — CSS colour of a hovered cell. Default "#3388ff".
  - hoverOpacity: number — Opacity of a hovered cell. Default 0.3.
  - onHexagonClick: handler — Runs when a cell is pressed, with the cell's H3 index as event.
  - Example: `{ "factory": "h3HexagonsLayer", "enabled": { "$": "local.showHexagons" }, "options": { "maxResolution": 8, "color": "#3388ff", "opacity": 0.6 } }`

**background**

- `skyboxLayer` — A star map around the globe, from NASA's Tycho-2 catalogue. Cesium's own copy shows at once and offline; the set asked for replaces it once it has loaded. Drawn by the Cesium engine only.
  - textureSet: "tycho2-1k" | "tycho2-2k" | "tycho2-4k" | "custom" — Resolution of each face: 1k is 2.4 MB, 2k 5.8 MB, 4k 20 MB. Default "tycho2-1k".
  - customPaths: { px, nx, py, ny, pz, nz } — One image URL per cube face, with textureSet "custom".
  - Example: `{ "factory": "skyboxLayer", "enabled": { "$": "local.showSkybox" }, "options": { "textureSet": "tycho2-4k" } }`
- `proceduralStarsLayer` — Points of light at random depths around the earth, which move against each other as the camera turns. Drawn by the Cesium engine only.
  - count: number — How many stars. Default 5000.
  - minDistance: number — Nearest star, in metres from the surface.
  - maxDistance: number — Farthest star, in metres from the surface.
  - minBrightness: number — Dimmest star, 0 to 1. Default 0.3.
  - maxBrightness: number — Brightest star, 0 to 1. Default 1.
  - minSize: number — Smallest star in pixels. Default 1.
  - maxSize: number — Largest star in pixels. Default 3.
  - color: string — CSS colour. Default "#ffffff".
  - Example: `{ "factory": "proceduralStarsLayer", "enabled": { "$": "local.showStars" }, "options": { "count": 2000, "minDistance": 10000, "maxDistance": 100000000 } }`
- `solarSystemLayer` — The sun, the planets at their positions for today, and their orbits, scaled down to be seen from the earth. Drawn by the Cesium engine only.
  - planets: string[] — Which to draw: mercury, venus, earth, mars, jupiter, saturn, uranus, neptune.
  - showSun: boolean — Default true.
  - showOrbits: boolean — Default true.
  - showPlanets: boolean — Default true.
  - showLabels: boolean — Default true.
  - planetScale: number — Multiplies the size of each planet’s point. Default 1.
  - orbitScale: number — Shrinks the orbits to fit the view; the real system is far too large. Default 0.0001.
  - orbitWidth: number — Orbit line width in pixels. Default 2.
  - orbitResolution: number — Points per orbit; more is smoother. Default 360.
  - Example: `{ "factory": "solarSystemLayer", "enabled": { "$": "local.showSolarSystem" }, "options": { "planets": ["mercury", "venus", "earth", "mars"], "orbitScale": 0.01 } }`

### GraphView

Names resolvable inside GraphView props: seed sources (seeds.source), expanders (expansion.expanders), layouts (layout.type) and behaviours (behaviours[]).

**seed**

- `query` — Loads instances of one entity type as nodes; can draw named relations immediately.
  - entity: string — Entity type to load (required).
  - where: object — Filter, same operators as $query.
  - order: object — e.g. { createdAt: "desc" }.
  - limit: number — Defaults to 100.
  - relations: string[] — Relations to hydrate and draw as edges up front.
  - Example: `{ "source": "query", "options": { "entity": "Post", "limit": 50, "relations": ["author"] } }`
- `schema` — Maps the dataset's own entity types and the relations between them — one node per type. Picks up model types installed after the template was written, so it suits spaces whose vocabulary is open-ended.
  - entities: string[] — Restrict to these types; omit for all of them.
  - Example: `{ "source": "schema" }`
- `canvas` — A container's contents at the positions somebody put them. Membership is ordinary containment, so a card composed onto the canvas is found like any child; position comes from Placement records parented to the same canvas, which is why the same note can sit on two canvases in two places. Pair with layout: manual and drag-node { pin: true }, and persist a drop through recordStore.placeOnCanvas. Loads nothing until a canvas is chosen.
  - canvas: string — Record id of the canvas (required).
  - contains: string[] — Types the canvas may hold beyond whatever its placements name — one query each. Defaults to the block vocabulary; anything *placed* is loaded whether or not it is listed.
  - via: string — Relation holding the contents. Defaults to "children".
  - connections: string — Reified relation entity to draw as lines between the cards — e.g. "Relationship". Only pairs whose two ends are both on the canvas are drawn, since a line to something elsewhere would leave the canvas. Each line carries the record it stands for, so clicking one can open it. Omit for a canvas with no connections.
  - typeStyles: string — Entity holding this canvas's colour per kind of thing — WE passes "TypeStyle". Read onto every node as `canvasTypeColor`, for a style rule to pick up with `{ from: "data.canvasTypeColor" }`. This is what a canvas's key writes.
  - routes: string — Entity holding how this canvas draws its connections — WE passes "EdgeRoute". Read onto each edge as `sourceAnchor` / `targetAnchor`, which pin which SIDE of a card a line leaves and arrives on (`n`, `e`, `s`, `w`) instead of letting the geometry decide. Per canvas, like a placement: the same connection shown on two canvases is tidied on each separately. Also carries the points a line is bent through, read onto the edge as `waypoints`. Pair with onEdgeAnchor/recordStore.anchorOnCanvas and onEdgeReroute/recordStore.rerouteOnCanvas to let people set them.
  - pending: string[] — Record ids whose card stands for a suggestion nobody has agreed to yet — an extraction pass can stage a whole record, so it is on the canvas and answers every query the accepted ones do. Read onto the matching node as `data.pending`, for a style rule or a node action to pick up with `{ when: { "data.pending": true } }` — the `data.` prefix is required, since a bare key reads a node field rather than seeded data, and matches nothing here. Ids rather than a query because only the capability that staged them knows which they are.
  - changed: string[] — Record ids that are agreed but carry a suggested change — a staged edit to something a person already owns. Read onto the matching node as `data.changed`. Separate from `pending` because it wants the opposite drawing: the record is settled, so mark it rather than fade it.
  - hidden: string[] — Record ids to leave off the canvas entirely — no card, and no connection to or from one. For narrowing what is shown (hiding suggestions nobody has agreed to), where an opacity rule would still leave the card pressable and its lines drawn.
  - counts: string[] — Relations to count on each card, read onto its data as `<name>Count` — `["signals", "comments"]` for "what have people made of this". The projections ride in the read the seed already makes, so a canvas of three hundred cards pays nothing extra; a query per card would be three hundred subscriptions. A type that does not declare the relation is asked for no count rather than refusing the read, since a refusal would take that whole type off the canvas. Absent for a count of zero, like every other unset field, so a rule can ask whether it is there.
  - weigh: { signalTypeId: string; aggregate?: string; mode?: string; rangeMin?: number; rangeMax?: number; step?: number; excludeAuthors?: string[]; me?: string } — Weigh each card by one reaction type, read onto its data as `weight` (with `weightCount`, `weightMine` — what `me` gave — and `weightType`). Read the way every reaction surface reads the type: a toggle counts, a vote nets out, a rating or slider averages, and the community's own `aggregate` where the mode can express it. Absent for a vote or rating nobody has given; zero for a count. What a forest's `sortBy: 'weight'` and a heat rule read. Pass the type's `rangeMin`, `rangeMax` and `step` too, so the pretend people a development build can add answer within its range.
  - weights: string — How much each person's voice counts in `weigh` — `did=50,did=0` in whole percent, anyone not named in full; 0 leaves them out. Applied to the answers already read, so changing it re-weighs the canvas with no query — a slider can drive it. The seed reports who answered as `onSeedSummary`'s `voices`: `{ author, cards, mean }`, the busiest first.
  - limit: number — Rows per type. Default 200.
  - Example: `{ "source": "canvas", "options": { "canvas": { "$": "local.canvasId" } } }`
- `dataset` — Seeds a single node for the current space — the starting point for exploring outward.
  - label: string — What the node is called. Defaults to the space name.
  - Example: `{ "source": "dataset", "options": { "label": "This space" } }`

**expander**

- `entity` — Follows an entity's typed relations, forwards and backwards, from the dataset's schema. The default for knowledge maps.
  - relations: string[] — Only follow these.
  - exclude: string[] — Never follow these.
  - Example: `"expansion": { "expanders": ["entity"], "direction": "both", "defaultDepth": 1 }`
- `collection` — Opens a container into its children through an untyped to-many relation — the drill-down the schema cannot describe. Recurses naturally into nested collections.
  - parents: string[] — Container types. Defaults to CollectionBlock.
  - via: string — Relation holding the children. Defaults to "children".
  - children: string[] — Child entity types to look for.
  - Example: `"expansion": { "expanders": ["collection"], "defaultDepth": 2, "direction": "out" }`
- `schema` — Opens an entity-type node from the schema seed into instances of that type — the step from "what kinds of thing are here" to "here they are". Paired with the schema seed it makes one map out of two.
  - limit: number — Instances loaded per type. Default 25.
  - Example: `"seeds": { "source": "schema" }, "expansion": { "expanders": ["schema", "entity"] }`
- `property` — Opens an instance out into its own scalar fields, and optionally into shared value nodes so instances converge on common values. The resolution level below an entity.
  - properties: string[] — Only show these fields.
  - valueNodes: boolean — Promote values to shared nodes. Defaults to true.
  - Example: `"expansion": { "expanders": ["property"] }`

**layout**

- `force` — Force-directed, with warm start so newly expanded nodes settle around what is already placed rather than restarting the whole map. The default.
  - distance: number — Preferred edge length. Default 90.
  - charge: number — Repulsion; more negative spreads further. Default -220.
  - collide: number — Minimum spacing. Default 28.
  - Example: `{ "type": "force", "options": { "distance": 140 } }`
- `tree` — Layered hierarchy from the graph roots. The right choice for containment and org charts.
  - direction: "down" | "right" — Which way the tree grows from its roots. Default "down".
  - levelGap: number — Distance between one rank and the next.
  - siblingGap: number — Distance between neighbours on the same rank.
  - Example: `{ "type": "tree", "options": { "direction": "right", "levelGap": 200 } }`
- `forest` — Separate tidy trees side by side along one named connection, each parent centred over its own children, siblings ordered by a field on the card, and everything the connection does not touch in a labelled zone of its own. This is the layout for a map somebody reads an ORDER off — "the strongest option is leftmost". Prefer `tree` where shared parents are the point and crossings are what to reduce, since ordering siblings by data and minimising crossings are the same decision and cannot both be had.
  - spine: { field: string; value: string | number | boolean } — Which connections make a parent a parent — one field of a line and the value it must hold. `{ "field": "data.relationshipTypeId", "value": "<id>" }` follows one kind a community named. Absent follows every line, which is right only where they are all one kind. Every other line is still drawn; it simply does not decide where a card goes.
  - sortBy: string — Card data field deciding sibling order, left to right — "weight" for strongest first, "createdAt" for oldest first, "canvasRank" for an order somebody dragged. Absent leaves the order the graph holds.
  - sortDirection: "asc" | "desc" — Default "asc", which is what a date wants.
  - tiebreakBy: string — The second key, used only where the first ties. Default "createdAt". Not decoration: two cards on the same number of votes otherwise swap places whenever anything else in the space changes, which reads as the map being unstable.
  - card: { width: number; height: number } — The box every card is allotted — uniform on purpose, since ranks read as significance and cards at the sizes somebody chose on a freeform canvas would claim some the data does not support. What a card is DRAWN as is a style rule.
  - siblingGap: number — Clear space between two cards side by side. Defaults to a share of the card's WIDTH, so a reader switching to large cards gets room to match — a constant is comfortable at one card size and reads as cards touching at another.
  - levelGap: number — Clear space between one rank and the next. A share of the card's HEIGHT, and a larger share than the sibling gap: a rank is read along, so its cards belong together, where the vertical gap is what the lines live in and has to be legible on its own.
  - treeGap: number — Clear space between one tree and the next. Default three sibling gaps.
  - unattached: "right" | "bottom" — Where cards on no tree go. Default "right"; "bottom" suits a narrow screen.
  - unattachedColumns: number — How many cards wide that zone is. Default 3.
  - unattachedLabel: string — What the zone is called; the count is appended. Default "Unconnected", and an empty string leaves it unlabelled.
  - Example: `{ "type": "forest", "options": { "spine": { "field": "data.relationshipTypeId", "value": { "$": "local.spine" } }, "sortBy": "weight", "sortDirection": "desc", "card": { "width": 180, "height": 120 } } }`
- `radial` — Concentric rings by hop distance from the roots — reads as distance from a centre.
  - ringGap: number — Distance between one ring and the next.
  - Example: `{ "type": "radial" }`
- `grid` — Uniform grid, optionally ordered by a node data field. Honest default when edges say little.
  - columns: number — How many columns. Derived from the node count when omitted.
  - sortBy: string — Node data field to order by.
  - Example: `{ "type": "grid", "options": { "columns": 6, "sortBy": "name" } }`
- `manual` — Positions come from the nodes themselves — a canvas, where position is the data being edited rather than something derived. Pair with drag-node and persist via onNodeDragEnd.
  - xField: string — Node data field holding x. Default "x".
  - yField: string — Node data field holding y. Default "y".
  - size: { width: number; height: number } — The box a card takes. A node with no stored position is parked in the view, in the first slot clear of every card already there — pass the card size so slots do not overlap. Absent means a 160-sided square.
  - widthField: string — Node data field holding a resized card’s own width, so parking keeps clear of it.
  - heightField: string — The same, for height.
  - margin: number — Clear space around a parked card. Default 24 with `size`.
  - Example: `{ "type": "manual", "options": { "size": { "width": 180, "height": 135 } } }`

**style**

- `curve` — Edge style — the shape a connection is drawn with. "smooth" (default) leaves and arrives along the axis the edge mostly runs on, the flow-chart S, so it reads as direction and suits hierarchies and pipelines. "straight" is a direct line, right when the layout is already doing the talking. "arc" bows to one side, for a graph dense enough that lines need telling apart by shape. "step" turns at right angles, for containment and org charts where the eye follows a rank. Two nodes related in both directions are always separated — shifted sideways, or crossed at different points — so picking a shape never hides a relationship.
  - Example: `"edgeStyle": [{ "style": { "curve": "smooth" } }]`
- `sourceAnchor / targetAnchor` — Edge style — which side of each node the line leaves and arrives on ("n", "e", "s", "w"). Normally derived from where the two nodes are, which is right on a canvas, where a line between two cards somebody placed should take the shortest sensible path. It is wrong wherever the ARRANGEMENT carries the meaning: in a downward tree a parent's children sit below it and spread sideways, so the geometry attaches the outer ones to their left and right edges and only the middle one to its top — three children, three different-looking relationships, when they are the same relationship. A rule, so an edge's own stored anchors still win: those are one canvas's tidying of one connection, which is the narrower fact.
  - Example: `"edgeStyle": [{ "style": { "sourceAnchor": "s", "targetAnchor": "n" } }]`
- `ignoreRoute` — Edge style — ignore what one canvas has tidied about this connection, its stored anchors and the points it is bent through, and draw it as the rules say. The usual precedence is the other way round, and that is right on a canvas: a line somebody pulled to a card's left side is a decision about that connection, narrower than any rule. It is wrong wherever the ARRANGEMENT carries the meaning. In a tree every child hangs off its parent's underside and is met at its own top, and that uniformity is what makes a rank readable — so one line bending around something that is no longer in the way is a card disagreeing with the shape for a reason that belonged to a different reading of the same records. Nothing is unwritten: the route is still stored, still the canvas's, and comes back the moment an arrangement that reads it does — and a bend appearing or going away is animated over the switch rather than snapped.
  - Example: `"edgeStyle": [{ "style": { "sourceAnchor": "s", "targetAnchor": "n", "ignoreRoute": true } }]`
- `arrow` — Edge style — which ends carry an arrowhead. "target" (default) points at the thing being related to; "both" for a mutual relationship drawn as one line; "none" when the relation has no direction worth showing. The head scales with the line's width, and the line stops short of it rather than running underneath.
  - Example: `"edgeStyle": [{ "style": { "arrow": "none" } }]`
- `scaleWithZoom` — Edge style. true (default) treats the line as part of the drawing, so it thickens as you zoom in — right for a canvas. false pins it to a constant on-screen width, so hairlines stay visible when you zoom out to see a whole network.
  - Example: `"edgeStyle": [{ "style": { "scaleWithZoom": false } }]`
- `content` — Node style, cards only. Names a host-supplied component to draw INSIDE the card instead of a text label — WE registers `block`, which renders a CollectionBlock's composed content the way a post card does, and `record`, which does the same for a note and draws any other record as its kind, its name and every value it holds. A label can only ever be the first line, so a card holding an image and three paragraphs shows sixty characters and gives no sign the rest exists. Clipped, not scrolled: a card is a preview, and what does not fit is reached by opening it. Falls back to the label when the host supplies no component by that name.
  - Example: `"nodeStyle": [{ "style": { "shape": "card", "width": 180, "content": "block" } }]`
- `contentMinZoom` — Node style. Hides card content below this zoom and falls back to the label. The sibling of labelMinZoom, and the thing that decides whether rich cards scale: a hundred documents rendered at once is a hundred component trees, and at the zoom where a canvas reads as coloured rectangles none of them is legible anyway.
  - Example: `"nodeStyle": [{ "style": { "shape": "card", "content": "block", "contentMinZoom": 0.5 } }]`
- `badge` — Node style, cards only. Names a host-supplied mark to pin to the card's lower edge — one a reader can press without picking the card up. WE registers `reaction`, which shows a card's score for the reaction a tree is ordered by and lets a reader give, change or take back their own. Not content: a card's content is inert, so a press anywhere on it starts a drag, and it is clipped to the card's shape; a badge sits on the edge, outside the clip, and takes its own presses. Nothing is drawn when the host supplies no badge by that name.
  - Example: `"nodeStyle": [{ "style": { "shape": "card", "badge": "reaction" } }]`
- `scaleLabelWithZoom` — Node style. true (default) scales the label with the camera; false keeps it a constant on-screen size, which keeps text readable at any zoom on a map you navigate by reading. Affects the label only — a node mark always scales, because its size and its hit area are both world units.
  - Example: `"nodeStyle": [{ "style": { "scaleLabelWithZoom": false } }]`
- `labelMinZoom` — Node style. Hides the label below this zoom level, so a dense graph stays readable when zoomed out and gains its detail as you move in.
  - Example: `"nodeStyle": [{ "style": { "labelMinZoom": 0.6 } }]`

**metric**

- `degree` — How connected a node is, normalised 0..1. The usual answer to "make the important things bigger". Reference it from a style value rather than a fixed number.
  - range: [number, number] — Output range, e.g. [8, 30].
  - Example: `"nodeStyle": [{ "style": { "size": { "metric": "degree", "range": [10, 34] } } }]`
- `community` — Groups the visible graph by label propagation. Pair with scale: "categorical" to colour each cluster differently — this is what makes a cluster map.
  - rounds: number — Propagation rounds. Default 8.
  - Example: `"nodeStyle": [{ "style": { "color": { "metric": "community", "scale": "categorical" } } }]`
- `field` — Reads a number already on the card and normalises it against the rest of the visible graph — what makes a HEAT MAP. Pair it with a scale to colour by it — a named one ("heat") steps, and two colours, scale: { from, to }, blend continuously low to high, so a card’s shade says where in the range it sits — or a range to size by it. Works on a freeform canvas as readily as on a tree, since it is a style value rather than an arrangement. A card with no value is left out entirely rather than scored zero, so it falls through to whatever an earlier rule set: "nobody has answered this" and "this is the coldest thing here" are different facts.
  - from: string — The data field to read — "weight", "signalsCount", or a date such as "createdAt".
  - min: number — With max, map against a FIXED domain instead of the data's own — for a value whose scale means something absolutely (a 0..1 share, a 1..5 rating), where normalising to what is on screen would make one card at two stars look like the best there is. Values outside are clamped.
  - max: number — The top of that fixed domain.
  - Example: `"nodeStyle": [{ "style": { "color": { "metric": "field", "options": { "from": "weight" }, "scale": "heat" } } }]`

**control**

- `zoom-in` — Zooms toward the centre of the view. Shown by default.
  - Example: `"controls": ["zoom-in", "zoom-out", "fit"]`
- `zoom-out` — Zooms out from the centre. Shown by default.
- `fit` — Frames everything currently on the graph. Deliberately not a re-layout — it moves the camera, never the nodes.
- `pin` — Holds the selected nodes where they are, so the layout stops moving them; press again to release. The usual way to shape a force graph — put the thing you care about where you want it, hold it there, and let the rest settle around it. Held nodes are ringed so the state is visible. Not shown by default: on a canvas every node is placed already and it means nothing.
  - Example: `"controls": ["zoom-in", "zoom-out", "fit", "pin"]`
- `lock` — Blocks moving nodes, so a graph cannot be rearranged by accident while it is being read or shown to someone. Affects dragging only — panning, zooming and a settling force layout all carry on. Not shown by default, and only meaningful where the template allows dragging at all.
  - Example: `"controls": ["zoom-in", "zoom-out", "fit", "lock"]`
- `relayout` — Re-runs the layout. Not shown by default: a rescue for a tangled force graph, and destructive on a canvas, where it would discard every position somebody chose.
  - Example: `"controls": ["zoom-in", "zoom-out", "fit", "relayout"]`

**behaviour**

- `pan-zoom` — Drag the background to pan, wheel to zoom about the pointer. **List it last.** It claims a press on empty canvas, and dispatch stops at the first behaviour that claims — so anything after it never sees a background press. Listed before `select`, clicking empty canvas silently stops clearing the selection.
  - Example: `"behaviours": ["select", "expand-on-double-click", "pan-zoom"]`
- `select` — Click to select, shift-click to extend, background to clear. Emits onNodeClick, and onSelectionChange with an empty list when a background click clears it. Must be listed BEFORE pan-zoom, which claims the background press it needs to see.
- `marquee-select` — Drag a rectangle over empty canvas to select everything it touches, marking each card as the rectangle reaches it. Additive rather than a mode: it takes a background press only when Shift or Ctrl/Cmd is held, or when `armed` is set, so a plain drag still pans. List it BEFORE pan-zoom, which is the background fallback and would otherwise claim the press first. Selecting touches rather than encloses, so a card wider than the view can still be caught. Holding the modifier adds to whatever is already selected.
  - armed: boolean — Whether a plain background drag sweeps rather than pans. Default false. Arm it from a control the user can see — a touchscreen has no modifier keys.
  - Example: `"behaviours": [{ "type": "marquee-select", "options": { "armed": { "$": "local.selecting" } } }, "select", { "type": "drag-node", "options": { "pin": true } }, "pan-zoom"]`
- `drag-node` — Drag a node to move it, and every other selected node with it — so a selection built by clicking or sweeping travels as one. Releases on drop by default so the layout stays in charge; pass { pin: true } on a canvas.
  - pin: boolean — Leave the node pinned where it was dropped.
  - Example: `{ "type": "drag-node", "options": { "pin": true } }`
- `arrange-nodes` — Drag a card to another place in a hierarchy, with the tree showing the result as you go — emitting onNodeArrange when it is dropped. One rule — the place whose ghost would be nearest the card: every place it could go (each gap in each row, the level beneath a card with no children, its own place) is asked of the layout, and the one that would draw it closest to the middle of the card in the hand, on its level, is the one shown — so the gap always opens under the card, however the tree reshuffles to make room and wherever the card was picked up; where the end of one family and the start of the next land at one spot, just left of it is the first and just right the second; between levels the last place shown holds; in the unconnected zone it comes out of its tree; over its own place or off the tree it goes back where it was and nothing is emitted. A place it would land is drawn as a dashed ghost with the line it would have, and its own place as a faint hole with no line, so ‘nothing will happen’ never looks like a destination; on release the card travels into it and is held there until the write comes back, so the drop is one movement. The preview needs a layout that reports its hierarchy (forest); on one that does not, the gesture reports CHILD, SIBLING or LOOSE from where it is dropped, with no preview. Writes nothing: what a hierarchy is differs per graph, so the template decides. The alternative to drag-node rather than an addition to it — listing both has them fight for the same press.
  - reorder: boolean — Whether a drag may change the order of siblings. Default true. Set it false while siblings are ordered by something a drag cannot change — a date, a tally — so a card can still move under another parent, and lands where that order puts it, but is never shown sliding into a place it would not keep.
  - keep: string[] — Fields of a connection that keep a card in its tree: dragging into the unconnected zone is refused for a card whose connection to its parent holds a value in any of them, and the preview says why before it is let go. WE passes ['commentsCount', 'signalsCount'] with the canvas seed's `counts`, because it will not delete a connection people have discussed.
  - keepReason: string — What the preview says when `keep` refuses a drop.
  - reach: number — Without a hierarchy to preview against: how far from a card, in world units, a drop still counts as beside it. Default 240.
  - band: number — Without a hierarchy to preview against: how tall the band searched for siblings is. Defaults to the dragged card's own height.
  - Example: `"behaviours": ["select", { "type": "arrange-nodes", "options": { "reorder": true } }, "pan-zoom"]`
- `connect-nodes` — Drag from one node to another to connect them, emitting onEdgeCreate with both ends. Writes nothing — what a connection means is the template's decision, so it answers by creating whatever record it thinks the connection is. List it BEFORE drag-node: both claim a press on a node and the first wins. Arm it from a control the user can see rather than a modifier key, which is undiscoverable and absent on a touchscreen.
  - armed: boolean — Whether the gesture is live. Default true. Disarmed, the press falls through to drag-node.
  - button: "primary" | "secondary" — Which button starts it. Default "primary", armed as above. "secondary" is the quick form: a right-drag from a card draws a line whether or not anything is armed, leaving the left button to move cards — list it FIRST. A right-click that does not travel draws nothing, and the browser menu is kept off cards while it is listed. Touchscreens have no right-click, so keep another way to connect.
  - Example: `"behaviours": [{ "type": "connect-nodes", "options": { "button": "secondary" } }, "select", { "type": "drag-node", "options": { "pin": true } }, "pan-zoom"]`
- `node-double-click` — Double-click a node to emit onNodeDoubleClick, with the record it stands for resolved onto the payload. Writes nothing — what opening a node means is the template's decision. Pairs with canvas-double-click, which handles the same gesture on empty canvas; list both and exactly one fires. Do NOT list it alongside expand-on-double-click, which claims the same gesture to do something else.
  - Example: `"behaviours": ["node-double-click", "canvas-double-click", "pan-zoom", "select"]`
- `canvas-double-click` — Double-click empty canvas to emit onCanvasDoubleClick with the world point. Writes nothing — what gets made there is the template's decision. List it BEFORE pan-zoom, which is the background fallback. Claims only the background, so it composes with expand-on-double-click: a double-click on a node opens it, one beside a node creates.
  - Example: `"behaviours": ["canvas-double-click", "pan-zoom", "select", { "type": "drag-node", "options": { "pin": true } }]`
- `expand-on-double-click` — Double-click a node to expand it. The usual gesture on a map you also want to select on.
  - direction: "in" | "out" | "both" — Which way relations are followed when the node opens. Default "both".
  - Example: `{ "type": "expand-on-double-click", "options": { "direction": "out" } }`
- `expand-on-click` — Single click expands — for maps meant purely for exploring, where selection is not needed.
  - direction: "in" | "out" | "both" — Which way relations are followed when the node opens. Default "both".
  - Example: `{ "type": "expand-on-click", "options": { "direction": "out" } }`

---

## Design System Props

Most @we/primitives inherit **all** layers below. Props use design token values — not raw CSS.

### Token Value Reference

| Token Type | Valid Values |
|---|---|
| SpaceValue | "0", "100", "200", "300", "400", "500", "600", "700", "800", "900", "1000" (or CSS length e.g. "16px") |
| ColorValue | A **role** — see the table below — or a scale position "{hue}-{shade}" where hue = neutral, primary, success, warning, danger and shade = 0, 25, 50, 75, 100, 200–900, 1000. Also "white", "black". (or CSS color). **Prefer a role.** |
| RadiusValue | "0", "100", "200", "300", "400", "500", "600", "700", "800", "900", "pill", "full" (or CSS length). Also five *theme-family* names that follow the theme instead of naming a size — see "Theme families" below. Prefer them on an `EditableImage`, a `Card`, or a raw element standing in for one: a pinned "full" or "pill" cannot follow a theme's shape settings. Note "full" is 50%, so it is an ellipse on any box that is not square; reach for "pill" on wide boxes. |
| ShadowValue | "sm", "md", "lg", "xl" |
| FontSizeValue | "base", "100", "200", "300", "400", "500", "600", "700", "800", "900", "1000" (or CSS length) |
| FontFamilyValue | "base" (or CSS font-family) |
| LineHeightValue | "none", "tight", "snug", "normal", "relaxed", "loose" (or CSS value) |
| LetterSpacingValue | "tighter", "tight", "normal", "wide", "wider", "widest" (or CSS value) |
| FontWeightValue | Named tokens: "regular" (400), "medium" (500), "semibold" (600), "bold" (700). Numeric: "100"–"900". CSS pass-through: "light", "normal", "bolder". |

### Theme families — for `r`, `p` and `gap`, the counterpart of a colour role

A colour role says what a colour is *for*. A **family** says what kind of thing a box *is*, so the
theme can decide its shape and density: buttons are rounded like this, sheets like that. Naming one
is how a box follows a theme's `surfaceRadius` or `surfacePadding` instead of pinning a number.

| Name | `r` | `p` | `gap` | For |
|---|---|---|---|---|
| `control` | ✓ | | ✓ | Buttons, badges, tags — anything pressed. |
| `surface` | ✓ | ✓ | ✓ | Cards, modals, sheets — **and anything inset inside one**. |
| `input` | ✓ | | | Fields, selects, pickers. |
| `avatar` | ✓ | | | Anything square that reads as a profile picture. |
| `media` | ✓ | | | A **full-bleed** banner, video or embed spanning an edge. |

`surface` and `media` read the same theme variable and differ only in what they fall back to when a
theme sets nothing: `surface` is rounded like a card, `media` is **square**. Pick by whether the box
is inset in something rounded or spans the edge — a cover image inside a modal is `surface`, the
same image as a page-width header is `media`.

```json
{ "type": "Column", "props": { "bg": "surface", "r": "surface", "p": "surface", "gap": "surface" } }
```

**The blanks are constraints, not gaps.** A family only takes `p` when its theme value is a single
length: `control`'s padding is horizontal-only (the vertical comes from the control's height, per
size) and `input`'s is a full shorthand, and padding is assembled as four values in one declaration,
so either would produce an invalid rule.

**Only these props.** A family is meaningless on a margin or an offset — it says how much room a box
puts *inside* itself, which answers nothing about the space between it and its neighbour. `m:
"surface"` resolves to nothing and warns.

### Semantic Colour Roles — reach for these before a scale position

A scale position says *which grey*. A role says *what the colour is for*, and that is what a theme
can redesign. Some relationships invert between light and dark — a raised surface gets **lighter**
in dark rather than casting a shadow — and a scale position cannot express that, because the whole
scale flips together. Templates written with roles restyle correctly under any theme; templates
written with `neutral-100` are frozen into one theme's idea of what that grey meant.

Two naming conventions run through the table. A bare noun is a **fill or a foreground in its own
right** (`surface`, `accent`, `text`). `on<Fill>` is a foreground that sits **on** a
specific fill and exists to contrast with it (`on-accent`, `on-inverse`) — so `accent-text`
is the accent *used as* text, and `on-accent` is the text *placed on* the accent. They are
different colours and the prefix is what tells you which you want.

**Use a role for every `bg`, `color` and border colour.** Reach for a scale position only when the
colour is a *palette* rather than a meaning — a graph's node colours by category, a chart series,
a user-chosen swatch.

| Role | Use for |
|---|---|
| `chrome` | The app's ground, and the bottom of the stack: the sidebar, the module rail, a docked panel's frame, and the app's own screens (profile, settings, about, the marketplace). Reach for it when what you are painting belongs to the app rather than to a community — and for a space template meant to blend into the app instead of sitting above it. |
| `page` | The plane a **space's own content** sits on, a step above the chrome framing it, and what the surfaces below are measured from. Set it on a space template's root node. |
| `surface` | A card, panel or sheet sitting on the page. |
| `surface-raised` | Something floating above the page — a popover, a floating bar, a docked rail with a shadow. |
| `surface-sunken` | A well recessed into a surface — an inset box, a code block, an input trough. |
| `surface-hover` / `surface-active` | Row and item feedback — something sitting **on** a surface. Use inside `hoverProps` / `activeProps`. |
| `surface-sunken-hover` | A **well** lifted — an input, a textarea, a picker trigger. Hovering one with `surface-hover` lands it at about surface level and it stops looking recessed, so use this wherever the resting fill is `surface-sunken`. One state, not a hover/pressed pair: a field is clicked *into* rather than pushed, so hover, press and focus all resolve here and the ring is what says "focused". |
| `control-surface` | The filled neutral of a *control* — a slider or switch track, a progress trough, a scrollbar thumb, a secondary button, a count chip. Not a surface and not a state. |
| `text` | Primary body and heading text. |
| `text-muted` | Secondary text — captions, labels, metadata. |
| `text-faint` | Tertiary text — placeholders, disabled labels, decorative icons. |
| `surface-inverse` | A surface deliberately opposite to the page — a tooltip. Holds a fixed lightness, so it does *not* flip with the theme. |
| `on-inverse` | Text or an icon **on top of** `surface-inverse` — a tooltip's own text. **Not** for text on the accent, which is `on-accent`. |
| `border` | Default borders and dividers. |
| `border-strong` | Emphasised separation — two regions that are genuinely apart. Not a hover state. |
| `border-hover` | The edge of an interactive box under the pointer. Sits between `border` and `border-strong`, which are three ramp steps apart; borrowing the latter for hover makes an outline jump rather than acknowledge. |
| `accent` | An accent *fill* — a primary button, a selected disc. |
| `accent-hover` / `accent-active` | Hover and pressed states of an accent fill. |
| `on-accent` | Text or an icon **on top of** an accent fill. |
| `on-accent-muted` | Secondary text on an accent fill — a caption under a heading on an accent panel, or on `gradient-primary`. The `text-muted` of fills, and the **only** correct choice there: `text-muted` and `text-faint` are measured against the *page*, so on a fill they are measured against the wrong thing and can vanish entirely. |
| `accent-text` | The accent used **as text** — an accented heading or icon on an ordinary surface, where `accent` is often too light to read. |
| `accent-muted` | An accent-tinted fill — a selected row, a subtle highlight. |
| `focus` | The focus ring. Rarely set directly; `--we-ring-color` already resolves to it. |
| `danger-text` / `success-text` / `warning-text` | Status as a **foreground** — an error message, a warning icon, a "connected" tick. |
| `danger-surface` / `success-surface` / `warning-surface` | The tinted **panel** behind status content. |
| `overlay` | The scrim behind a modal or drawer. Carries its own alpha. |
| `shadow-color` | The colour shadows are built from. |

```json
{ "type": "Column", "props": { "bg": "surface", "border": "1px solid border" }, "children": [
  { "type": "we-text", "props": { "variant": "heading-md", "color": "text" }, "children": ["Title"] },
  { "type": "we-text", "props": { "color": "text-muted" }, "children": ["Supporting line"] }
]}
```

Roles work anywhere a colour token does, including inside a border shorthand
(`"1px solid border"`) and behind a ternary
(`{ "$": "row.selected ? 'accent-muted' : 'surface-sunken'" }`).

**Not `$if` in a prop.** `$if` is a *node* type and, in a value position, resolves to a handler —
so the colour resolver is handed a function, paints nothing, and warns about nothing at runtime. A
condition that chooses a value is a ternary, which is what the expression language has one for.

The validator refuses it. It asks whether the prop holds a function rather than whether its name
starts with `on`, so a handler prop that is not an event — `we-modal`'s `close`, which every
`discardGuard` passes a `$if` to — stays legal.

**Always kebab-case: `"surface-sunken"`, never `"surfaceSunken"`.** The camelCase spelling is the
TypeScript key of a `ThemeRole`; a schema writes the CSS spelling. Getting it wrong fails silently —
the value resolves to a variable that does not exist and the element paints nothing at all — so the
validator rejects it with the right spelling rather than letting it through.

**Layout-only primitives** — these accept only Layout props (not Visual, Flex, Typography, or State):
we-divider, we-icon, we-menu-group, we-popover, we-spinner, we-tooltip

### Layout

| Prop | Type | Description |
|------|------|-------------|
| width | string | Element width |
| height | string | Element height |
| minWidth | string | Minimum width |
| minHeight | string | Minimum height |
| maxWidth | string | Maximum width |
| maxHeight | string | Maximum height |
| position | "relative" \| "absolute" \| "fixed" \| "sticky" | CSS position |
| top | SpaceValue | Top offset — space token or CSS length |
| right | SpaceValue | Right offset — space token or CSS length |
| bottom | SpaceValue | Bottom offset — space token or CSS length |
| left | SpaceValue | Left offset — space token or CSS length |
| zIndex | number | Stack order |
| display | "flex" \| "block" \| "inline" \| "inline-block" \| "grid" \| "inline-flex" | Display mode |
| flex | string | Flex shorthand (e.g. "1", "0 0 auto", "none") — controls grow/shrink/basis |
| flexShrink | number \| string | `flex-shrink` alone, for the common "just don't let it shrink" case (`0`) without committing to a grow and a basis |
| alignSelf | string | Override parent cross-axis alignment for this child |
| overflow | "hidden" \| "auto" \| "overlay" | Overflow behavior, both axes |
| overflowX | "hidden" \| "auto" \| "overlay" | Horizontal overflow alone — a nav strip or tab bar that scrolls sideways instead of pushing the page wide |
| overflowY | "hidden" \| "auto" \| "overlay" | Vertical overflow alone |
| scrollbarWidth | "auto" \| "thin" \| "none" | How much room the scrollbar takes. `none` for a strip in fixed-height chrome, where a gutter would not fit. **Use `none` or leave it unset — never `thin` or `auto`:** Chromium reads this property as "use the platform scrollbar" and drops the app's own styling for that element, so it becomes the one scroll region that does not match the rest (a different colour, square corners, and stepper arrows on Linux). `none` is safe because a hidden bar has nothing to style. |
| scrollbarGutter | "auto" \| "stable" \| "stable both-edges" | Reserve the gutter whether or not it scrolls, so content does not shift when a scrollbar appears |
| m | SpaceValue | Margin (all sides) |
| mx | SpaceValue | Margin left + right |
| my | SpaceValue | Margin top + bottom |
| mt | SpaceValue | Margin top |
| mr | SpaceValue | Margin right |
| mb | SpaceValue | Margin bottom |
| ml | SpaceValue | Margin left |

**`position`, `top`, `right`, `bottom` and `left` do not respond to a breakpoint or a state.**
They are excluded from the tier and state pipelines, so `mdUpProps: { left: '300px' }` would set a
variable nothing reads — **the validator refuses it** rather than letting it through silently. To
move something at a breakpoint use `x` / `y` / `rotate` (see Visual), which compose into
`transform` and do tier — as do `width`, `height` and `zIndex`.

**A row that overflows is a row where nobody said who gives up space.** Inside a `Row`, a child's
`maxWidth` is not a promise: a flex item's automatic minimum size is its *content*, so an item whose
content cannot narrow — a strip of `we-button`s, which set `white-space: nowrap` — refuses every
request to compress. Flexbox then takes the whole deficit out of whichever sibling *can* shrink
(usually a run of text, which folds onto two lines) and pushes the rest past the container. Where a
template is mounted in a scrolling box, that reads as the entire page sliding sideways.

Say who does what, and the row cannot overflow:

```json
{ "type": "Row", "props": { "ay": "center" }, "children": [
  { "type": "Row", "props": { "flex": "1 1 auto", "minWidth": "0", "overflowX": "auto", "scrollbarWidth": "none" },
    "children": ["…the strip that gives up space and scrolls instead…"] },
  { "type": "Row", "props": { "flex": "0 0 auto" },
    "children": ["…the ornament that never absorbs somebody else's overflow…"] }
]}
```

`minWidth: '0'` is the half that gets forgotten. Without it `overflowX` has nothing to do, because
the item is never asked to be narrower than its content in the first place.

### Visual

| Prop | Type | Description |
|------|------|-------------|
| bg | ColorValue | Background color (token) |
| bgImage | string | Background image — a URL, or a CSS gradient (linear-, radial- or conic-gradient, including several comma-separated for a mesh). Sets background-image, defaults background-size to cover, background-position to center, background-repeat to no-repeat. Composes with bg, which paints beneath it |
| bgFit | "cover" \| "contain" | Background image sizing (default: "cover") — only meaningful with bgImage |
| bgPosition | string | Background image position (default: "center", e.g. "top", "50% 20%") — only meaningful with bgImage |
| bgImageOpacity | number | Fades bgImage only (0–1), independent of the element's own content/opacity — only meaningful with bgImage |
| bgImageTint | ColorValue | Color bgImage fades toward as bgImageOpacity decreases (default: the element's own `bg`, or neutral-0) — only meaningful with bgImageOpacity |
| color | ColorValue | Text/foreground color (token) |
| opacity | number | Opacity (0–1) |
| border | string | Border shorthand (e.g. "1px solid border" — color tokens are resolved) |
| borderColor | ColorValue | Border color (token, e.g. "border", "border-strong") |
| borderTop | string | Top border shorthand (color tokens resolved) |
| borderRight | string | Right border shorthand (color tokens resolved) |
| borderBottom | string | Bottom border shorthand (color tokens resolved) |
| borderLeft | string | Left border shorthand (color tokens resolved) |
| borderWidth | string | Border width (raw CSS, e.g. "1px", "2px 0") |
| shadow | "sm" \| "md" \| "lg" \| "xl" | Shadow token |
| cursor | "pointer" \| "default" \| "text" \| "not-allowed" | Cursor style |
| pointerEvents | "none" \| "auto" | Pointer events |
| transform | string | CSS transform |
| x | number \| string | Horizontal offset from where the element would otherwise sit. A bare number is px; a string carries its own unit. Composes into `transform` |
| y | number \| string | Vertical offset, same rules |
| rotate | number \| string | Degrees clockwise about the element's own centre. A bare number is degrees |
| transition | string | CSS transition. Durations may be animation tokens (`'0'`–`'500'`): `'width 300 ease-in-out'`. Prefer the token — a theme's animationSpeed preset overrides those, so `300` respects a reduced-motion setting where `300ms` overrides it. Use for a property whose *value* changes in place (a width bound to a local); for something appearing and disappearing use `$if`/`$animate` transitions instead |
| r | RadiusValue | Border radius (all corners) |
| rt | RadiusValue | Border radius top |
| rb | RadiusValue | Border radius bottom |
| rl | RadiusValue | Border radius left |
| rr | RadiusValue | Border radius right |
| rtl | RadiusValue | Border radius top-left |
| rtr | RadiusValue | Border radius top-right |
| rbr | RadiusValue | Border radius bottom-right |
| rbl | RadiusValue | Border radius bottom-left |

**Placing something: `x` / `y` / `rotate`, never `top` / `left`.** All three compose into one
`transform`, in front of any `transform` you also write — so the element is put where it goes and
turned, and anything else happens in that frame.

```json
{ "type": "Column", "props": { "x": 40, "y": 120, "rotate": -3, "mdUpProps": { "x": 300, "y": 80 } } }
```

They are the placement spelling for four reasons, any one of which decides it: the offsets are the
only ones that respond to a breakpoint at all; they compose with rotation and scale in one property
instead of fighting them; they move on the compositor, so a drag costs no layout; and they stay
correct inside a scaled surface, where a pixel offset would be measured in the wrong units.

Two things to know. A **percentage resolves against the element's own size**, not its parent's —
that is what `translate` does, and rarely what `x: '50%'` means, so give a coordinate a length.
And setting any of them makes the element a **containing block** for absolutely positioned
descendants, as any transform does.

They are meaningful anywhere, and they are *coordinates* inside a `Canvas`, whose `artboard`
declares what space those numbers are in.

### Flex (Container)

| Prop | Type | Description |
|------|------|-------------|
| direction | "row" \| "row-reverse" \| "column" \| "column-reverse" | Flex direction |
| ax | "start" \| "center" \| "end" \| "between" \| "around" \| "even" \| "stretch" | Main-axis alignment |
| ay | "start" \| "center" \| "end" \| "between" \| "around" \| "even" \| "stretch" | Cross-axis alignment |
| wrap | boolean | Enable flex wrap |
| gap | SpaceValue | Gap between children (token) |
| p | SpaceValue | Padding (all sides) |
| px | SpaceValue | Padding left + right |
| py | SpaceValue | Padding top + bottom |
| pt | SpaceValue | Padding top |
| pr | SpaceValue | Padding right |
| pb | SpaceValue | Padding bottom |
| pl | SpaceValue | Padding left |

### Typography

| Prop | Type | Description |
|------|------|-------------|
| textAlign | "left" \| "center" \| "right" \| "justify" | Text alignment |
| fontFamily | "base" \| {css-font-family} | Font family token |
| fontWeight | "regular" \| "medium" \| "semibold" \| "bold" (named tokens) or "100"–"900" (numeric) or "light" \| "normal" \| "bolder" (CSS pass-through) | Font weight |
| fontSize | "base" \| "100"–"1000" \| {css-length} | Font size token |
| lineHeight | "none" \| "tight" \| "snug" \| "normal" \| "relaxed" \| "loose" | Line height token |
| letterSpacing | "tighter" \| "tight" \| "normal" \| "wide" \| "wider" \| "widest" | Letter spacing token |
| textDecoration | "underline" \| "line-through" \| "overline" \| "none" | Text decoration |
| textTransform | "uppercase" \| "lowercase" \| "capitalize" \| "none" | Text transform |
| whiteSpace | "normal" \| "nowrap" \| "pre" \| "pre-wrap" \| "pre-line" \| "break-spaces" | How whitespace and line breaks in the source text are treated |
| overflowWrap | "normal" \| "break-word" \| "anywhere" | Where a line may break inside a word too long to fit. **Defaults to `anywhere`** — see below |

**Text that cannot break is text that breaks the page.** `overflowWrap` defaults to `anywhere` on
every typography component and on `Column`/`Row`/`Grid`/`Card`, so a URL, a DID, or a transcriber's
run-together output wraps instead of stretching its card off the screen. **Do not set it, and do not
reach for `styles: { 'word-break': ... }` — that is the patch this default replaced.**

Set `overflowWrap: 'normal'` only to deliberately opt a box *out* of breaking. Note `'break-word'` is
the value that looks right and is not: it breaks in the same places as `anywhere` but does not
reduce the element's min-content width, and a flex item and a `1fr` grid track are both sized by
min-content — so under it the long string still pushes its container wider than the viewport.

**Typography defaults:** fontSize and fontWeight have **no built-in defaults** — omitting them inherits from parent elements (browser default is ~16px / normal weight). Do not set fontSize or fontWeight unless you need a non-default value. For example, `fontSize: '300'` (16px) and `fontWeight: '500'` (normal) are the inherited defaults — omit them.

`we-text` variants (set via the `variant` prop) bundle typography presets. Always pair with a semantic `tag` prop for correct HTML structure:
body (300, tag: p/span), label (200 + medium, tag: span), footnote (100, tag: span), subheading (400 + medium, tag: h5/p), ingress (400 + lineHeight 1.6, tag: p), heading-sm (500 + bold, tag: h4), heading-md (600 + bold, tag: h3), heading-lg (700 + bold, tag: h2), heading-xl (800 + bold, tag: h1).
Variants set size and weight only — color is always inherited or set explicitly. For muted footnote text add `color="text-muted"` explicitly.

### State

| Prop | Type | Description |
|------|------|-------------|
| hoverProps | Partial\<DesignSystemProps\> | Styles on :hover |
| activeProps | Partial\<DesignSystemProps\> | Styles on :active |
| focusProps | Partial\<DesignSystemProps\> | Styles on keyboard focus (:focus-visible) — deliberately not applied on mouse click. `we-button` and `we-input` already carry a default focus ring; only set this to override it |
| disabledProps | Partial\<DesignSystemProps\> | Styles when disabled |

### Responsive — adapting to the space available

| Prop | Type | Description |
|------|------|-------------|
| smUpProps | Partial\<DesignSystemProps\> | Values that take over from 640px up |
| mdUpProps | Partial\<DesignSystemProps\> | …from 900px up |
| lgUpProps | Partial\<DesignSystemProps\> | …from 1200px up |

A partial prop bag applying above a width, exactly like `hoverProps` applies in a state:

```json
{ "type": "Column", "props": { "gap": "300", "px": "300", "mdUpProps": { "gap": "500", "px": "400" } } }
```

**Measured against the nearest surface, not the window.** A template renders inside a docked panel,
an editor preview pane and a phone, so the viewport is the wrong subject in two of those. The host
declares a surface wherever it mounts a schema tree; a template can declare its own with `$surface`
(see Block-level Dynamic Structures) when a pane should adapt to itself rather than to the page.

**Write the narrow value at base and grow.** Every tier is min-width — there is no `smDownProps` —
so the unqualified value is what a phone gets and each tier adds room as it appears. Tiers cascade
through: something set only in `smUpProps` still applies at `lg`.

`mdUpProps`, not `mdProps`: `md` is already a size value on ~15 primitives (`size="md"`), and `Up`
settles whether a tier means at-this-width or below it. The validator suggests the right spelling.

States and tiers do not cross — there is no `mdUpHoverProps`. A tier sets base values at that width;
`hoverProps` applies at every width.

### Which mechanism to reach for

Four ways to respond to size, and they are not interchangeable:

| Need | Use | Why |
|---|---|---|
| Different **values** — padding, gap, width, font size | `*UpProps` | Pure CSS. Nothing remounts. |
| A different **tree** — a pane becomes a drawer, two panes become one | `$surface` + `$if` on `surface.tier` | Only a branch can swap DOM. |
| Same-shaped things **filling a box** — video tiles, a photo wall | `Grid` with `childAspect` | Needs both axes and an argmax; CSS cannot express it. |
| A **composition the author placed by hand** — a scrapbook, a poster, a diagram | `Canvas` with an `artboard` | The coordinates mean something; declaring the space is what lets them be scaled rather than guessed. |

**Prefer `*UpProps` for anything that is a value.** `$if` on the tier works and is tempting, because
branching is the familiar tool — but it **unmounts and rebuilds the subtree** every time the surface
crosses a threshold. That loses scroll position, half-typed input, and anything holding a live
resource: it is why a video call laid out that way goes black when its panel is resized. Reserve it
for genuine structural change.

**Prefer intrinsic sizing over either, where it works.** A wrapping `Row` whose children have a flex
basis, or a `Grid` with `minChildWidth`, adapts continuously at every width instead of at three
thresholds, needs no surface, and cannot be got wrong. Reach for a breakpoint when the layout must
genuinely change its mind, not merely stretch.

### Additional

| Prop | Type | Description |
|------|------|-------------|
| styles | Record\<string, string \| number\> | Inline CSS applied directly to the component's own element (raw CSS values allowed). For Column, Row, Grid — use this when you need CSS the DS props don't cover. Applied last, so it genuinely overrides a DS prop setting the same property. **Do not confuse with node-level styles** (see Schema Structure) which applies to a wrapper div, not the component. |
| onClick | ActionToken | Event handler (see dynamic logic) |

---

## Design Tokens

Use design tokens for spacing, color, radius, etc. Do not use raw CSS values unless using the styles prop.

animation.transition: '0', '100', '200', '300', '400', '500'

avatarSize: 'xxs', 'xs', 'sm', 'md', 'lg', 'xl', 'xxl'

border.color: 'base', 'strong'

breakpoint: 'sm', 'md', 'lg'

color.base: 'white', 'black'

color.config: 'polarity', 'lightnessFloor', 'lightnessCeiling', 'saturation', 'neutralSaturation'

color.hues: 'neutral', 'primary', 'success', 'warning', 'danger'

color.lightness: '0', '25', '50', '75', '100', '200', '300', '400', '500', '600', '700', '800', '900', '1000'

component.scrollbar: 'width', 'backgroundImage', 'background', 'cornerBackground', 'thumbBoxShadow', 'thumbBorderRadius', 'thumbInset', 'thumbBackground'

componentHeight: 'xs', 'sm', 'md', 'lg', 'xl'

font.family: 'base', 'mozilla', 'boldonse', 'mono'

font.letterSpacing: 'tighter', 'tight', 'normal', 'wide', 'wider', 'widest'

font.lineHeight: 'none', 'tight', 'snug', 'normal', 'relaxed', 'loose'

font.size: '100', '200', '300', '400', '500', '600', '700', '800', '900', '1000', 'base'

font.weight: '100', '200', '300', '400', '500', '600', '700', '800', '900', 'regular', 'medium', 'semibold', 'bold'

layout: 'xs', 'sm', 'md', 'lg'

radius: '0', '100', '200', '300', '400', '500', '600', '700', '800', '900', 'pill', 'full'

RAMP: 'light', 'dark'

shadow: 'sm', 'md', 'lg', 'xl'

size: 'xxs', 'xs', 'sm', 'md', 'lg', 'xl', 'xxl'

space: '0', '100', '200', '300', '400', '500', '600', '700', '800', '900', '1000'

STATE_STEPS: 'light', 'dark'

zIndex: 'dropdown', 'sticky', 'chrome', 'modal', 'popover', 'toast', 'tooltip'

---

## Block & Entity Models

Available data models for $query and store data:

A `json` field is a stored blob rather than a queryable value. `TextBlock.marks` is the one worth
knowing: it holds inline structure over `text` as standoff annotations — a JSON array of
`{ start, end, type, ...data }` ranges, offsets in Unicode **code points** — with types `strong`,
`em`, `underline`, `strike`, `code`, `link` (`href`), `nodeLink` and `mention` (`did`). A block
with `text` and no `marks` is one unmarked span, which is why a transcriber can write a
well-formed block without knowing marks exist. Render from it; never filter on it — anything
queryable is written beside it as a relation (a mention is also a `we://mention` link on the root,
which is where "who is named in this post" is answered).

AgentSettings extends Ad4mModel:
  Fields:
  - currentTemplateId: string = 'default' [we://current_template]
  - defaultTemplateId: string = 'default' [we://default_template]
  - currentThemeId: string = 'default' [we://current_theme]
  - defaultThemeId: string = 'default' [we://default_theme]
  - systemLightThemeId: string [we://system_light_theme]
  - systemDarkThemeId: string [we://system_dark_theme]
  - claudeApiKey: string [we://claude_api_key]
  - datasetOrder: string [we://dataset_order]
  - globalSpaceJoined: boolean = false [we://global_space_joined]
  - globalSpaceUrl: string [we://global_space_url]
  - useSpaceTemplate: boolean = true [we://use_space_template]
  - useTemplateTheme: boolean = true [we://use_template_theme]
  - themeScope: string [we://theme_scope]
  - installedModules: string [we://installed_modules]
  - moduleSettings: string [we://module_settings]
  Relations:
  - installedTemplates: HasMany → Template [we://installed_template]
  - installedThemes: HasMany → Theme [we://installed_theme]
  - spaceTemplatePreferences: HasMany → SpaceTemplatePreference [we://space_template_preference]

AudioBlock extends WeNode:
  Fields:
  - title: string (required) [we://title]
  - artist: string [we://artist]
  - audioUrl: string (required) [we://audio_url]
  - duration: number [we://duration]
  - albumArt: string [we://album_art]
  - version: number [we://version]

CalloutBlock extends WeNode:
  Fields:
  - text: string [we://text]
  - variant: string = 'info' [we://variant]
  - icon: string [we://icon]
  - version: number [we://version]

CallExtraction extends WeNode:
  Fields:
  - callId: string [we://call_id]
  - entities: string [we://extraction_targets]
  - auto: string [we://auto_interpret]

ChatMessage extends WeNode:
  Fields:
  - role: string [we://role]
  - content: string [we://content]

ChatSession extends WeNode:
  Fields:
  - name: string [we://name]
  - templateId: string [we://template_id]
  Relations:
  - messages: HasMany → ChatMessage [we://chat_message]

CodeBlock extends WeNode:
  Fields:
  - code: string (required) [we://code]
  - language: string [we://language]
  - title: string [we://title]
  - version: number [we://version]

CollectionBlock extends WeNode:
  Fields:
  - editorState: string = null [we://editor_state]
  - type: string [we://type]
  - kind: string [we://kind]
  - mode: string [we://mode]
  - title: string [we://title]
  - slug: string [we://slug]
  - description: string [we://description]
  - version: number [we://version]
  - textContent: string [we://text_content]
  - sourceRef: string [we://source_ref]
  - sourceName: string [we://source_name]
  Relations:
  - children: HasMany [we://children]
  - arranges: HasMany [we://arranges]
  - gathers: HasOne [we://gathers]
  - board: HasOne → CollectionBlock [we://board]
  - extractionPasses: HasMany → ExtractionPass [we://extraction_pass_record]
  - extracted: HasMany [we://extracted]
  - amendments: HasMany → ExtractionAmendment [we://extraction_amendment]

DividerBlock extends WeNode:
  Fields:
  - style: string = 'solid' [we://style]
  - version: number [we://version]

EdgeRoute extends Ad4mModel:
  Fields:
  - sourceAnchor: string [we://source_anchor]
  - targetAnchor: string [we://target_anchor]
  - points: json [we://route_points]
  Relations:
  - connection: HasOne [we://routed_connection]

EmbedBlock extends WeNode:
  Fields:
  - url: string [we://url]
  - target: string [we://target]
  - targetType: string [we://target_type]
  - label: string [we://title]
  - thumbnail: string [we://thumbnail]
  - sourceAuthor: string [we://source_author]
  - sourceName: string [we://source_name]
  - displayMode: string = 'card' [we://display_mode]
  - version: number [we://version]

EventBlock extends WeNode:
  Fields:
  - occurrence: string [we://occurrence]
  - title: string (required) [we://title]
  - description: string [we://description]
  - startDate: string (required) [we://start_date]
  - endDate: string [we://end_date]
  - allDay: boolean = false [we://all_day]
  - version: number [we://version]
  Relations:
  - location: HasOne → LocationBlock [we://location]

FileBlock extends WeNode:
  Fields:
  - title: string [we://title]
  - name: string (required) [we://name]
  - url: string (required) [we://url]
  - mimeType: string [we://mime_type]
  - size: number [we://size]
  - version: number [we://version]

ImageBlock extends WeNode:
  Fields:
  - src: string (required) [we://src]
  - altText: string [we://altText]
  - width: number [we://width]
  - height: number [we://height]
  - version: number [we://version]

Involvement extends Ad4mModel:
  Fields:
  - agent: string (required) [we://involved_agent]
  - kind: string (required) [we://involvement_kind]
  - note: string [we://description]
  Relations:
  - node: HasOne [we://involved_in]

InvolvementType extends WeNode:
  Fields:
  - name: string (required) [we://name]
  - slug: string [we://slug]
  - description: string [we://description]
  - icon: string [we://icon]
  - color: string [we://color]
  - semantic: InvolvementSemantic = 'responsible' [we://semantic]
  - reflexive: boolean = false [we://reflexive]
  - appliesTo: string [we://applies_to]
  - retired: boolean = false [we://retired]
  - schemaVersion: number = 1 [we://schema_version]

LinkBlock extends WeNode:
  Fields:
  - url: string (required) [we://url]
  - title: string [we://title]
  - description: string [we://description]
  - thumbnail: string [we://thumbnail]
  - version: number [we://version]

LocationBlock extends WeNode:
  Fields:
  - name: string [we://name]
  - latitude: number [we://latitude]
  - longitude: number [we://longitude]
  - address: string [we://address]
  - city: string [we://city]
  - countryCode: string [we://country_code]
  - country: string [we://country]
  - version: number [we://version]

MutedAgent extends WeNode:
  Fields:
  - did: string [we://did]
  - description: string [we://description]

Placement extends Ad4mModel:
  Fields:
  - nodeType: string [we://node_type]
  - x: number [we://x]
  - y: number [we://y]
  - width: number [we://width]
  - height: number [we://height]
  - contentScale: number [we://content_scale]
  - rotation: number [we://rotation]
  - z: number [we://z]
  - color: string [we://color]
  - cardShape: string [we://card_shape]
  - rank: number [we://rank]
  Relations:
  - node: HasOne [we://placed_node]

ReadMarker extends WeNode:
  Fields:
  - nodeId: string [we://node_id]
  - spaceUuid: string [we://space_uuid]
  - lastReadAt: string [we://last_read_at]

Relationship extends WeNode:
  Fields:
  - connection: string [we://connection]
  - relationshipTypeId: string [we://relationship_type_id]
  - label: string [we://title]
  - description: string [we://description]
  - sourceType: string [we://source_type]
  - targetType: string [we://target_type]
  Relations:
  - source: HasOne [we://relationship_source]
  - target: HasOne [we://relationship_target]

RelationshipType extends WeNode:
  Fields:
  - name: string (required) [we://name]
  - slug: string [we://slug]
  - description: string [we://description]
  - icon: string [we://icon]
  - color: string [we://color]
  - inverseName: string [we://inverse_name]
  - directed: boolean = true [we://directed]
  - schemaVersion: number = 1 [we://schema_version]

Shape extends WeNode:
  Fields:
  - name: string (required) [we://name]
  - description: string [we://description]
  - icon: string [we://icon]
  - shapeId: string [we://shape_id]
  - version: number = 1 [we://version]
  - forkedFrom: string [we://forked_from]
  - definition: string = null [we://shape_definition]

Signal extends Ad4mModel:
  Fields:
  - signalTypeId: string [we://signal_type_id]
  - value: number [we://value]

SignalType extends WeNode:
  Fields:
  - name: string [we://name]
  - slug: string [we://slug]
  - description: string [we://description]
  - icon: string [we://icon]
  - iconSecondary: string [we://icon_secondary]
  - step: number = 1 [we://step]
  - rangeMin: number [we://range_min]
  - rangeMax: number = 1 [we://range_max]
  - mode: SignalMode = 'toggle' [we://mode]
  - aggregate: SignalAggregate = 'count' [we://aggregate]
  - semantic: SignalSemantic = 'custom' [we://semantic]
  - allowChange: boolean = true [we://allow_change]
  - retired: boolean = false [we://retired]
  - valueType: string = 'numeric' [we://signal_value_type]
  - schemaVersion: number = 1 [we://schema_version]

Space extends WeNode:
  Fields:
  - uuid: string [we://uuid]
  - url: string [we://url]
  - name: string (required) [we://name]
  - description: string (required) [we://description]
  - discovery: string = 'hidden' [we://discovery]
  - avatar: string [we://image]
  - coverImage: string [we://thumbnail]
  - defaultTemplateId: string [we://default_template_id]
  - defaultThemeId: string [we://default_theme_id]
  - enabledModules: string [we://enabled_modules]
  - enabledViews: string [we://enabled_views]
  - extractionTargets: string [we://extraction_targets]
  - autoInterpret: boolean = true [we://auto_interpret]
  - threadMode: string = 'fractal' [we://thread_mode]
  - moduleSettings: string [we://module_settings]
  Relations:
  - location: HasOne → LocationBlock [we://location]
  - board: HasOne → CollectionBlock [we://board]
  - taskStates: HasMany → TaskState [we://task_state_order]
  - typeStyles: HasMany → TypeStyle [we://type_style]

SpacePreference extends WeNode:
  Fields:
  - spaceUuid: string [we://space_uuid]
  - mutedModules: string [we://muted_modules]
  - moduleSettings: string [we://module_settings]
  - hiddenViews: string [we://hidden_views]
  - templateId: string [we://template_id]
  - themeId: string [we://theme_id]

SpaceTemplatePreference extends WeNode:
  Fields:
  - spaceUrl: string [we://space_url]
  - preference: string [we://preference]

TagBlock extends WeNode:
  Fields:
  - name: string (required) [we://name]
  - color: string [we://color]
  - version: number [we://version]

TaskBlock extends WeNode:
  Fields:
  - title: string (required) [we://title]
  - description: string [we://description]
  - status: string = 'todo' [we://status]
  - priority: string = 'medium' [we://priority]
  - dueDate: string [we://due_date]
  - assignee: string [we://assignee]
  - version: number [we://version]

TaskState extends WeNode:
  Fields:
  - name: string (required) [we://name]
  - slug: string [we://slug]
  - description: string [we://description]
  - icon: string [we://icon]
  - color: string [we://color]
  - semantic: TaskStateSemantic = 'open' [we://semantic]
  - retired: boolean = false [we://retired]
  - approvals: number = 1 [we://approvals]
  - approverKind: string [we://approver_kind]
  - schemaVersion: number = 1 [we://schema_version]

Template extends WeNode:
  Fields:
  - name: string [we://name]
  - description: string [we://description]
  - icon: string [we://icon]
  - origin: string [we://origin]
  - version: number = 1 [we://version]
  - slug: string [we://slug]
  - schema: string = null [we://template_schema]
  - themeId: string [we://theme_id]
  - role: string [we://template_role]
  Relations:
  - screenshots: HasMany → ImageBlock [we://screenshot]

TextBlock extends WeNode:
  Fields:
  - style: string = 'normal' [we://style]
  - listItem: string [we://list_item]
  - level: number [we://level]
  - checked: boolean = false [we://checked]
  - align: string [we://align]
  - direction: string [we://direction]
  - text: string [we://text]
  - marks: json [we://marks]
  - source: string [we://text_source]
  - version: number [we://version]

Topic extends WeNode:
  Fields:
  - name: string (required) [we://name]
  - description: string [we://description]
  - icon: string [we://icon]
  - color: string [we://color]

Theme extends WeNode:
  Fields:
  - name: string [we://name]
  - description: string [we://description]
  - icon: string [we://icon]
  - origin: string [we://origin]
  - slug: string [we://slug]
  - version: number = 1 [we://version]
  - css: string = null [we://stylesheet]
  - overrides: string = null [we://token_overrides]
  Relations:
  - screenshots: HasMany → ImageBlock [we://screenshot]

ExtractionAmendment extends Ad4mModel:
  Fields:
  - property: string [we://amended_property]
  - previousValue: string [we://previous_value]
  - newValue: string [we://new_value]
  - nodeType: string [we://node_type]
  Relations:
  - node: HasOne [we://amended_node]

ExtractionPass extends Ad4mModel:
  Fields:
  - outcome: string = 'done' [we://outcome]
  - recordCount: number [we://record_count]
  - targets: string [we://extraction_targets]
  - error: string [we://error]
  - trigger: string = 'manual' [we://trigger]
  - prompt: string [we://prompt]
  - response: string [we://response]

TypeStyle extends Ad4mModel:
  Fields:
  - nodeType: string [we://node_type]
  - color: string [we://color]

VideoBlock extends WeNode:
  Fields:
  - title: string [we://title]
  - url: string (required) [we://url]
  - duration: number [we://duration]
  - thumbnail: string [we://thumbnail]
  - provider: string [we://provider]
  - version: number [we://version]

WeNode extends Ad4mModel:
  Relations:
  - comments: HasMany [we://comment]
  - inReplyTo: HasOne [we://comment]
  - signals: HasMany → Signal [we://signal]
  - participants: HasMany [we://participants]
  - calls: HasMany [we://call]
  - mentions: HasMany [we://mention]

---

## Stores

Stores provide state (readable values) and actions (methods) for dynamic logic in schemas.
Read state in an expression ({ "$": "storeName.member" }) and call actions with $action.
For ephemeral/form state, use $localState with local.* reads and $setLocal writes instead of stores (see Dynamic Logic).

AccountStore:
- State:
  - canManageAccounts: boolean — the host can manage local accounts (false on web). Gate every account control on this
  - accounts: Account[] — local accounts (id, name, avatar, active, hasAgent, sharedWithLauncher). id is the data directory; hasAgent is false for one scaffolded but never set up
  - activeAccount: Account | undefined — the account this app instance is running against. Correct at first paint: the list is seeded from a synchronous cache
  - hasOtherAccounts: boolean — true when there is somewhere else to switch to
  - accountsLoaded: boolean — the host has answered. Without it an empty list reads as a first run and flashes a welcome at a returning user
  - isFirstRun: boolean — nothing has ever been set up on this machine: the host has answered and no account holds an identity yet
  - busy: boolean — a mutation is in flight; a successful one ends in a relaunch
  - switchingTo: Account | null — the account being switched to, from the click until the process goes away
  - creating: boolean — true from the moment a create is requested until the process goes away
  - error: string — the last account error, for display
  - pendingRemoval: Account | null — the account a removal was requested for, awaiting confirmation
- Actions:
  - refresh(): re-reads the account list from the host
  - createAccount(): creates an account under a provisional name and switches into it — the setup screen names it. Does not return on success
  - switchAccount(id: string): switches to another account. Does not return on success
  - removeAccount(id: string): deletes an account and its data. Refuses the active one
  - requestRemoval(id: string): opens the removal confirmation for that account
  - cancelRemoval(): closes the removal confirmation without deleting
  - confirmRemoval(): deletes the account awaiting confirmation
  - clearError(): clears the error slot

AppStore:
- State:
  - apps: RegisteredApp[] — list of registered external apps (id, name, image)
  - appsWithWe: RegisteredApp[] — the apps list with a WE entry prepended, for an app switcher that offers the way back to templates as one more row. Prepended here because a schema can map a list but cannot add to it
  - activeAppId: string | null — id of the currently active app, or null if none
- Actions:
  - activateApp(id: string): activates an app and switches to its view
  - deactivateApp(): deactivates the current app and returns to the template view

ClockStore:
- State:
  - clocks: Record<name, { at, atIso, atLabel, ticks, from, fromIso, to, toIso, progress, playing, speed, loop, canPlay }> — the app's clocks by name. A clock is the moment something shows and the playback that moves it: a globe given `clock: "events"` follows the clock of that name, and every control reading or driving "events" moves it too. `at` is milliseconds since 1970, or null until somebody plays or seeks, which shows everything; `from`/`to` are the range, which the globe works out from its layers' data; `atIso` is ready for a we-timestamp, and `atLabel` is the moment already written as precisely as the range calls for (with the time across a day, the month alone across decades); `ticks` are marks along the range, { at, fraction, label }, on round moments at the scale it calls for — hours, days, months or years — to place at `fraction` of a scrubber's width; `progress` is 0–1 through the range, for a we-slider (max 1, step 0.001). Published about five times a second while playing. A name nothing has used yet reads as undefined, so guard a control on it: { $: 'clockStore.clocks.events.canPlay' }
- Actions:
  - play(name: string): plays from the start, or from where it was paused; does nothing with no range to cross
  - pause(name: string): stops where it is
  - toggle(name: string): plays or pauses — what one button calls
  - seek(name: string, at: number | string | null): shows that moment, in milliseconds or an ISO date; null shows everything again
  - seekProgress(name: string, fraction: number): shows the moment that far through the range, 0 to 1 — what a we-slider's onChange passes as event.detail
  - setSpeed(name: string, speed: number): plays faster or slower — 2 is twice as fast. Default 1
  - setLoop(name: string, loop: boolean): starts again at the end rather than stopping
  - configure(name: string, settings: { from?, to?, speed?, duration?, rate?, loop? }): several at once. `duration` is how long the whole range takes to play at speed 1 — seconds or a span ("45s", "2m"), default 30s; `rate` instead runs at a fixed pace (1 is real time, for a countdown); from/to fix the range rather than taking it from the data

DatasetStore:
- State:
  - datasets: array of dataset handles (all joined datasets)
  - orderedDatasets: datasets sorted by user-defined sidebar order, system datasets excluded
  - currentDataset: dataset handle | null (the dataset currently being viewed)
  - currentDatasetUri: string | undefined — the shared URL of the current dataset with its scheme (neighbourhood://…), or undefined for a personal one. Prefer currentDatasetCid for comparisons; this is the form a share link carries
  - currentDatasetCid: string | undefined — the neighbourhood CID of the current dataset (prefix stripped)
  - currentDatasetEntities: EntityManifestEntry[] (non-WE SHACL models from the current dataset; injected as externalEntities into AI messages)
  - isWeSpace: boolean — true once the current dataset is confirmed to have WE's Space SDNA installed (false for a joined-but-foreign dataset, e.g. one synced in from Flux)
  - joinedSpaceCids: string[] — CIDs of every joined shared dataset
  - datasetsLoaded: boolean — the backend has answered with the dataset list. An empty list is otherwise indistinguishable from "not fetched yet", so anything asking "have I joined this?" reads the boot frame as "no". The same reason accountStore.accountsLoaded exists
  - systemDatasetUuids: string[] — uuids of the system datasets (we-root, we-personal, we-test)
  - rootDataset: dataset handle | null — the app's configuration (we-root): AgentSettings, templates, themes, per-space preferences. Chrome tier only
  - personalDataset: dataset handle | null — the agent's own things (we-personal): notes, the Pocket. Carries the ordinary space schema, so posts, blocks and files work there. Chrome tier only — a space's template cannot reach it. Null until its schema is installed
  - globalDataset: dataset handle | null — the seed-configured global discovery space, once joined
  - marketplaceDataset: dataset handle | null — the seed-configured marketplace, once joined
  - globalSpaceConfigured: boolean — the seed declares a global space
  - globalSpaceId: string | null — the dataset id of the seed-configured global discovery space, or null when it is not configured or not joined. Compare a route segment against it to tell "the user is in the global space" from "the user is in a space of their own"
  - marketplaceConfigured: boolean — the seed declares a marketplace
  - marketplaceId: string | null — the dataset id of the seed-configured marketplace, or null when it is not configured or not joined. The marketplace counterpart of globalSpaceId
  - marketplaceJoined: boolean — the marketplace dataset is joined locally
- Actions:
  - switchDataset(uuid: string): switches to a dataset by UUID, registers its SHACL models as dynamic model classes, and populates currentDatasetEntities
  - reorderDatasets(newOrder: string[]): reorders the sidebar items by UUID array
  - removeDataset(uuid: string): removes a dataset from the backend and from local state. The low-level half of spaceStore.removeSpace, which also clears the global-discovery listing — call that from a template, and this only for a dataset that is not a space
  - cleanupSpaceSdna(uuid?: string): one-time remediation for a space that accumulated duplicate SDNA installs — removes the redundant duplicate link copies. Defaults to the current dataset. Returns a display-ready summary string naming how many links were removed and the DIDs that authored them (your own DID annotated with "(you)"), or an empty string if nothing needed cleaning up

EditorStore:
- State:
  - messages: ChatMessage[] — the active AI session's messages (id, role: 'user' | 'assistant' | 'system', content, createdAt, status). Empty for a new chat
  - isOpen: boolean — the AI chat panel is open
  - isStreaming: boolean — an assistant reply is arriving; streamingContent holds what has arrived so far
  - streamingContent: string — the partial assistant reply while isStreaming, empty otherwise
  - assistantAvailable: boolean — the node has a language model the editor can hold a conversation with, so sendMessage can work. Configured in Settings → AI. Gate the composer on it and say what is missing rather than hiding it
  - assistantStatus: { state: 'ready' | 'loading' | 'error' | 'unchecked' | 'none', name, model, detail } | null — which model answers the chat and whether it can right now, checked without spending tokens when the panel opens and after a failed send. `unchecked` means the backend could not ask, not that it failed; `detail` says why for error and loading
  - templateName: string — the name of the template being edited, for the editor’s own header
  - templateIcon: string — its icon
  - isReadOnly: boolean — the template on screen cannot be saved in place (a built-in, or somebody else's). Edits buffer as pending changes; offer Fork rather than Save. Answers for the template rendered, so do not use it to gate per-row controls in a list — switcherGroups carries `editable` per row
  - hasPendingChanges: boolean — buffered edits exist against a read-only template, waiting for a fork to land in
  - pickerOpen: boolean — the fork/fresh naming dialog is showing
  - pickerAction: 'fork' | 'fresh' — which the open picker is for
  - pickerDefaultName: string — what the picker’s name field starts with
  - pickerDefaultIcon: string — what its icon field starts with
  - pickerShowDestination: boolean — the picker offers a personal-or-space destination, which it can only do while a space is open to save into
  - sessions: ChatSession[] — this template's saved AI sessions (id, name, templateId), newest first
  - activeSessionId: string | null — the session whose messages are shown
  - contentMode: 'preview' | 'visual' — whether the editor shows the rendered template or the visual editing surface
  - schemaJson: string — the template being edited, serialised with its node ids — what the code panel shows and edits. Ids are permanent, so a save keeps them
  - canUndo: boolean (true when there are schema edits that can be undone)
  - canRedo: boolean (true when there are undone schema edits that can be redone)
  - isEditingTemplate: boolean — a template editing session is open
  - editAction: 'edit' | 'fork' | 'fresh' | null — how the current template session began, null outside one
  - codePanelOpen: boolean — the code panel is open
  - themePanelOpen: boolean — the theme panel is open
  - visualPanelOpen: boolean — the visual properties panel is open
  - isEditingTheme: boolean — a theme editing session is open, independently of template editing
  - aiDockEdge: DockEdge — where the AI panel opens ('left' | 'right' | 'top' | 'bottom'), or null while it is closed. An opening bid: the shell remembers wherever the user drags it
  - codeDockEdge: DockEdge — the same, for the code panel
  - themeDockEdge: DockEdge — the same, for the theme panel
  - visualDockEdge: DockEdge — the same, for the visual panel
  - editorDockSize: DockSize — the opening size every editor panel shares ('sm' | 'md' | 'lg' | 'full')
  - editorDockFloat: boolean — editor panels open floating over the content rather than pushing it aside
- Actions:
  - refreshAssistant(): checks the chat’s model again — after changing models in settings, or to see whether a failure has cleared
  - newChat(): starts a new AI session for this template and switches to it
  - switchSession(sessionId: string): shows another saved session
  - deleteSession(sessionId: string): deletes a saved session and its messages
  - setContentMode(mode: 'preview' | 'visual'): switches the editor between the rendered preview and the visual editing surface
  - undo(): undoes the last schema edit
  - redo(): redoes the last undone schema edit
  - startFork(): opens the picker to copy the current template into one you own
  - startFresh(): opens the picker to start an empty template
  - confirmPicker(name: string, icon: string, destination: 'personal' | 'space'): creates the fork or fresh template and enters editing on it
  - cancelPicker(): closes the picker without creating anything
  - enterTemplateEditing(action?: 'edit' | 'fork' | 'fresh'): opens a template editing session on the template on screen. Omit action to edit in place; a read-only template buffers its edits
  - exitTemplateEditing(): ends the template session. Buffered changes to a read-only template are dropped
  - toggle(): toggles the AI chat panel open/closed
  - open(): opens the AI chat panel
  - close(): closes it
  - toggleCodePanel(): opens or closes the code panel
  - openCodePanel(): opens the code panel
  - closeCodePanel(): closes it
  - toggleThemePanel(): opens or closes the theme panel
  - openThemePanel(): opens the theme panel. Pair with themeStore.focusRole to land on a role
  - closeThemePanel(): closes it
  - toggleVisualPanel(): opens or closes the visual properties panel
  - enterThemeEditing(): opens a theme editing session on the current theme, and the theme panel with it
  - exitThemeEditing(): ends the theme session, discarding an unsaved draft
  - toggleThemeEditing(): enters or exits theme editing — what a single button in chrome should call
  - sendMessage(text: string): sends a message to the assistant. Patches it proposes are applied to the template and land in undo history; the reply streams into streamingContent
  - clearHistory(): deletes the active session's messages

InterpretationStore:
- State:
  - activity: InterpretationActivityView[] — every extraction pass this agent knows about, its own and its peers’, running first then most recent. Each row carries display-ready strings: `label` is a whole clause ("Anna is waiting on the model", "Extracted 3 records"), `elapsed` is `m:ss` while running and empty once settled, `name`/`avatar`/`runner` identify who is running it, and `mine` says whether it is this agent’s. Only a row with `mine` carries `prompt`/`response` — a peer’s exchange is never sent live; read it from the call’s `ExtractionPass` records once the pass settles — so gate a details affordance on `hasDetail`
  - runningCount: number — how many passes are still in flight. What a collapsed "N extractions running" summary counts
  - hasActivity: boolean — whether there is anything to show at all. Counts settled rows too, so a bar gated on it does not vanish the instant a pass finishes and take its result with it
  - runningPasses: InterpretationActivityView[] — the passes still in flight, for a readout that lists them
  - settledPasses: InterpretationActivityView[] — the passes that have finished, newest first
  - settledCount: number — how many have finished. What a collapsed "N extractions processed" line counts
  - capable: boolean — whether this node can interpret AT ALL, as distinct from being able to and having no model configured. Answered by asking the backend rather than by testing the client library, so it is false against a node whose executor predates the extraction stack. False means no fix exists from inside the app — say so rather than offering a control that cannot work
- Actions:
  - dismissSettled(): forgets every finished row, leaving anything still running. A running pass is not this agent’s to dismiss

PresenceStore:
- State:
  - peers: PresentAgent[] — every peer known in the current space, offline included, each joined to its cached profile (did, name, avatar, tone, focus, activities, availability). Sorted by liveness
  - online: PresentAgent[] — peers in the current space who are not offline — the "who is here" list
  - onlineHere: PresentAgent[] — peers at this agent's exact route path, for a per-page presence strip
  - calls: Map<callId, PresentAgent[]> — the calls running in this space right now and who is in each
  - available: boolean — a presence transport exists. False in a personal space, where there is nobody to be present to; gate presence UI on it rather than rendering an empty roster
  - focusDepth: FocusDepth — how much of this agent's location peers are shown: the space only, the section, or the exact path
- Actions:
  - setFocusDepth(depth: FocusDepth): sets how much of your location peers see
  - setAvailability(availability: 'available' | 'busy' | 'away' | 'invisible'): sets the status published with your presence. 'invisible' stops publishing entirely rather than asking peers not to look
  - setActivity(activity: Activity): adds or replaces a published activity — a call, an edit, a work claim — keyed by its type and id
  - clearActivity(type: string, id?: string): withdraws a published activity; omit id to withdraw every one of that type

ProfileStore:
- State:
  - profiles: AgentProfileSummary[] — cache of all fetched profiles (did, firstName, lastName, handle, bio, avatar, coverImage, location)
  - ownProfile: AgentProfileSummary | undefined — reactive accessor for the current user's own profile (derived from the cache). Note `name` is assembled for display and falls back to "Anonymous", so it is never empty — test firstName/lastName/handle to ask whether somebody has a name
  - ownProfileLoaded: boolean — the own-profile fetch has answered. An empty profile is otherwise indistinguishable from an unfetched one, so anything asking "has this person set a name?" reads every boot frame as "no". Same reason as datasetStore.datasetsLoaded
  - needsName: boolean — this agent has no name of any kind and has not waved the question away this session, as a settled fact (false until the app is ready and the profile fetch has answered). What the name prompt mounts on; also the right gate for any "finish setting up" nudge of your own
  - pendingAvatar: File | null — a picture chosen before the agent exists, held until completeAccountSetup uploads it. Read it to preview the choice on the setup screen; null once uploaded or when nothing was picked
- Actions:
  - setPendingAvatar(file: File): holds a picture chosen before an agent exists; uploaded by completeAccountSetup
  - saveNameFromPrompt(name: string): sets the name and stops asking. Dismisses before publishing, so a failed write cannot re-raise the prompt on top of the toast explaining it — which is why this exists rather than calling updateOwnProfile from the schema
  - dismissNamePrompt(): stops asking for a name until the next launch. Not persisted: a nameless agent degrades every other member's experience, so the only permanent exit is setting a name
  - completeAccountSetup(name: string): the whole of first-run setup — creates the agent with the password typed into the host's CredentialField (purpose 'new'), then publishes the name and picture, then lets the app appear. Does nothing but ask the field to show its errors when that password is missing or its confirmation differs
  - fetchProfile(did: string): fetches and caches an agent's profile from their public dataset
  - updateOwnProfile(fields: { firstName?, lastName?, handle?, bio? }): updates own profile text fields and publishes to the public dataset
  - updateProfileImage(field: "avatar" | "coverImage", imageFile: File): uploads the image and publishes its expression URL to the public dataset
  - clearProfileImage(field: "avatar" | "coverImage"): removes that image from the published profile
  - updateOwnLocation(update: { latitude?, longitude?, city?, country?, countryCode? }): merges the location update into the cache and publishes to the public dataset

RecordStore:
- State:
  - creatableEntities: { label, value, icon, group, description, via }[] — the content a person can create here, each with the one-line `description` from its manifest (or the shape's), ready for a we-select: this space's own models first, then WE's built-in blocks. A built-in entity is here when it is a block there is a way to make — `authoring` fields (via 'form') or `composed` (via 'composer': a CollectionBlock, which is a note or a post, written in BlockComposer). Not blocks — spaces, templates, vocabulary entries, drawn Relationships — are never here. Filter by `via` for what a surface can host: a record form's type selector lists `recordStore.creatableEntities.filter(k, k.via == 'form')`; a canvas's 'add' chooser lists them all and opens the composer for 'composer'
  - recordDraft: the open form's draft ({ entity, label, icon, fields[] }) or null while closed — its non-nullness is what mounts the modal. Each field is { name, label, control, required, options, placeholder, value, accept, target, targetLabel, many, canCreate, canPick, entries }, derived from the model's own declaration, so a form exists for a model nobody wrote a form for. control 'file' is a we-file-upload (accept names the types); control 'relation' points at another record: entries are the chips ({ key, label }), canCreate offers openRelationForm, canPick offers a picker over existing target records, and inline ('location' | 'image' | '') names the in-place control a target is made with instead — see setRelationLocation and addRelationImage; an image entry carries preview, a data URI
  - recordDraftDirty: boolean — the open form holds something worth keeping. What a discard guard reads: the fields come from the model, so a shape this community defined has properties no schema was written against and there is no set of local names an expression could test. Pass it to discardGuard's `dirty`
  - displays: Record<entity, RecordDisplay> — how to show an instance of each creatable model, every core block (a divider or a quote card included) and Relationship, keyed by entity name and derived from its declaration: { entity, label, icon, title, summary, media, mediaRelation, fields[] }, where title/summary/media name the properties playing those roles ('' when none does) and mediaRelation names a relation to an ImageBlock that pictures the record when no property does — look the image up by the ids it holds ({ entity: 'ImageBlock', where: { id: row[display.mediaRelation] } }) rather than drawing them and each field is { name, label, kind, role, options, vocabulary }. kind is one of text, longText, number, boolean, date, datetime, color, url, image, file, json, relation (with target, the model it points at); role is title, summary, media or detail. `options` is the values a field is allowed to hold where the model closes the set (a task's status), empty otherwise — count() it to tell a state worth drawing as a we-badge from free text, and map it into a we-select rather than offering a text box that accepts a word the model does not know. `vocabulary` names the community list a value is a slug of ('taskState' for a task's status, looked up in spaceStore.taskStates for its name and colour), empty otherwise. Index it by a row's type — { $: 'recordStore.displays[row.type]' } — and render the fields with $each; see "A record of any type" in the patterns
  - recordErrors: string[] — validation errors from the last save attempt, plus any backend failure
  - savingRecord: boolean — a create is in flight
  - lastCreatedId: string — the id of the last record created, empty before the first. Read it to act on what was just made; kept in the store because an $action's onSuccess can read a store and cannot hold a value
  - pendingLink: the two records a pending connection joins ({ sourceId, sourceType, sourceLabel, targetId, targetType, targetLabel }), or null when the open form is an ordinary one. Read it to name what is being connected
  - relationDraft: the record being made inline for a relation field — an image for a sighting — as a draft of the same shape, or null. Its non-nullness mounts the nested form over the outer one. It is not written until the outer form saves
  - relationErrors: string[] — why the nested form's last Add was refused
  - relationshipKind: string — which named RelationshipType the pending connection is, or empty for one carrying only a label. Held beside the draft because the kinds are a list to pick from, which a generated form cannot render
  - canvasHistory: { canUndo, canRedo, undoLabel, redoLabel } — whether the canvas on screen has anything to undo or redo, and what each press would put back. Gate a control on canUndo rather than hiding it: a disabled key with a tooltip naming the act says more than an absence does
- Actions:
  - openRecordForm(entity?): opens the create form — on that model, or on the first offered one. Clears any pending connection
  - connectNodes(link): opens the form on a Relationship joining two records. Takes the graph's onEdgeCreate payload as it arrives
  - connectNodesNow(link): writes the Relationship straight away, with no label and no kind, and answers with its id. The same onEdgeCreate payload; the choice between this and connectNodes is the template's. Ask first where the claim is the point (a knowledge map); write first where the arrangement is (a canvas beside a live call), and let the words be added in an inspector afterwards. Pair it with an onSuccess that selects the new line — a connection nobody is shown is a connection nobody knows is a record
  - setRecordEntity(entity): switches which model is being created, discarding what was typed
  - setRecordField(name, value): sets one field. Takes the field name, so one action serves every control — which is the only shape that works when the fields come from data. A file control passes its File as event.detail
  - setRecordPlace(detail): pins the open draft's place — pass a we-location-picker's arg.detail. Writes latitude, longitude and address where the draft has them, and a name where none was typed. recordFormModal draws the picker for any model with both a latitude and a longitude field, in place of the two number boxes
  - openRelationForm(field): opens the nested form on a relation field’s target model
  - setRelationField(name, value): sets one field of the nested form, as setRecordField does for the outer one
  - saveRelationForm(): adds what the nested form holds to its relation field as a chip, and closes it. Nothing is written until the outer form saves
  - cancelRelationForm(): closes the nested form, discarding it
  - pickRelation(field, id): points a relation field at an existing record — pass a picker’s event.detail
  - removeRelationEntry(field, key): takes one chip off a relation field
  - setRelationLocation(field, detail): points a location relation at the place a we-location-picker reports — pass its arg.detail. The place is made on save and names itself after the city unless a name was typed
  - setRelationEntryField(field, key, name, value): edits one field of a relation entry still to be made — the name or address under a picked place
  - addRelationImage(field, file): adds a chosen, cropped image to an image relation — pass an EditableImage's onImageChange event. Its entry carries a preview
  - setRelationshipKind(id): sets which named kind the pending connection is; an empty value clears it
  - cancelRecordForm(): closes the form, discarding it
  - saveRecord(): validates and creates. Errors land in recordErrors and the form stays open holding what was typed; success closes it and sets lastCreatedId
  - placeOnCanvas(canvas: string, nodeId: string, nodeType: string, x: number, y: number): puts a record at a position on a canvas, or moves one already there. An upsert, so dragging twice leaves one coordinate. Prefer dragOnCanvas for the graph’s onNodeDragEnd, which also carries what a folded card is holding
  - dragOnCanvas(canvas: string, payload): writes where a drag left a card, and where everything a FOLDED card carried with it now sits. Takes the graph's onNodeDragEnd payload as it arrives. This rather than placeOnCanvas wherever the canvas can fold: the carried cards are a list, $action calls a method once, and a schema cannot loop — so without it, carrying a fold into a corner and unfolding it scatters its contents back where they were
  - dropOnCanvas(canvas: string, payload): puts something dragged in from elsewhere onto a canvas where it landed. Takes the graph's onDrop payload as it arrives. A record from this space is placed as it is; something from another dataset is brought in first (the bringIn rule) and placed — a whole post or note as a post, a single block as itself (a copy of the block, or a lone EmbedBlock quoting somebody else's), owned by the canvas. Refuses, with a toast, anything that is not a record — an agent, a space
  - bringIn(payload): takes a `we-drop-zone`'s dropped detail ({ items }) into the space on screen as posts — `onDropped: { $action: 'recordStore.bringIn', args: [{ $: 'event.detail' }] }`. Your own note or post becomes a copy (a post from another shared space records sourceRef/sourceName, shown as 'Also posted in …'); anybody else's post or block becomes a new post quoting it through an EmbedBlock carrying sourceAuthor and sourceName. Things already in this space are ignored. Each new post shows a toast with Undo
  - updateRecordField(entity: string, id: string, field: string, value): changes one property of one record — the inspector's edit mode. Takes the field name so one action serves every control; the value is coerced by the field's declared kind and a control's { detail } is unwrapped. An empty string is not written, so a text field cannot be cleared this way
  - rekeyConnection(id: string): rewrites a Relationship's dedup key (`connection`) from its label and both ends' titles, which is how an extraction pass reads the structure people drew. updateRecordField does it already; call this after saving a Relationship's label through record.update
  - removeFromCanvas(canvas: string, node: string | string[]): takes a record — or a whole selection — off a canvas, leaving the records themselves alone. A card the canvas owns survives as an unplaced one in the tray. Takes one id or a list, so a selection is not a special case: pass the graph's onDeleteSelection or onSelectionAction records as event.records.map(r, r.recordId). UNDOABLE, which is why this rather than deleteRecords is what a canvas should bind its Delete key to
  - deleteRecords(records): deletes several records for everyone in the space, asking ONCE. Takes the graph's onDeleteSelection or onSelectionAction `records` as they arrive — [{ recordId, recordType }]. The host raises its own confirmation and counts the list, which is why this exists: a template looping record.delete stacks one dialog per card. Irreversible and outside the undo history — a delete drops the record's links and a re-create earns a new id, so anything pointing at the old record breaks
  - undoCanvas(canvas: string): puts back the last thing this agent did to the arrangement of THAT canvas — a move, a resize, a colour, a card taken off, a card moved in a tree. Replayed as a NEW write rather than as a rollback, so a peer’s changes in between are not discarded and a card somebody else has moved since is skipped rather than dragged back out from under them. Pass the same canvas id the GraphView’s canvas seed reads; the stack scopes itself to it, so pressing undo after opening another canvas replays nothing. Gate a control on recordStore.canvasHistory.canUndo
  - redoCanvas(canvas: string): does again what undoCanvas put back, on the same terms and with the same argument
  - resizeOnCanvas(canvas: string, payload): resizes a card on a canvas. Takes the graph's onNodeResize payload as it arrives; the size lives on the placement, so the same post on another canvas is unaffected
  - anchorOnCanvas(canvas: string, payload): pins which SIDE of a card a connection leaves or arrives on, for this canvas. Takes the graph's onEdgeAnchor payload as it arrives; an empty side clears that end, and a route with neither end pinned and no bends is deleted. Bends survive a clear — one record holds both, and letting go of a side says nothing about the shape somebody drew. Per canvas, like a placement — the same connection on somebody else's canvas is unaffected
  - rerouteOnCanvas(canvas: string, payload): writes the shape of one connection's route on this canvas — the points it is bent through. Takes the graph's onEdgeReroute payload as it arrives; the whole list, in the edge's own frame, so a bend keeps its proportions when either card moves. An empty list straightens it, and a route with no points and no anchors is deleted
  - retargetOnCanvas(canvas: string, payload): moves one end of a connection onto a different record. Takes the graph's onEdgeRetarget payload as it arrives. Unlike anchorOnCanvas and rerouteOnCanvas this changes the CLAIM rather than how one canvas draws it — the relationship now says something different everywhere it is shown. That end's anchor is cleared; its waypoints stay
  - arrangeOnTree(canvas: string, relationshipTypeId: string, payload): moves a card to another place in a tree. Takes the graph's onNodeArrange payload as it arrives, plus which kind of connection the tree follows — EMPTY meaning every kind, which mirrors what the layout does with the same answer and is the state a canvas starts in; a parent it has to create is then a connection with no kind, exactly as the canvas's own connect gesture writes one — the community's own vocabulary and the reader's chosen spine, neither of which the store can know. The counterpart of dragOnCanvas for a canvas read as a hierarchy: there a drag writes a coordinate, here it writes the structure the layout reads. A drop that makes a card a child writes the connection; one BESIDE a card reorders it there, writing ranks on the placements in the order the drop reports; one in the unconnected area takes it out of its tree. Undoable through undoCanvas, the connection and the ranks as one act. Three refusals, each with a toast: a card inside itself, a drop beside a tree's own root (which would detach it as a side effect — the unconnected area is where that is explicit), and taking out a connection people have commented on or reacted to, since that deletes the record and everything said about it — pass arrange-nodes the same rule as `keep` so the preview refuses first
  - setCardStyle(canvas: string, node: string | string[], field: string, value): sets one presentation property of one card — or of a whole selection — on one canvas: 'color', 'cardShape', 'contentScale', 'rotation' (degrees clockwise) and 'z' (stacking order). Takes the field name so one action serves a swatch, a picker and a slider, and one id or a list so a selection is not a special case. 0 is unset for the numbers, so a card is un-rotated by writing 0. Undoable, each card keeping its own baseline — putting back a colour applied to nine cards restores nine different colours
  - previewCardStyle(nodeId: string, field: string, value): shows a presentation change without writing it — for a slider that reports while it moves. Pair with setCardStyle on release; both go through the same pending map so the card never jumps
  - setTypeColor(canvas: string, nodeType: string, color): sets the colour every card of one type is drawn in, on one canvas — the canvas's key, made writable. An empty colour clears it
  - setSpaceTypeColor(spaceId: string, nodeType: string, color): sets the colour every card of one type is drawn in across the whole space — the community's key, which a canvas falls back to where it has no colour of its own for that type. Pass spaceStore.currentSpace.id. Read the result back with a TypeStyle query scoped { anchor: 'Space', via: 'typeStyles', anchorId: spaceStore.currentSpace.id }. An empty colour clears it
  - createOnCanvas(canvas: string, x?: number, y?: number): opens the create form and places whatever it makes onto that canvas, at the point given. Pair with the graph’s onCanvasDoubleClick
  - createCardOnCanvas(editorState, { canvas, at? }): composes a card onto a canvas and records where it sits, as one write. Without `at` the card lands in the canvas's tray. The composer's counterpart to createOnCanvas

RouteStore:
- State:
  - currentPath: string (the current route path)
  - segments: string[] (currentPath split by "/", e.g. ["/foo/bar"] → ["foo", "bar"])
  - templateSegments: string[] — the segments BELOW the space prefix, which is a template's own coordinate space. A template mounted at /space/<id> reading its own route params wants this: at /space/abc/photo/xyz it is ["photo", "xyz"], so a `/photo/:postId` route reads templateSegments[1] and keeps reading it wherever the host mounts the template. Reading `segments` by index pins a template to the host's prefix and breaks when it moves.
  - params: Record<string, string> — the URL's query parameters, reactive; read one as { $: 'routeStore.params.<name>' }. Prefer $localState with syncParam for fields a view owns; read params directly only for parameters something else writes
- Actions:
  - navigate(to: string, options?): navigates to a route (a bare path restores that route's remembered query string)
  - setParam(name: string, value: string | null, options?: { push?: boolean }): writes one query parameter (null removes); replaceState by default, push: true for changes that deserve a Back entry. Prefer $localState syncParam over calling this directly
  - back(): goes back one entry, the browser's own way. Use it on a page reached from several places — a record page is opened from a list, from a search and from a link somebody sent, and only one of those has a parent worth guessing. Does nothing at the start of the session's history

RuntimeStore:
- State:
  - canAdminister: boolean — this backend exposes runtime administration at all
  - canManageTrust: boolean — gate the trusted-agents section on this
  - canManageNetwork: boolean — gate the peer-network section on this
  - canRestartNetwork: boolean — the backend can restart its networking layer, and the restart does something. Gate a restart control on this, not on canManageNetwork
  - canManageApps: boolean — gate the authorized-apps section on this
  - canManageLanguages: boolean — gate the languages section on this
  - canManageAi: boolean — gate the AI section on this
  - canConfigureAi: boolean — the models can be changed, not just listed. False for a guest on somebody else's node, which grants reading the models but refuses changing them. Gate add/edit/remove/set-default controls on this and the section itself on canManageAi
  - canConfigureExecutor: boolean — this host starts the backend, so how it starts it can be changed. False on web
  - unsupportedCapabilities: { name, firstSeen }[] — capabilities this backend was asked for and does not have, `name` being the backend's own word for each (its RPC method name), so it can be searched for in that backend's source. What a node running an older build looks like from inside the app: the adapter degrades rather than failing, so the symptom is a part of the app quietly doing less, and this is the only thing connecting that to the node. EMPTY MEANS NOTHING HAS BEEN REFUSED YET, not that the backend is current — nothing is recorded until something asks — so say as much rather than rendering silence as health
  - aiModels: AiModelView[] — installed models, each carrying its display strings (kindLabel, sourceLabel, detail, statusText, ready) alongside id/name/kind/source/isDefault. Empty until loadAiModels() runs
  - aiTasks: AiTask[] — named prompts apps registered against a model (id, name, modelId, systemPrompt)
  - aiForm: AiModelForm | null — the model form while it is open, null when closed. One flat field per input; read with runtimeStore.aiForm.<field>
  - aiPresetOptions: { label, value }[] — model names the backend can fetch itself, for the open form kind
  - aiFormComplete: boolean — the open form has every field its chosen source needs
  - aiMaxContextError: string — why the open form's context limit (aiForm.apiMaxContext) cannot be saved, or empty. Bind it to that field's error: a limit that does not parse holds Save disabled, and nothing else says which field is doing it
  - aiServiceOptions: { label, value }[] — the remote services a model can be reached through (Anthropic, OpenAI, OpenRouter…) plus 'Custom endpoint', for a we-select bound to aiForm.apiService. Pass the value to setAiService. Show the protocol and base URL fields only while aiForm.apiService == 'custom'
  - canDiscoverAiModels: boolean — the backend can ask a remote endpoint which models it serves. Gate a "List models" control on it; where it is false, the model id is typed
  - aiDiscoveredModelOptions: { label, value }[] — the models the open form's endpoint said it serves, for a we-select. Empty until discoverAiModels() answers, and empty again once the protocol, URL or key changes
  - aiFormDirty: boolean — the open form has been edited since it opened. What a discard guard reads; compared against a snapshot taken on open, so looking at a model's settings and closing again asks nothing
  - languages: InstalledLanguage[] — language plugins installed in this backend (address, name, system). Empty until loadLanguages() runs
  - trustedAgents: string[] — trusted peer ids. Empty until loadTrustedAgents() runs
  - authorizedApps: AuthorizedApp[] — external apps holding credentials (id, name, description, url, iconUrl, capabilities, revoked). Empty until loadAuthorizedApps() runs
  - networkMetrics: string — backend diagnostic blob, already formatted for reading (indented JSON, hashes decoded). Show it in a read-only CodeEditor with language json. Empty until requested, and emptied again while a fetch runs
  - peerInfos: string[] — the peer-discovery records this node holds, exactly as the backend gave them: what copyPeerInfos copies. Opaque — don't display them, show peerInfosReadable
  - peerInfosReadable: string — the same records decoded for reading, as indented JSON (agent, space, dates, url, signature). Show it in a read-only CodeEditor with language json. Empty until loadPeerInfos() runs
  - pending: string[] — names of the actions with a runtime call in flight. A control's spinner reads its own: { $: "'loadPeerInfos' in runtimeStore.pending" }
  - loading: boolean — true while any runtime call is in flight. Prefer pending, so a spinner does not light for an unrelated call
  - error: string — the last runtime error, for display
  - canBackUp: boolean — a database export/import can be offered: the backend writes the file and the host can name one. False on web
  - logLevels: { crate, level }[] — per-crate log levels the user has set, sorted. Empty means the backend own defaults are in use
  - backupStatus: string — what the last export or import did, for display. Empty until one runs
  - mcpEnabled: boolean — whether the backend serves MCP on its next start
  - mcpPort: number — the port MCP is served on
  - executorRestartPending: boolean — settings were changed that the running backend has not picked up
  - pendingConsent: ConsentRequest | null — a request awaiting the user's decision (kind: 'capability' | 'trust', title, message, app, peerId)
  - consentSecret: string — a code an approval returned, to be relayed to the asking app
- Actions:
  - loadAiModels(): fetches the installed AI models and their load status
  - loadAiTasks(): fetches the prompts apps registered against a model
  - newAiModel(): opens the model form empty, for a new model
  - editAiModel(id: string): opens the model form on an existing model
  - setAiFormField(field: string, value: string | boolean): sets one field of the open model form. Takes the field name so one action serves every input
  - setAiService(id: string): chooses the open form's service. A named one sets the protocol and base URL; 'custom' keeps what the form holds for editing
  - discoverAiModels(): asks the open form's endpoint which models it serves, through the node — also the check that the key works. A refusal lands in error; an empty model field takes the first model
  - closeAiForm(): closes the model form, discarding it
  - saveAiModel(): saves the open form — adds or updates depending on whether it has an id
  - removeAiModel(id: string): deletes a model
  - setDefaultAiModel(id: string): makes this the model apps get when they ask for its kind
  - removeAiTask(id: string): deletes a registered prompt
  - loadLanguages(): fetches the installed languages
  - installLanguage(address: string): installs a language by content address, then reloads the list
  - removeLanguage(address: string): removes an installed language. Refuses the backend own system languages
  - loadTrustedAgents(): fetches the trusted-agent list
  - trustAgent(id: string): trusts a peer, then reloads the list
  - untrustAgent(id: string): untrusts a peer, then reloads the list
  - loadAuthorizedApps(): fetches apps holding credentials against this agent
  - revokeApp(id: string): invalidates an app's tokens, keeping the grant listed
  - removeApp(id: string): forgets the grant entirely
  - loadNetworkMetrics(): fetches the diagnostic blob
  - copyNetworkMetrics(): copies the loaded metrics to the clipboard, with a toast either way. Takes no text: a copy action names what it copies
  - restartNetwork(): restarts the peer-networking layer
  - loadPeerInfos(): fetches the peer-discovery records this node holds — its own and every peer it knows. Can take tens of seconds on a busy node; show a state on 'loadPeerInfos' in pending
  - copyPeerInfos(): copies the loaded peer records as a JSON array addPeerInfos accepts, with a toast either way
  - addPeerInfos(text: string): adds pasted peer records (JSON array or one per line). Resolves true when added — clear the paste box on result in onSuccess, since onSuccess also fires after a failure
  - setMcpEnabled(enabled: boolean): turns MCP on or off for the backend next start
  - setLogLevel(crate: string, level: string): sets one crate log level — adds it when not already set, so there is no separate add. Levels: error, warn, info, debug, trace
  - removeLogLevel(crate: string): drops an override, returning that crate to the backend default
  - exportDatabase(): asks for a file, then has the backend write everything to it
  - importDatabase(): asks for a file, then has the backend read it back in
  - setMcpPort(port: number): sets the MCP port. The host refuses one outside 1024-65535
  - restartExecutor(): starts the backend over so written settings take effect. Does not return
  - approveConsent(): grants the pending request
  - denyConsent(): declines the pending request
  - dismissConsentSecret(): clears the confirmation code display

SessionStore:
- State:
  - bootState: string — 'initialising' | 'login' | 'createAgent' | 'finishing' | 'ready' | 'error'
  - bootError: string — why the boot failed, when bootState is 'error'. Empty otherwise
  - passwordError: boolean — true after an unlock the backend refused. Not set when it merely timed out; see loginError
  - loginError: string — why the last sign-in failed when the password was not the problem (the backend took too long to finish), ready to display. Empty otherwise, and never set together with passwordError. Show it where passwordError’s message goes: { $: "sessionStore.passwordError ? 'Incorrect password' : sessionStore.loginError" }
  - loginLoading: boolean
  - createAgentError: string — the backend message from a failed agent creation, or empty
  - createAgentLoading: boolean
  - me: Agent | undefined — the authenticated identity; prefer the $me token in schemas
  - host: BackendHostInfo | undefined — the node this session runs against when it is somebody's hosting rather than this machine (id, name, description, imageUrl, location, url, computeSpecs, aiModels, rates). Undefined on desktop and on a local executor, so its presence is also the answer to "am I a guest here?" — gate any "connected to" UI on it. `aiModels` comes from the host directory and needs no capability, so it answers "can this node transcribe?" even where the executor refuses to list its models
  - hostAccount: BackendAccountInfo | undefined — this agent's account with that node (email, remainingCredits, walletAddress, freeAccess). Check freeAccess before showing a balance: on a free node the credit figure means nothing and "0" reads as an account that has run dry
  - isGuest: boolean — this identity was minted for somebody who arrived on a guest invite link rather than chosen by them. NOT the same question as `host`: an ordinary member of a hosted deployment has a host and is not a guest. Read it where the app explains itself to the person using it — why it is asking for a name, what "log out" would mean for an identity with no other way back
  - isDevelopment: boolean — whether this is a development build. A fact about the build. Do NOT gate developer-only UI on it; gate on devTools, which is the same answer plus a switch
  - devTools: boolean — whether developer affordances should be VISIBLE. True in a development build unless a developer has thrown the Settings → Developer switch to see what a shipped app looks like. Reactive, so a control gated on it appears and disappears on the press. Gate any developer-only control on this — a schema-test page, a fixture toggle — and wrap it in $if rather than hiding it, since a hidden row is still in the accessibility tree and still found by find-in-page. Never true in a production build, whatever the switch says
  - credentialEntered: boolean — something has been typed into the host's password field. The password itself is never readable from a template — see CredentialField — so gate a Sign in button on this
  - credentialConfirmed: boolean — a CredentialField with purpose 'new' holds a password typed twice and the same both times. Gate the call to profileStore.completeAccountSetup on it
- Actions:
  - setDevTools(on: boolean): shows or hides developer affordances for this session. Takes the value the control shows, so a we-switch can pass `event.detail` bare. Cannot turn developer UI on in a production build
  - unlock(): signs in with what was typed into the host's password field (a CredentialField with purpose 'unlock'), and loads user data. Takes no password, on purpose: nothing a template collected can be handed to it. Rejects when the unlock fails
  - touchCredential(): asks a CredentialField with purpose 'new' to show what is wrong with it — the $touch: '$all' for fields a template cannot reach. Put it beside $touch in a Create account button's handler
  - clearPasswordError(): clears the failed-unlock flag. Wire it to the CredentialField's onEdit — the verdict was on the submitted password, so editing that password retracts it and a stale "Incorrect password" should not sit over the correction
  - finishSetup(): leaves 'finishing' for the running app — sets bootState to 'ready'
  - logout(): locks the agent and returns to the login screen
  - retryBoot(): starts the whole boot again from the failure screen, by reloading. A failed boot can have got anywhere before it threw, so retrying in place would race the remains of the first attempt

ShapeStore:
- State:
  - spaceShapes: SpaceShapeView[] — the content models THIS SPACE defines (id, name, description, icon, shapeId, version, forkedFrom, propertyCount, problems). A shape with a non-empty problems array failed validation or adoption and its entity is not queryable; render the problems rather than hiding the row
  - shapesLoaded: boolean — the space has been asked for its shapes. An empty list is otherwise indistinguishable from "not fetched yet"; gate empty states on it
  - shapeDraft: the model wizard's draft (name, description, icon, classHint, identityMember, members[]) or null while the wizard is closed — its non-nullness is what mounts the wizard modal. Each member is { rowId, kind: 'property' | 'relationship', name, … }: a property carries type/required/hint/options/defaultValue, a relationship carries target/many. Form state lives here rather than $localState because rows are structured and validated as a whole, and the LLM flow fills the same draft
  - editingShapeId: string | null — the Shape record being edited; null means the draft is a new model
  - draftErrors: string[] — wizard-facing validation errors from the last save attempt
  - savingShape: boolean — a save is in flight
  - aiAvailable: boolean — AI model generation is available (the agent has a Claude API key configured)
  - generating: boolean — an AI generation is in flight
  - hintEntities: { entity, source: 'core' | 'shape' }[] — entities offering AI-hint tuning in this space: core interpretable vocabulary (TaskBlock, EventBlock, Relationship) plus the space's own shapes
  - extractionCandidates: string[] — entity names an extraction pass COULD write here: core vocabulary that declares itself extractable, plus every adopted shape that does. Candidacy, not a decision — which of these a call actually looks for is two layers down (spaceStore.extractionTargets, then the call's own participants). Read it to offer a choice, and to display findings: a card should show a record somebody extracted an hour ago even if the target has since been switched off
  - relationshipTargets: { label, value }[] — what a relationship may point at here, ready for a we-select: this space's own models, then block types, then other apps' models. Core infrastructure entities are deliberately absent
  - identityOptions: { label, value }[] — "None" plus every named property of the open draft, for the identity picker. Built in the store because a schema can map options but cannot prepend one
  - nameOptions: { label, value }[] — "Work it out" plus every named property of the open draft, for the naming-field picker. A different first entry from identityOptions on purpose: no identity means no dedup key, where no naming field means the name is DERIVED (a property called name or title, else whichever string is required or first) — there is no such thing as a record with no name
  - hintEditor: the hint editor state ({ entity, classHint, defaultClassHint, rows: { name, predicate, hint, defaultHint }[], customized }) or null while closed — non-nullness mounts the hint editor modal
  - hintBusy: boolean — the hint editor is loading or saving
  - extractionNeedsIdentity: boolean — the open draft would be extracted into and has no field to recognise what it already wrote, so every pass duplicates everything. A warning to put beside the switch, not a refusal: the wizard saves either way
  - memberOptions: { rowId, options }[] — each member's default-value picker entries. Read with find(shapeStore.memberOptions, { rowId: member.rowId }) rather than off member: rows are mutated in place while typing, so values hanging off the row cannot be reactive
  - expandedMembers: string[] — rowIds whose detail panel is open. Read with { $: 'member.rowId in shapeStore.expandedMembers' }; a new row and any row an error names open themselves. Generation leaves rows closed — a collapsed row shows its hint, so what was generated is readable without opening anything
  - generateIntent: 'none' | 'generate' | 'regenerate' | 'replace' — what the generate button would do right now, given what the draft holds. Label it "Regenerate" on 'regenerate' and 'replace' and "Generate" otherwise — 'none' is an empty draft, which has nothing to re-run, so testing for 'generate' alone labels a fresh form wrongly. Disable only on 'none', and route the click through requestGenerateFields, which decides whether to ask first
  - confirmReplaceFields: boolean — the "replace the fields below?" confirmation is showing. Only ever raised for a generation over hand-written rows; a generated proposal nobody touched re-runs on the click
  - confirmDiscard: boolean — the "discard this model?" confirmation is showing
  - hintEditorDirty: whether the open hint editor holds edits that closing would lose. What a discard guard reads: the rows come from the model’s declaration, so a schema has no set of local names it could test. Compares against the state the editor opened in, so an editor somebody only read closes without a question
- Actions:
  - openShapeWizard(shapeRecordId?): opens the model wizard — empty for a new model, or pre-filled from a stored shape to edit it
  - cancelShapeWizard(): closes the wizard, discarding the draft
  - setShapeField(field: 'name' | 'description' | 'icon' | 'classHint', value): sets one top-level draft field
  - setIdentityMember(rowId): chooses which member identifies duplicates for AI extraction; 'none' clears it. At most one, which is why it is a picker rather than a per-row flag
  - setNameMember(rowId): chooses which member NAMES an instance — the heading on a card, the caption on a canvas, the label on a drag chip; 'none' returns it to being worked out. Not the same question as setIdentityMember: a dedup key may be a composite nobody would recognise (an event's is its title and day joined), where this is the one short string every surface shows when it has room for one line
  - setExtractable(on: boolean): allows or refuses an AI extraction pass writing instances of the open draft. Its own action rather than a setShapeField case, because the value is a boolean and that field takes strings
  - addProperty(): appends an empty property (scalar field) row to the draft
  - addRelationship(): appends an empty relationship (edge to another model) row to the draft
  - removeMember(rowId): removes one member row
  - setMemberField(rowId, field, value): sets one field of one member row. 'options' takes the comma-separated string as typed
  - reorderMembers(rowIds: string[]): applies a drag-reorder. Pair with we-sortable's onReorder and pass { $: "arg.detail" } — order is the stored declaration order, not decoration
  - toggleMemberExpanded(rowId): opens or closes one member's detail panel (hint, default, allowed values)
  - commitDraft(): publishes in-place edits to the draft signal. Typed fields are mutated without touching it so inputs keep focus, which leaves derived values stale — pair with onBlur on a field something else is computed from
  - replaceDraft(draft): replaces the whole draft — how the LLM flow hands a generated model to the same review path
  - generateShapeDraft(description: string): generates a draft from a plain-language description and lands it in the open wizard for review. Proposes only — nothing is stored until the user saves. Gate the control on aiAvailable
  - generateShapeFields(): generates the draft's fields from what the author actually wrote — the name, description and AI hint they typed — and answers whatever they left blank, including anything a previous run had filled in (that being the machine's own output, which would otherwise steer the next prompt and return a model half about the last subject). Replaces the member list wholesale, so call requestGenerateFields from a button instead, and this from the confirmation it raises
  - requestGenerateFields(): the generate button's own entry point — generates now, or raises confirmReplaceFields when the click would discard hand-written rows. The store makes that choice because only it can tell a proposal nobody touched from rows somebody wrote
  - cancelReplaceFields(): dismisses the replace confirmation, keeping the fields as they are
  - requestCloseWizard(): closes the wizard, asking first when there is work to lose. Wire the modal's own close to this so a backdrop click is guarded too
  - cancelDiscard(): dismisses the discard confirmation and keeps the wizard open
  - saveShapeDraft(): validates, stores and adopts the draft. Errors land in draftErrors; success closes the wizard and the new entity becomes queryable via $query in this space
  - deleteShape(shapeRecordId): removes a model definition from the space. Existing entries keep their data; only the definition goes
  - openHintEditor(entity): opens per-space AI-hint tuning for an entity (core or space-defined)
  - closeHintEditor(): closes the hint editor, discarding unsaved edits. Pair it with hintEditorDirty in a discardGuard rather than wiring it to a modal’s close directly
  - setHintDraft(key, value): sets one hint in the open editor — key is 'class' or a property predicate
  - saveHintEditor(): writes the hints to this space and marks them customized, so schema refreshes stop reverting them
  - resetHintEditor(): back to the declaration's hints; release improvements flow again

ShellStore:
- State:
  - activeShellView: string | null — id of the currently open shell overlay ('profile' | 'settings' | 'schema-tests' | 'landing-page'), or null
  - createSpaceOpen: boolean — the create-space modal is open. Shell state because more than one place opens it; bind the modal’s open prop to this and close it with setCreateSpaceOpen
  - joinSpaceOpen: boolean — the join-a-space dialog is open, where somebody pastes an address they were sent. Shell state for createSpaceOpen’s reason, opened from the same two places. It exists because a share link only opens itself on the web: a desktop build has no address bar and registers no protocol handler, so an address arriving by any other route needs somewhere to go
  - pendingScreenSources: ScreenSource[] — the screens and windows the host is waiting for somebody to choose between ({ id, name, thumbnail }), or empty. Non-empty only on a desktop host whose OS draws no picker of its own, and only while a share is being asked for: on the web, on macOS 15+ and under a Wayland portal the OS or the browser asks instead
  - pendingDestructive: the destructive action a space template just asked for ({ path, title, body }), or null. The host raises its own confirmation in front of every one of them — a space template arrives from a stranger, so whether it asks before deleting is not the stranger's decision. Host chrome renders it; a template writing its own dialog for a destructive store action would be a second question about one click
  - spaceSettingsOpen: boolean — the space-settings panel is open. It configures whichever space is open, so it needs no id; bind a launcher’s active state to this
  - spaceSettingsTab: string — the tab the space-settings panel opens on ('about' | 'features' | 'vocabulary'). A starting position read once as the panel mounts, not a controlled value: somebody who then walks to another tab stays there. Set it by passing a tab to openSpaceSettings
  - dockGeometry: Record<dockId, DockGeometry> — every registered panel's resolved box (top, left, width, height, edge, mode) and its state — hidden behind another tab, collapsed to its bar, stowed in a lane collapsed to its edge, and which of those its titlebar may offer (canCollapse, canStow). Read a field as { $: "shellStore.dockGeometry['<id>'].<field>" } — by index, since a dock id holds a colon; the frame a panel is wrapped in binds its geometry this way so a move rewrites props rather than remounting
  - contentInset: { top, right, bottom, left } in pixels — what the content viewport gives up to panels that displace it. Read it to keep your own fixed chrome clear of docked panels
  - coveredInset: { top, right, bottom, left } in pixels — what FLOATING panels are covering. They take no room, so they leave contentInset at zero while still sitting over the content: this is the part of your own box the reader cannot see. Read it to keep something in the clear where contentInset would say there is nothing in the way
  - dockResizing: boolean — a panel is being dragged or resized right now. Suspend transitions while it is true so the edge tracks the cursor
  - panelMaximised: boolean — some panel covers the whole window. The app's own chrome — sidebar, module rail — hides while it is true; a template's fixed chrome should too
  - dockPlacement: Record<dockId, { snap, displace, canDisplace, … }> — where each panel is parked, for its frame to read: which of the eight snaps it is at, whether it displaces content, and whether it may. The state a position menu ticks; dockGeometry is the resulting box
  - movingDock: string | null — the id of the panel being dragged, or null. What mounts the snap-target overlay
  - activeSnap: SnapPoint | null — the snap the moving panel would take if dropped now ('top-left' | 'top' | … | 'left'), so that target can light up
  - snapTargets: { id, top, left, width, height }[] — every snap target’s box while a panel is being dragged, measured against the room left for it. A place a card is already parked at is left out: the question there has stopped being whether and started being where among what is there, which the insert slots answer. Empty otherwise
  - insertSlots: { key, index, edge, lane, mode: 'band' | 'lane' | 'tab', top, left, width, height }[] — every place a dragged panel could land, while one is being dragged. 'band' offers a new lane at that distance inboard, 'lane' a new seat beside the panels in the lane it names, 'tab' the seat itself, to stack behind whatever is showing there. A 'tab' slot naming no edge is a floating panel offered as somewhere to stack. Empty otherwise
  - activeInsert: string | null — the slot a drop would take right now, as that slot's `key`. Compare it against slot.key rather than rebuilding the string, which names four things
  - dragGhost: { top, left, width, height, title } | null — the outline following the cursor while one TAB is dragged out of a stack. A panel is moved instead, and so is a whole stack — whose other tabs ride along hidden — so this is null for both of those and between drags
  - layoutPinned: Record<string, boolean> keyed by panel id — whether that panel has been dragged away from where meta.panels declared it. False for a panel no layout mentions, since there is nothing to go back to. Gate a "reset to layout" affordance on it rather than on a placement merely existing
  - layoutDirty: boolean — the interface on screen has been rearranged: one of its panels moved, resized or closed. What a whole-arrangement "reset layout" control is gated on, and not the same question as any layoutPinned entry — a closed panel has no placement, and a panel declared for another route is not among the docks at all. False for an interface declaring no panels
  - panelSupplied: Record<moduleId, boolean> — modules whose panel this interface supplies itself, by declaring a `meta.panels` entry that names the module and carries a `node`. What a module's dock frame asks before drawing its own contents; the module still owns whether the panel is open and how big it is
  - layoutNames: string[] — the arrangements saved for the interface on screen, by name, sorted. The three-rung chain has one user slot; these are how to keep more than one — a “recording” and a “reviewing” for the same template. Empty for an interface with none
  - activeLayout: string — the saved layout the arrangement on screen is, or '' once anything has been moved since. Mark the matching row as selected
  - panelsHidden: boolean — somebody has put every panel away at once, from the rail or with Cmd/Ctrl+\. The panels are also away while a shell overlay (settings, profile, about) is open, which is not this and does not set it. Either way they are hidden, never unmounted, and the content gets the room they took
  - hasPanels: boolean — some panel is open on screen to put away. What the hide-all toggle is gated on
- Actions:
  - openShellView(id: string, path?: string): opens a shell overlay by id, optionally at a route inside it — the overlay keeps its own memory router, so this never touches the browser URL
  - closeShellView(): closes the currently open shell overlay
  - setCreateSpaceOpen(open: boolean): opens or closes the create-space modal. Shell state rather than a page’s $localState because more than one place opens it — the settings page and the sidebar’s spaces group — and a page-scoped flag could only be set from inside that page
  - setJoinSpaceOpen(open: boolean): opens or closes the join-a-space dialog, where somebody pastes an address they were sent. Asking for the dialog is not joining anything — spaceStore.joinSpace is where that decision is taken and keeps its own grant. Shell state for setCreateSpaceOpen’s reason, and offered beside it: the sidebar’s spaces group offers the pair behind one +
  - chooseScreenSource(sourceId: string): answers the host’s "which screen do you want to share" with one of pendingScreenSources, or an empty id to cancel — which the page receives as the same refusal a browser’s own picker gives when dismissed. Host chrome only: a `getDisplayMedia` is outstanding the whole time the prompt is up
  - confirmDestructive(): runs the destructive action the host is asking about. Host chrome only, for the reason pendingDestructive is: an action able to answer its own confirmation is the confirmation being skipped
  - cancelDestructive(): refuses it. The waiting action resolves as though it had been blocked
  - toggleSpaceSettings(): opens or closes the settings panel for the space on screen. What a gear in chrome should call — a control that is always present toggles, so a second press puts back what the first press changed
  - openSpaceSettings(): opens that panel without closing it again. For a control that sits on the very fields it leads to (the About view’s pencil), where a toggle would break the promise to show them
  - closeSpaceSettings(): closes the space-settings panel
  - scrollToId(id: string): smooth-scrolls the element with that DOM id into view
  - beginDockResize(id: string): remembers a panel's current size so the drag that follows is measured from it. Wire it to we-resize-handle's resizestart. For a divider between lane-mates it first makes every member's stored size what is on screen, so the boundary can then travel the whole lane
  - resizeDock(id: string, side: 'left' | 'right' | 'top' | 'bottom' | 'top-left' | …, dx: number, dy: number): applies a resize drag from that side or corner, in screen pixels since it began. Wire it to resize with { $: 'arg.detail.delta' }
  - resizeColumn(id, delta): moves the boundary between this panel and the next one in its lane, giving one what the other loses. What the earlier panel's trailing grip calls when it has a lane-mate — its bottom in a side lane, its right-hand edge in a top or bottom one. A boundary belongs to both panels, so only one of them draws it
  - endDockResize(): ends the drag and persists the size
  - fitDock(id: string): shrinks a panel to the shape its content wants, keeping the width the user chose — only when the module declares an aspect for its panel
  - beginDockMove(id: string, pointerX: number, pointerY: number): begins moving a panel, remembering where it and the pointer started. A maximised panel shrinks back under the cursor
  - raiseDock(id: string): brings a panel in front of the others — what a pointer landing on its frame does, and what a drag or maximising does on its own. The most recently raised panel is the one on top; nothing else decides stacking
  - moveDock(id: string, dx: number, dy: number): applies a move, in pixels from where beginDockMove was called
  - beginTabDrag(id: string, pointerX: number, pointerY: number): a press on one tab of a stack. Records only — a tab is a click until the pointer travels, and the panel does not leave its seat until the drop
  - moveTab(id: string, dx: number, dy: number): past the drag threshold, shows where the tab would land. The tab itself stays put; only the guides follow
  - endTabDrag(id: string, pointerX: number, pointerY: number): a press that went nowhere brings the tab forward; one that travelled lands it, or leaves it as a card under the pointer
  - endDockMove(id: string): drops the panel — onto the snap or insert slot it is over, or where it is if that is nowhere
  - resetDockToLayout(panelId: string): puts a panel back where meta.panels asked for it, forgetting where it was dragged. Forgets rather than rewrites, so the panel keeps following the layout afterwards — including when the template changes it. Pair with layoutPinned
  - closeTemplatePanel(panelId: string): dismisses a panel the interface declared in meta.panels, by that panel's id. What its titlebar's close button calls
  - openTemplatePanel(panelId: string): puts a closed one back. The only way back to a panel that has been closed — it has no titlebar left to ask from — so a template offering a close should offer this too
  - resetTemplateLayout(): puts every panel of the interface on screen back the way meta.panels declared them, and reopens the ones that were closed. The whole-arrangement counterpart of resetDockToLayout, and the only way back for a closed panel, which has no titlebar to reset itself from. Scoped to the template rather than the route, so a declaration that varies by route is reset once. Pair with layoutDirty
  - saveLayout(name: string): saves the arrangement on screen under a name — its panels’ placements, which tab of each seat is showing, and which panels are closed. Scoped to the template, as placements are. Replaces a layout of that name
  - applyLayout(name: string): puts the arrangement back to a saved layout. What the layout does not mention returns to what meta.panels declared, exactly as a reset would leave it
  - deleteLayout(name: string): forgets a saved layout
  - snapDock(id: string, snap: SnapPoint): parks a panel at one of the eight positions from a menu — the keyboard's way to move it
  - insertDock(id: string, edge: 'left' | 'right' | 'top' | 'bottom', position: number, mode?: 'band' | 'lane' | 'tab', lane?: number | 'float'): puts a panel on that edge, renumbering what it lands among — what a drop does. 'band' opens a lane of its own at that distance inboard; 'lane' takes a new seat at that position along the lane named by `lane` (a distance inboard, or 'float' for the floating one); 'tab' joins the seat at that position, stacking behind whatever is showing there
  - toggleMaximiseDock(id: string): covers the content region with the panel, or goes back to being a card. Nothing about where the panel was is overwritten while it is on
  - toggleDockDisplace(id: string): makes the panel push the content aside, or stop. A toggle rather than a setter because a menu item reports only that it was clicked
  - toggleCollapseDock(id: string): folds a panel, and every tab stacked with it, down to its titlebar — or opens it again. A fold always takes height: down a side lane the lane-mates take the room, and across a top or bottom lane the lane is as thick as its tallest open member, so folding the last one hands the room back to the content. The content is hidden, never unmounted. Refused where there is nowhere for that room to go — a sidebar alone on its edge, or the last open member of a side lane; collapse that lane to its edge instead. Read dockGeometry[id].canCollapse
  - toggleStowLane(id: string): collapses the whole displacing lane this panel is in to a strip at its edge naming its panels, or opens it again. Every panel keeps its size, which tab is showing and whether it is folded; the content is hidden, never unmounted. Offered on the lane's first titlebar — read dockGeometry[id].canStow — and a press anywhere on the strip opens it
  - revealDock(id: string): brings an open panel into sight wherever it is hidden — to the front of its stack, unfolded, or by opening the lane it is collapsed into — and flashes its tab when it came forward in a stack. Leaves a closed panel alone. What the module rail does for a panel that is open and concealed, instead of the module’s own toggle
  - openModulePanel(dockId: string): opens one of a module’s panels, by its dock id (`<moduleId>:<name>`). The host holds whether most panels are open, so this is where the flag lives; a module that owns its own flag is asked through the actions it named instead
  - closeModulePanel(dockId: string): closes one of a module’s panels. What the titlebar’s close button calls for a host-owned panel
  - toggleModulePanel(dockId: string): opens a module’s panel if it is closed, closes it if it is open — what the rail’s button does for a panel that is in sight. Prefer spaceStore.launchModule from a template, which also brings a concealed panel into view
  - togglePanelsHidden(): puts every panel away at once, or brings them all back exactly as they were — hidden, never unmounted, with the content given their room while they are away. Does nothing while a shell overlay is up, when the panels are away already. Asking for one panel (revealDock, a rail launcher) brings them all back
  - breakOut(panelId: string, x?: number, y?: number): takes a section out of the template and makes it a panel — floating under the pointer when given one, else at the snap its meta.panels entry named. Refused for a section declared `fixed`. Takes the panel's own id, not the dock id
  - returnHome(panelId: string): puts a broken-out section back in the template at the outlet it came from. What the placeholder’s "Bring back" and the position menu’s "Return to page" call
  - stackDockstackDock(id: string, position: number): stacks a panel onto a floating one so the two share a seat and a tab strip — what a drop into the middle of a float does. Two panels in open space are in no lane, so `position` indexes the floating panels a drop could land on rather than naming one
  - insertHome(id: string, lane: string, position: number): drops a panel into a home lane at that position along it, renumbering the lane. Only a template's own sections land in one, and only where the lane's `accepts` allows
  - saveArrangementAsTemplate(): saves the arrangement on screen as a template of your own — a copy of the schema with the resolved placements written into its meta.panels and nothing else changed. The explicit bridge from arranging to authoring. Resolves true on success. Pair with layoutDirty

SpaceStore:
- State:
  - memberDids: string[] — DIDs of all members in the current space (includes own DID)
  - members: AgentProfileSummary[] — cached profiles for all memberDids
  - spaceDefaultTemplateId: string — the current space's default template ID (empty string when no space is active)
  - spaceDefaultThemeId: string — the current space's default theme ID (empty string when no space is active). The counterpart to spaceDefaultTemplateId; compare against it to mark which theme a space is currently on
  - currentSpace: Space | null — the current space model (all Space fields: uuid, url, name, description, access, discovery, avatar, coverImage, defaultTemplateId, defaultThemeId, location, plus id/author/createdAt)
  - mySpaces: array of Space objects — every space the agent holds, across all joined datasets
  - personalSpaces: array of Space objects (local/personal spaces; all Space fields)
  - sharedSpaces: array of Space objects (shared/neighbourhood spaces; all Space fields)
  - spaceList: { uuid, name, description, avatar, kind: 'shared' | 'personal' | 'foreign', isWeSpace, canAdminister }[] — one row per joined dataset the agent can act on, ordered like the sidebar and excluding the system datasets. Includes datasets that are not WE spaces (kind 'foreign', isWeSpace false), which are waiting to be initialized. `uuid` is the dataset id, so it keys navigation and settings whether or not a Space record exists
  - routeSpaceUnjoined: boolean — the current route points at a space this agent has not joined, as a settled fact. What a join gate should read: `currentDataset` being null is also true for the first frames of a refresh, so gating on that flashes a join prompt at someone already inside. False while the answer is still unknown
  - spacePath: string — the path a space's own pages hang off (`/space/<segment>`), empty outside a space. What a link to one record is built from: an href has to be absolute, since a browser resolves a relative one against the current URL rather than against the route tree, and the segment is the neighbourhood CID for a shared space and the dataset id for a personal one — only the URL says which
  - creatingSpace: boolean (true while a new space is being created)
  - joiningSpace: string — the shared id of the space a join is running for, '' when none is. The id rather than a flag so a list can spin only the row being joined; a gate compares it against its own route segment. Stays set for the whole join, which outlives the network call that starts it
  - joinSlow: boolean — that join has been going long enough to be worth mentioning. Joining a shared space has to fetch and install it before it exists anywhere, so a first join routinely takes a minute; pair with joiningSpace to say so instead of spinning in silence
  - joinError: { spaceId, message } | null — the last join failure, ready to display. Carries the space so a gate can tell whether the failure is its own: compare joinError.spaceId against the route segment, or a bare message follows the user to the next unjoined space they open
  - orderedSidebarItems: array of sidebar items in user-defined order (uuid, name, avatar, spaceId) — personal + shared spaces merged
  - foreignSpacePrefill: { name, description, avatar } | null — detected from a foreign app's own model (e.g. Flux's Community) for prefilling the "Initialize as WE space" gate; null once the dataset is a WE space or no recognized foreign model is found
  - enabledModules: string[] — ids of the feature modules THIS SPACE has turned on: the community’s decision, shared with every member. An unset value means "not decided", not "none": it falls back to every registered module, so spaces predating the setting keep the chrome they had
  - taskStates: { id, name, slug, semantic, color, retired, defined, approvals, approverKind }[] — the states this community’s work moves through, its own if it has defined any and otherwise the defaults ("unset" means not decided, never none). Ordered by the community’s own arrangement where it has one, otherwise by what each state counts as — what is coming, what is happening, what is stuck, what is finished, what was dropped. `slug` is what TaskBlock.status holds; `semantic` is the closed fact underneath a community’s own word, so "is this outstanding?" stays answerable after a rename. Includes withdrawn states, because a task sitting in one still has to resolve — offer offeredTaskStates instead. `defined` is false for a default the space has never written down — a virtual state, which becomes a record the first time somebody reorders it, withdraws it, or names a state with its slug. `approvals` is how many distinct people must agree before a task enters the state (1 is a plain drop) and `approverKind` the involvement kind whose holders’ agreement counts (empty: anybody’s) — see taskFlowEnabled
  - offeredTaskStates: { id, name, slug, semantic, color, retired, defined, approvals, approverKind }[] — the same list without the withdrawn ones. What a state picker or a new board column should offer
  - taskStatesLoaded: boolean — the space has been asked for its states. An empty list is otherwise indistinguishable from "not fetched yet"; gate an empty state on it
  - involvementTypes: { id, name, slug, semantic, reflexive, appliesTo, icon, color, retired, defined }[] — the kinds of part a person can have in a record: "Assigned" and "Reviewing" on a task, "Going", "Maybe" and "Not going" on an event, plus whatever this community has named. Its own if it has named any, otherwise those defaults. `slug` is what Involvement.kind holds. `semantic` is the closed meaning underneath the name — responsible, reviewing, committed, interested, declined — so a board still finds the assignee after "Assigned" is renamed. `reflexive` kinds are an agent’s own answer, which nobody else may give, and an agent holds one per record. `appliesTo` is the entity names the kind is offered on, empty for all — filter with `'TaskBlock' in kind.appliesTo || !count(kind.appliesTo)`. Includes withdrawn kinds; offer offeredInvolvementTypes. Read who holds them through the `involvement` host function
  - offeredInvolvementTypes: { id, name, slug, semantic, reflexive, appliesTo, icon, color, retired, defined }[] — the same list without the withdrawn ones. What an assign menu or an RSVP control should offer
  - involvementTypesLoaded: boolean — the space has been asked for its kinds of involvement
  - templateOverrideOptions: { label, value }[] — options for the per-space template override picker: "Use the space’s default" (space-default), "Use my default" (agent-default), then every template. Each of the first two names what it resolves to. Pre-built because a schema can map a store array into options but cannot prepend one, and without those entries overriding would be one-way
  - themeOverrideOptions: { label, value }[] — the same, for themes
  - spaceThemePinned: boolean — this agent has pinned a theme for the space on screen that differs from what would otherwise apply, so there is something for a reset to undo. False outside a space, and false for a pin that happens to name what the space resolves to anyway. Gate a "pinned here / reset" affordance on it rather than on the pin merely existing
  - installedModules: string[] — ids of the feature modules THIS AGENT wants available anywhere. Personal, held in the root dataset; unset means "not decided" and falls back to every registered module
  - requiredModules: string[] — module ids the template on screen mounts components from, derived by walking the schema rather than read from meta.components (which no template fills in). What makes uninstalling a capability module refusable
  - missingModules: string[] — of those, the ones this agent has not installed. Non-empty means the template is mounting a component nothing provides, so part of the page silently renders nothing. Empty in the ordinary case
  - activeModules: string[] — what actually renders here for this agent: registered ∩ installed ∩ enabled, less the modules muted in this space. Module chrome and the launcher rail gate on this; enabledModules alone is not sufficient
  - moduleInstallSettings: { id, name, description, icon, installed, surface, switchable, capabilities }[] — every registered module and whether this agent wants it anywhere. `capabilities` is what a person is agreeing to — derived from the module's manifest (its permissions and the kernels it reaches) and what it contributes (a panel, storage in the space), never authored, so it cannot go stale. The global Settings → Modules list, and the only place an 'app', 'capability' or agent-scoped module is decided about: a contribution is gated at the layer where it renders, and only 'chrome' (panels, slots, rail) and 'content' (sections, blocks) render inside a space. `surface` is derived from what the module contributes. Unset, every registered module counts as installed — a seed entry's `enabled: false` is about spaces, not people. Its per-space counterpart is `modules` on each spaceList row, which carries enabled/installed/visible/active together and lists the community-decided modules only: chrome or content, and not agent-scoped. A community-decided module a space has off takes its sections and its space-level settings out of that space
  - moduleLaunchers: { id, icon, label, active, busy, concealed }[] — one entry per module panel that asks for a rail button, plus the launchers a module declares of its own; what the host module rail renders. `id` is a panel’s dock id (`<moduleId>:<name>`) or a launcher’s key, and is what launchModule takes. `active` is the module reporting its surface open; `concealed` says that panel is open and out of sight — a background tab of a stack, folded to its bar, or in a lane collapsed to its edge — so light the button on `mod.active && !mod.concealed`, since pressing a concealed one brings the panel forward rather than closing it. `busy` says the module is working in the background — an extraction pass running — and is independent of `active`, so a rail can show work going on behind a closed panel. Pair with { $action: "spaceStore.launchModule", args: [{ $: "mod.id" }] }
  - spaceViews: ResolvedView[] — this space's sections resolved: which view renders at which segment, in the space's order, each carrying its schema. The host builds the route tree from it; a nav strip reads viewNav, which is this without the payload
  - routableViews: ResolvedView[] — every view that could render here, at its permanent segment — what routes are built from. Separate from spaceViews because it changes when a view is installed, not when a switch is flicked
  - enabledViewIds: string[] — ids of the sections the community has turned on here. What a route body is gated on; not the nav list, which also drops this agent's hidden ones — hiding a section for yourself must not make its URL refuse you
  - viewNav: { id, segment, label, icon, path }[] — the sections as a nav strip reads them: enabled by the community, minus those this agent hid, in order. One source with the routes, so nav and routes cannot disagree
  - linkLanguageTemplateOptions: { label, value, icon, description }[] — how a shared space can sync (its link language), for a we-select, default first; value is the template address. Labelled by how it syncs ("Peer-to-peer", "Server (host)") rather than by the template’s package name, and `description` is one sentence on what choosing it means — bind a we-form-field’s description to the selected entry’s. Only templates publishing can fill in are listed. Empty until the backend answers, and on a backend with no choice to offer
  - defaultLinkLanguageTemplate: string — address of the template publishing uses when none is chosen: the backend’s default, empty until it answers. Show it as the picker’s value while nothing is chosen — { $: "local.linkLanguage ? local.linkLanguage : spaceStore.defaultLinkLanguageTemplate" } — and pass the bare choice to createSpace, rather than copying it into local state, which freezes whatever it was at that moment
  - mutedDids: string[] — DIDs this agent has muted, everywhere. Private, held in the root dataset. A feed filters on it before rendering: { $: '!(post.author in spaceStore.mutedDids)' }. Hides on this screen only — a neighbourhood is writable by every member, so nothing here removes anything for anyone else
  - mutedAgents: MutedAgent[] — the full mute records (did, description), for a settings list that wants the note as well as the DID
  - readMarkers: { nodeId, lastReadAt }[] — when this agent last read each node. No row means never read, so everything is unread. Read with find(spaceStore.readMarkers, { nodeId: item.id }); a keyed map would not be indexable by a row
  - unreadNodeIds: string[] — ids of the containers in this space holding something newer than this agent's marker for them, or never read. What an unread dot reads: { $: 'channel.id in spaceStore.unreadNodeIds' }. Ids rather than counts, since a count needs every child's timestamp
  - myMentions: { id, author, createdAt }[] — nodes in this space that mention this agent, newest first. createdAt is the backend’s comparable timestamp. Filtered client-side, so right for a space and wrong for an inbox across many
  - spaceModuleSettings: SettingRow[] — what each capability that declares settings is set to FOR THIS COMMUNITY, as rows a screen renders directly: { group, groupLabel, key, label, description, type, options, value, source, set, locked, lockedBy }. `value` is already resolved across every level that had an opinion; `source` names the level that decided it ('default' when nobody did); `set` says whether THIS level holds an opinion, so a reset has something to undo; `locked` says a level that BINDS this one has forced it and the control must be disabled rather than springing back — a member's private refusal does not bind the community, so it never locks this list. Built from what modules declare, so a module that adds a setting gets a control with nothing to register
  - myModuleSettings: SettingRow[] — the same rows, for what THIS AGENT has decided in THIS space. Private, held in the root dataset. The most specific of the four levels
  - agentModuleSettings: SettingRow[] — the same rows, for what THIS AGENT has decided everywhere. Private. Render it in global settings, where the question is what you want in every space
  - autoInterpret: boolean — whether this space has calls interpreted (extracted into records) as they happen. A community decision, off by default. Readable by every member; writing it is space-settings
  - extractionTargets: string[] — the models a call in this space starts out extracting. The middle of three layers: shapeStore.extractionCandidates says what COULD be extracted, this says which of them a call begins with, and the call's own participants add or remove from there (modules.transcribe.extractionTargets). Unset falls back to the two classes that were hardcoded before the setting existed, so no space silently stops extracting. Writing it is space-settings
  - taskFlowEnabled: boolean — this space’s task states ask for agreement: some state needs more than one approval, or names whose approval counts. Where true, a card dragged into such a state waits instead of moving, and arrangedBoard(…).flow[card.id] describes what it is waiting on. Gate an explanation of the waiting on it; the board needs nothing else
  - canAdministerCurrentSpace: boolean — whether this agent may change what every member of the space on screen sees. The readable form of canAdministerSpace, which an expression cannot call. Gate an admin-only control on this rather than on `x.author == me.did`, which asks who made the row and not who runs the space
- Actions:
  - createSpace(name, description, access: 'personal' | 'shared', discovery: 'hidden' | 'listed', avatarFile?, coverImageFile?, location?, linkLanguageTemplate?): creates a new space with full setup. linkLanguageTemplate is an address from linkLanguageTemplateOptions and only matters for a shared space; empty uses the backend's default
  - joinSpace(id: string, focus = true): joins a shared space by share link, neighbourhood URL or CID, or focuses it if already joined. Pass focus: false to join without navigating there — for a caller that needs the dataset present rather than open, which is how the marketplace reads its own dataset without moving you out of the space you are in. Rejects when the join could not be completed, so onSuccess means what it says; watch joiningSpace/joinSlow/joinError for what to show while it runs. A join whose network call times out keeps going: the backend usually finishes anyway, and this waits for that before believing the failure
  - initializeAsWeSpace(name: string, description: string, avatarValue?: File | string | null): installs WE's Space SDNA into the current, already-joined, foreign-native dataset (e.g. one synced in from Flux) and creates a Space entity in place — access is always 'shared' since the dataset is already a published neighbourhood
  - removeSpace(uuid: string): removes a space — clears its global-discovery listing (when authored by this agent) and removes the backing dataset
  - createPost(editorState: unknown): creates a new post
  - updatePost(postId: string, editorState: unknown): reconciles an edited post against its existing blocks — updates/reuses blocks whose id survived the edit, creates new ones, deletes ones no longer present
  - moveChild(childId: string, fromId: string, toId: string): moves an owned child between two collections. Relinks the two children edges; the child itself is untouched. Not for a board — a column arranges its cards through moveCardToColumn, which is a different relation
  - createBoard(title: string, parentId?: string, options?: { gathers?: string }): makes a board — a CollectionBlock whose ordered children are its columns, one per state the community uses. Returns its id. Pass parentId to put the board inside another collection (a call’s record), which is where an anchored Boards view lists it. A board made this way shows only what is put on it; openBoardFor makes the ones that gather
  - openBoardFor(anchorId?: string, title?: string, dataset?: string): the board for a container — one call’s, or the space’s own — making it if nobody has yet. Returns its id either way. The board it makes gathers from that container, a fact the board carries in its `gathers` relation, so anything rendering it needs only the id. Call it from a click rather than on mount: creating a board writes records into a space everybody shares
  - addBoardColumn(boardId: string, name: string, slug?: string): adds a column. **With a slug** it IS that state on this board — matching work arrives on its own and dropping a card there changes the card’s state everywhere. **Without one** it is a local lane: nothing arrives by itself and a card put there is positioned rather than reclassified. A bound column given its state’s own name stores no title, so its heading follows the vocabulary when the state is renamed
  - removeBoardColumn(boardId: string, columnId: string): takes a column off a board — the column record only, never the work in it. A column arranges its cards rather than owning them, so nothing that walks children can reach them; on a made board they are handed to the board itself so they stay on it. They keep their state, so they reappear in another column bound to it or in the unplaced column
  - renameBoardColumn(columnId: string, name: string): renames one column on this board. Its slug — its meaning — is untouched; renaming a state everywhere is Settings → Vocabulary
  - reorderBoardColumns(boardId: string, orderedIds: string[]): the order this board reads its columns in. Pair with we-sortable’s onReorder and pass { $: "arg.detail" }
  - arrangeColumn(columnId: string, orderedIds: string[], columnOrder?: string[]): records the order somebody dragged one column’s cards into — the column’s `arranges`, an ordered relation, so two people rearranging at once converge instead of one write discarding the other. Pair with we-sortable’s onReorder. Where the column shows only some of its cards — a people filter hiding the rest, one person’s row — pass the column’s whole order as columnOrder (arrangedBoard’s contents[col].order): the moved cards go back into their own slots and the hidden ones keep theirs, where without it every hidden card would drop to the bottom of the column for everybody
  - moveCardToColumn(fromColumnId: string, toColumnId: string, cardId: string, orderedIds?: string[], toSlug?: string, columnOrder?: string[]): moves a card between columns — and writes its state when the column it joins names one, which is what makes “done is done” true on every board. A lane writes no state. One transaction, so no reader sees the card in two columns. Pass orderedIds — we-sortable’s `arg.detail.ids`, the target column’s whole new order — to seat the card where it was dropped; without it the card appends. An empty fromColumnId means the card came from nowhere on this board — Unplaced, or a picker. Pass toSlug — the state the target column stands for, which the board already has on screen — and the card is drawn in its new column the instant it is dropped rather than a round trip later: the store cannot know that state without reading the column, and until it does the card cannot be drawn there at all. A hint for the drawing only; the write reads the column itself, so a stale one costs a frame and never a wrong write. columnOrder is the target column’s whole order, for a drop into a column showing only part of itself — see arrangeColumn
  - addTaskToColumn(columnId: string, title: string, anchorId?: string): makes a task straight into a column, parented to the board’s anchor when there is one so every other scoped surface finds it. A bound column also gives it that column’s state
  - setAttending(nodeId: string, attending: boolean): joins or leaves a node's participant roster — an RSVP. Writes only this agent's own entry, so the roster stays conflict-free. Boolean, so a switch can pass `event.detail` bare
  - setAgentMuted(did: string, muted: boolean, description?: string): mutes or unmutes an agent for this agent everywhere, with an optional note. Positively phrased so a switch can pass `event.detail` bare
  - markRead(nodeId: string, spaceUuid?): marks a node read as of now, so it leaves unreadNodeIds. Silent on failure — a lost marker is a stale dot, not an error
  - uploadFile(file: File, name?: string): stores a file and returns the URL to reference it by, or null. Images are compressed on the way through. For a template doing its own media UI — without it, only the block composer could accept an upload
  - deleteCollection(collectionId: string): permanently deletes a CollectionBlock and everything inside it, recursively. Kind-agnostic — a post, a call record and a board are the same shape, so this is the one delete for all of them
  - updateSpaceImage(field: "avatar" | "coverImage", imageFile: File, spaceUuid?): uploads and sets the space avatar or cover image
  - updateSpaceMeta(updates: { name?, description?, discovery?, location? }, spaceUuid?): updates the space everyone sees. Omit spaceUuid to target the space on screen; pass one to configure a space from the spaces list without navigating to it
  - setSpaceDefaultTemplate(templateId: string, spaceUuid?): sets the template members see when they enter that space. Only repaints the app when the target is the space currently on screen
  - setSpaceDefaultTheme(themeId: string, spaceUuid?): sets the theme members see when they enter that space
  - setModuleEnabled(moduleId: string, enabled: boolean, spaceUuid?): turns a feature module on or off for a space; writes the resolved list, so the first toggle also pins whatever was on by fallback. Omit spaceUuid for the space on screen
  - setSpaceModuleSetting(group: string, key: string, value?, spaceUuid?): sets one of a capability's settings for everyone in a space — `group` is the module id and `key` the setting's key, both off the row. **Omit `value` to clear it**, which returns the level to having no opinion: a stored value that happens to equal the default goes on overruling everything less specific while its control reads as untouched. Omit spaceUuid for the space on screen
  - setMyModuleSetting(group: string, key: string, value?, spaceUuid?): the same, for this agent in one space. Private — written to the root dataset, never to the space. Omitting `value` clears it
  - setAgentModuleSetting(group: string, key: string, value?): the same, for this agent in every space. Private, and global, so there is no space to name. Omitting `value` clears it
  - autoInterpretForCall(collectionId): whether ONE CALL is extracted as it happens — its participants' answer if they gave one, else the space's. A function rather than a value because the answer is per call, like canAdministerSpace
  - setAutoInterpretForCall(collectionId, on) => turns automatic extraction on or off for ONE CALL, for everyone in it. A participant's decision, unlike setAutoInterpret, which administers the space — and it leaves the space's default alone. Does not stop a pass already running: those tokens are spent
  - setAutoInterpret(enabled: boolean, spaceUuid?): turns automatic call interpretation on or off for a space. Omit spaceUuid for the space on screen
  - setThreadMode(mode: 'fractal' | 'flat', spaceUuid?): sets how deep conversations go here — whether a reply may itself be replied to. A decision about what may be ADDED, never about what is stored: replies are a tree either way, so switching to flat leaves existing threads drawn as they are and switching back restores the button that grows them. Read it back as spaceStore.currentSpace.threadMode; anything but 'flat' means fractal, so a space that predates the setting reads as fractal. Omit spaceUuid for the space on screen
  - setExtractionTarget(entity: string, on: boolean, spaceUuid?): adds or removes one model from what this space's calls start out extracting. Writes the resolved list, so the first toggle also pins whatever was on by fallback. The community's decision; a call's participants override it per call
  - setModuleInstalled(moduleId: string, installed: boolean): turns a module on or off for this agent in every space. Personal — writes AgentSettings.installedModules in the root dataset, so no other member sees it
  - setModuleVisible(moduleId: string, visible: boolean, spaceUuid?): shows or hides a module for this agent in one space, without changing what the community runs. Private: written to the root dataset, never to the space. Phrased positively so a switch can pass `event.detail` bare — wrapping it in another token would evaluate at render time and send a constant
  - setViewEnabled(viewId: string, enabled: boolean, spaceUuid?): adds or removes a section from a space. The community’s decision — every member sees it. Omit spaceUuid for the space on screen
  - reorderViews(viewIds: string[], spaceUuid?): sets the whole section order at once — what a drag-reorder writes. Pair with we-sortable's onReorder
  - setViewVisible(viewId: string, visible: boolean, spaceUuid?): shows or hides a section for this agent in one space, without changing what the community has. Private. Positively phrased so a switch can pass `event.detail` bare
  - setSpaceTemplateOverride(templateId: string, spaceUuid?): sets the template THIS AGENT sees in one space, overriding the community's default. Three values: 'space-default' follows the space, 'agent-default' follows your own global default (tracking later changes to it), or a concrete template id pins that one. Private, and applied immediately when that space is the one on screen. The sentinels are named values rather than '' because they are three distinct meanings, and only one of them is no value at all
  - setSpaceThemeOverride(themeId: string, spaceUuid?): sets the theme THIS AGENT sees in one space. Same three values as setSpaceTemplateOverride. Private
  - applyTheme(themeId: string): applies a theme where the agent is — pinned to the space on screen, or set as their global default when there is no space. What a theme picker in chrome should call: it persists, where setCurrentTheme only sets a signal that the next resolution overwrites. Which of the two it does is decided at click time, against state a schema cannot see
  - clearSpaceThemePin(): drops this agent’s theme pin for the space on screen, returning it to whatever would otherwise apply. The way back out of applyTheme, so the picker need not spell the FOLLOW_SPACE sentinel as a literal. Pair with spaceThemePinned
  - launchModule(moduleId: string): invokes that module's declared launcher action. Takes an id rather than a path because $action resolves a literal string, so a rail iterating over modules cannot build modules.<id>.<method> itself
  - createSignalType(config: Partial<SignalType>): creates a new signal type in the community; slug auto-derived from name if blank
  - createRelationshipType(config: Partial<RelationshipType>): names a kind of connection this community makes — "contradicts", "came out of". The counterpart to createSignalType; slug derived from name if blank
  - setSignalTypeRetired(signalTypeId: string, retired: boolean): withdraws a signal type from use, or brings it back. Never deletes the signals given with it — a signal names its type by record id while templates resolve it by slug, so DELETING a type strands every reaction ever given and re-creating one with the same slug does not restore them. Retiring is the reversible version: the type stops being offered, existing counts keep working, and un-retiring brings everything back. Filter the offered list with OFFERED_SIGNAL_TYPES from @we/template-kit; leave find()-by-slug unfiltered so history still resolves
  - createTaskState(config: { name, semantic?, color?, icon? }): names a state this community’s work moves through — "Blocked", "In review". The counterpart to createSignalType one concept along. The defaults stay virtual beside it; a name whose slug matches a default adopts that default rather than sitting beside it. The space’s own board gains a column for the new state in the same act. Slug derived from the name; it is what tasks store, so it is not editable afterwards
  - updateTaskState(slug: string, updates: { name?, icon?, color?, semantic?, approvals?, approverKind? }): changes a state the community already has — what it is called, the glyph and colour it is drawn with, and what the rest of the app reads it as. The counterpart createTaskState had no pair for, and the only way a state gets a colour after it is made: the three defaults ship without one. An empty string CLEARS a field, which is how a colour goes back to the template’s default without deleting the state. The slug is deliberately absent — every task stores it, so changing it would leave the work holding a word nothing defines; renaming is what `name` is for and it carries. `approvals` (a whole number, 1–20) and `approverKind` (an involvement kind’s slug, or empty) set what agreement the state asks for — the first state that asks for any turns the space’s states into a flow, see taskFlowEnabled. By slug, so editing a default adopts it
  - approveTaskMove(taskId: string): agrees with the move a task is waiting on — the same as dragging the card there yourself, so it counts toward the state’s approvals when the agent is one whose approval counts. Offer it where arrangedBoard(…).flow[card.id].canApprove
  - withdrawTaskMove(taskId: string): takes back this agent’s own vote on the move a task is waiting on, never anybody else’s. Offer it where arrangedBoard(…).flow[card.id].mine
  - setTaskStateRetired(slug: string, retired: boolean): withdraws a state from use, or brings it back. Never touches the work sitting in it — a task names its state by slug, so deleting the state would leave the work holding a word nothing defines. The same decision setSignalTypeRetired makes. By slug, so a default can be withdrawn: doing so writes its record, which is the moment a default becomes the community’s own
  - reorderTaskStates(orderedSlugs: string[]): sets the order this community reads its states in — which is the order of a board’s columns. An ordered relation rather than a number on each state, so two people reordering at once converge instead of one write discarding the other. A state the order does not mention still appears, after the ones it does. Slugs, because a default has no id until it is placed in an order, which adopts it. Key the rows by slug and pair with we-sortable’s onReorder, passing { $: "arg.detail" }
  - setInvolvement(nodeId: string, agent: string, kind: string, on: boolean): puts somebody on a record as a kind one member says about another — assigning a task, asking for a review — or takes them off. `on` is the state wanted rather than a toggle, so a menu passes the opposite of the tick it shows and a double press cannot undo itself. Every copy of the pair goes on removal. A reflexive kind is routed to respondTo, and refused for anybody but the agent it is about. Pair with a DropdownMenu of toggle entries: `onSelect: { $action: "spaceStore.setInvolvement", args: [{ $: "card.id" }, { $: "arg.id" }, "assignee", { $: "!arg.checked" }] }`
  - respondTo(nodeId: string, kind: string): gives this agent’s own answer to a record — "going", "maybe", "not-going" — replacing any other answer it held there, in one transaction. Pass an empty kind to withdraw the answer. Refuses a kind that is not reflexive. Shown on the click, before the write lands
  - createInvolvementType(config: { name, semantic?, reflexive?, appliesTo?, icon?, color? }): names a kind of part a person can have — "Shepherd", "Second pair of eyes". `appliesTo` is entity names joined with commas. `reflexive` is fixed once made. A name whose slug matches a default adopts it
  - updateInvolvementType(slug: string, updates: { name?, icon?, color?, semantic?, appliesTo? }): changes a kind the community already has. The slug and `reflexive` are absent — every involvement stores the one, and changing the other would rewrite who said what. An empty string clears a field. By slug, so editing a default adopts it
  - setInvolvementTypeRetired(slug: string, retired: boolean): withdraws a kind from use, or brings it back, without touching anybody who holds it
  - upsertSignal(nodeId: string, signalTypeId: string, value: number | null): gives a reaction on a node, or changes one. `null` WITHDRAWS it; a zero is an ordinary value and is stored like any other. Spelling a withdrawal as 0 is what made a 0–100 slider dragged to the bottom indistinguishable from an unanswered one — pass the control's own emitted value straight through (`{ $: 'arg' }`) and both cases are right
  - withdrawSignal(nodeId: string, signalTypeId: string): takes back this agent's reaction of one type on one record. The named form of `upsertSignal(node, type, null)`, for a control that only clears
  - navigateToSpace(spaceId: string, view?: string): navigates to a space — accepts a dataset id or a shared id (sharedUrl without its scheme prefix); pre-loads space templates before switching so the template and data arrive together
  - openRecordRef(ref: string): goes to whatever a record reference names — the space, and the record's own page within it. Takes the whole `we:…` reference rather than its parts, so nothing outside the host restates where a record's page lives. A reference naming only a dataset opens the space; a relative one (`we:./…`) resolves against the space on screen; a person has no page, so nothing happens
  - canAdministerSpace(uuid: string): whether this agent may change what every member of that space sees — true for a personal space, and for a shared one they authored. A UI affordance for deciding whether to offer the controls, NOT enforcement: a shared space is a neighbourhood every member can write to. Ask by name rather than comparing author to me.did, so the answer can grow (multiple admins, roles) without every template changing
  - copyShareLink(uuid: string): copies that space's share link to the clipboard, with a toast either way. No-op for a personal space, which has no global id and so no shareable link — read `spaceList[].shareLink` to decide whether to offer the control at all
  - copyGuestLink(uuid: string): copies that space's guest invite link — a URL that creates an account on the space's host and joins, with no sign-up and no download. Empty, and the control hidden, unless BOTH this app's origin and the node's URL are addresses a recipient could reach: a loopback address on either half resolves to the reader's own machine. Read `spaceList[].guestLink` to decide whether to offer it; `shareLink` is the one for somebody who already has WE
  - getSubgroupMessages(subgroupId: string): messages belonging to one of Flux's conversation subgroups, fetched on demand. A dialect query against a foreign schema rather than a WE model, so it goes through the backend's interop surface instead of $query — which is why it is a store method and not a relation you can drill into
  - exportCallTranscript(callId: string): writes the call's transcript to a .txt file (one line per utterance: name, timestamp, text) and downloads it. Read-only and client-side — it reads the shared record and writes to the caller's own device
  - exportExtractionLog(callId: string): writes everything extraction did with the call to a Markdown file and downloads it — the settings it ran under, the transcript once, every member's passes with their prompts and responses verbatim, the records written as they are stored now, and the suggestions still awaiting a decision. For handing to a person or a model investigating the extraction. Read-only and client-side, like exportCallTranscript
  - removeSpaceFromGlobal(spaceUuid: string): withdraws a space's listing from the global discovery space, leaving the space itself alone. Only its author may; removeSpace does this for you

TemplateStore:
- State:
  - personalTemplates: array of TemplateSchema objects — core templates plus user's installed custom templates (excludes space templates)
  - spaceTemplates: array of TemplateSchema objects — templates loaded from the current space
  - builtInTemplates: array of TemplateSchema objects — built-in system templates (always available)
  - myTemplates: array of TemplateSchema objects — user's installed custom templates only (excludes built-in and space templates)
  - allTemplates: array of TemplateSchema objects — union of built-in + personal + space templates
  - templateManagementList: TemplateManagementItem[] — flat list of all templates with management metadata (id, name, icon, description, isBuiltIn, isInstalled, isDefault)
  - refusedTemplates: RefusedTemplate[] — templates in this agent's library that no longer validate, so they cannot be loaded (id, name, icon, reason). `reason` is the validator's first complaint with where it is. Listed so they can be seen and deleted; they are in no other list. `id` is the record's own, for deleteRefusedTemplate
  - switcherGroups: TemplateSwitcherGroup[] — pre-grouped flat items for the template switcher UI; each group has { label: string, items: { id, name, icon, editable }[] }. Groups: "Space templates", "My templates", "Built-in". Use filter(group.items, { name: { contains: local.search } }) for search since items have a flat name field. `editable` says whether editing THAT row would open a session that can be saved — gate a per-row edit control on it rather than on editorStore.isReadOnly, which answers for whichever template is currently rendered and so gives every row the same verdict.
  - currentSwitcherId: string — the id the template switcher should show as selected. The switcher's own spelling of the current template: it differs from currentTemplate.id while a space override or a preview is in effect
  - currentTemplate: TemplateSchema (the active template)
  - loading: boolean — the template lists are still being read. Gate empty states on it
  - defaultTemplateId: string — id of the agent's preferred default template, used where no space or override decides. Persisted to AgentSettings.defaultTemplateId
  - pendingInstall: the template an install dialog is showing ({ marketplaceId, destination, name, icon, version, capabilities, blocked }), or null when none is open. `capabilities` is already in the words a person reads. Host chrome renders it: a dialog vouching for a template must not be drawn by a template
  - safeMode: { on, reason, template } — whether this tab is in safe mode, where WE's own templates and themes are drawn in place of the chosen ones. reason is 'asked' (the ?safe address, the key or the menu) or 'unfinished-render' (a template did not finish loading last time — template is its id). Decided before anything rendered; fixed for the page
  - operationLoading: string | null — the id of the template operation in flight, namespaced by kind ('marketplace-install:<id>', 'space-install:<id>'), or null. A key rather than a boolean so one row's spinner does not appear on every row
- Actions:
  - switchTemplate(newTemplateId: string): switches to another template
  - removeTemplate(): removes the current template
  - deleteTemplate(templateId: string): permanently deletes a custom template from the library
  - deleteRefusedTemplate(id: string): permanently deletes a library template that could not be loaded, by its refusedTemplates id
  - installTemplate(templateId: string): marks an installed custom template visible in the pickers
  - uninstallTemplate(templateId: string): hides a custom template from the pickers without deleting it. The counterpart of installTemplate
  - installFromMarketplace(marketplaceTemplateId: string): copies a marketplace template into your own library. A personal act — use installToSpace to give the community a template. Asks first: the template is fetched and inspected, and the host raises a dialog naming what it will be able to do. Nothing is written until that is confirmed, so treat this as "start an install", not "install"
  - installToSpace(marketplaceTemplateId: string): copies a marketplace template into the current space, so every member of that community gets it — as opposed to installing it for yourself. Asks first, exactly as installFromMarketplace does. Pair with templateStore.operationLoading to show progress on the row being installed
  - confirmInstall(): installs what the dialog is showing. Host chrome only, for the same reason pendingInstall is: a template able to call this is the disclosure being skipped
  - cancelInstall(): closes the install dialog without installing
  - toggleInstalled(templateId: string): installs or uninstalls by id — what the settings list’s switch calls. Prefer installTemplate/uninstallTemplate where the switch can pass its value
  - setDefaultTemplate(templateId: string): sets the agent's preferred default template (persists to AgentSettings.defaultTemplateId)
  - saveTemplate(name: string): saves the current template
  - saveTemplateAs(schema: TemplateSchema, destination?: 'root' | 'space'): saves a schema as a new template in your library or in the current space. Resolves true on success. The editor's fork path; prefer editorStore.startFork from chrome
  - publishToSpace(perspectiveUuid: string, spaceName: string): copies the current template into that space, so its members get it. Resolves true on success
  - deleteMarketplaceTemplate(templateId: string): removes a template this agent published from the marketplace. Only its author may
  - publishToMarketplace(options: { name, description, icon?, themeId?, slug?, screenshots: File[] }): publishes the current template to the marketplace under those details. Resolves true on success
  - refreshSpaceTemplates(): re-reads the current space's templates. The list follows the space on its own; call this after a publish the subscription might have missed
  - leaveSafeMode(): leaves safe mode and reloads with the templates and themes that were chosen

ThemeStore:
- State:
  - builtInThemes: array of ThemeData objects — built-in registry themes (origin: "built-in", always available)
  - automaticThemes: array of ThemeData objects — modes that *resolve to* a theme rather than being one, currently just "Follow system". Listed separately because they carry no parameters: the id is answered at the point of use (by asking the OS) and resolves to one of the built-ins. Render them under their own heading, after the themes
  - installedThemes: array of ThemeData objects — user-installed themes from the root dataset (origin: "custom" | "marketplace")
  - spaceThemes: array of ThemeData objects — themes stored in the current space (origin: "custom")
  - allThemes: array of ThemeData objects — union of builtInThemes + visible installedThemes + spaceThemes (hidden themes filtered out)
  - currentThemeId: string — id of the currently active theme
  - currentTheme: ThemeData — the currently active theme object (id, name, icon, origin)
  - defaultThemeId: string — id of the user's preferred default theme (used for bootscreen, shell, and future space-override). Persisted to AgentSettings.defaultThemeId
  - themeManagementList: ThemeManagementItem[] — flat list of all themes (built-in + all custom) with management metadata (id, name, icon, isBuiltIn, isInstalled, isDefault)
  - editingTheme: EditingTheme | null — the theme being edited (id, name, icon, overrides, css, basePreset) or null when no theme editing session is open. Its non-nullness is what mounts the theme editor
  - operationLoading: string | null — the id of the theme operation currently in flight, namespaced by kind (e.g. 'marketplace-install:<themeId>'), or null when idle. A key rather than a boolean so one row's spinner does not appear on every row — compare it against the row you are rendering
  - focusedRole: string — the kebab-case role the theme editor should scroll to ('surface-sunken'), or empty. Set by whatever sent somebody to the panel — the inspector's role readout — and re-announced on every set, so pressing the same chip twice scrolls twice
  - systemThemes: { light, dark, resolved } — which two themes 'Follow system' chooses between. light/dark are the ids as chosen, empty for a side left at the built-in; resolved is 'light' | 'dark', whichever the OS is asking for now
  - systemThemeOptions: { label, value }[] — options for either side of the Follow-system pair, with a "Built-in" entry a schema could not prepend itself
  - themeScope: 'global' | 'scoped' — what actually applies right now: the theme editor's session preview if one is active, else the agent's preference
  - themeScopePreference: 'global' | 'scoped' — the agent's persisted choice
  - themeScopeGlobal: boolean — the preference as a boolean, for a switch to bind to
  - themeScopePreviewing: boolean — a theme being edited is previewing a different scope, so the preference is temporarily masked. Worth saying so beside the setting
  - templateThemePending: boolean — the template's suggested theme cannot be resolved yet and might still arrive. Hold what is on screen rather than painting a fallback while it is true
  - useTemplateTheme: boolean — whether a template may bring the theme it was designed for (meta.themeId). Defaults on; one condition in the resolver rather than a setting to unwind, so turning it off restores whatever would otherwise apply immediately
  - activeTemplateTheme: ThemeData | null — the theme the scoped template wrapper renders: the theme being edited if there is one, else the space's. Null in global mode, where the template inherits the document's theme
- Actions:
  - setCurrentTheme(themeId: string): sets and persists the active theme
  - setDefaultTheme(themeId: string): sets the preferred default theme (persists to AgentSettings.defaultThemeId)
  - focusRole(role: string): asks the theme editor to reveal a role, kebab-case as a schema spells it. Pair with editorStore.openThemePanel so there is a panel to scroll
  - setSystemTheme(polarity: 'light' | 'dark', themeId: string): sets one side of the Follow-system pair. An empty id returns that side to the built-in
  - setThemeInstalled(themeId: string, visible: boolean): shows or hides a custom theme in the pickers; does not delete it. Takes the value rather than toggling, so a `we-switch` can pass `event.detail` straight through
  - previewThemeScope(scope: 'global' | 'scoped' | null): previews a scope for the current theme-editing session without writing the preference; null drops the preview. Cleared when editing ends
  - setThemeScopeGlobal(global: boolean): persists whether a space's theme covers the whole window (true) or only the space's own content (false, the default). Takes a boolean because a switch emits one; an expression over event in the args is evaluated when the switch fires, so pass `event.detail` bare
  - setUseTemplateTheme(enabled: boolean): persists whether templates may bring their own theme. Boolean, so a switch can pass `event.detail` bare
  - startEditing(themeId?: string): opens a theme editing session on that theme, or on the current one. Prefer editorStore.enterThemeEditing, which also opens the panel
  - changeBasePreset(preset: string | undefined): while editing, swaps the base preset the theme builds on — takes its polarity and lightness range and repopulates the controls from the preset's computed CSS
  - updateEditingOverrides(overrides: Partial<ThemeOverrides>): while editing, merges parameter changes (hues, saturation, lightness range, role pins) into the draft. Applied live
  - updateEditingCss(css: string): while editing, replaces the draft’s raw CSS layer. Applied live
  - updateEditingMeta(fields: { name?, icon? }): while editing, renames or re-icons the draft
  - cancelEditing(): ends the editing session and discards the draft, restoring what was applied before. Note the theme *panel* autosaves on unmount, so closing the panel keeps the draft — this is the explicit throw-away, and the only path that does
  - createAndStartEditing(name: string, icon: string, sourceId?: string, destination?: 'personal' | 'space'): creates a new theme — copied from sourceId when given — and opens an editing session on it. Resolves true on success
  - saveEditingTheme(): writes the draft over the theme being edited and keeps editing. Resolves to the saved theme, or null when nothing was being edited
  - saveEditingThemeAs(name: string, icon: string): writes the draft as a new theme under that name, leaving the original untouched
  - deleteTheme(themeId: string): permanently deletes a custom theme
  - installFromMarketplace(marketplaceThemeId: string): installs a marketplace theme into your own library (installedThemes). A personal act — use installToSpace to give the community a theme
  - installToSpace(marketplaceThemeId: string): copies a marketplace theme into the current space, so every member of that community gets it. The counterpart to templateStore.installToSpace. Pair with themeStore.operationLoading to show progress on the row being installed
  - uninstallTheme(themeId: string): removes an installed theme (deletes the model)
  - deleteMarketplaceTheme(themeId: string): removes a theme this agent published from the marketplace. Only its author may
  - publishToMarketplace(options: { name, description, icon?, slug?, screenshots: File[] }): publishes the current theme to the marketplace under those details. Resolves true on success
  - publishToSpace(perspectiveUuid: string, spaceName: string): copies the current theme into that space, so its members get it. Resolves true on success
  - refreshSpaceThemes(): re-reads the current space's themes. The list follows the space on its own; call this after a publish the subscription might have missed

Record:
- State:
- Actions:
  - create(entity: string, fields: object, options?: { dataset?: string }): creates a record in the current space, or in the dataset a store path names ('datasetStore.rootDataset' for we-root entities, 'datasetStore.personalDataset' for the agent's own content). See "Record mutations via $action" above
  - update(entity: string, id: string, fields: object, options?: { dataset?: string }): updates the named fields of one record, leaving the rest
  - delete(entity: string, id: string, options?: { dataset?: string }): deletes one record. Irreversible

Clipboard:
- State:
- Actions:
  - copy(text, what?: string): copies text to the clipboard and confirms with a toast — '<what> copied', or 'Text copied'. A non-string is copied as JSON. For a copy button beside something long: a prompt, a log, an id. Host chrome only (the `clipboard` capability) — a space template's bag does not have it

---

## Feature Modules

The modules this deployment ships. A module publishes a store at `modules.<id>` (public members only),
parts a template places with `{ "type": "$part", "props": { "id": "<id>.<part>" } }`, panels a
template places or supplies through `meta.panels` (`{ "module": "<id>", "dock": "<panel>" }`), and
functions expressions call like the host functions above. A template that reaches a module by name
declares it: `meta.requires.modules: ["<id>"]`. Reading `{ "$": "modules.<id>" }` bare is how a template
depends on a module that may not be installed.

### Calls (`call`)
Audio, video and screen share with the people in a space.
Needs: kernels records, presence, ephemeral, media, peerConnection; permissions microphone, camera, screen-share.
- State (read in an expression as `modules.call.<name>`):
  - active — Whether this agent is in a call right now.
  - arrangement — The { columns, rows } the stage is currently laid out in.
  - audioDevice — The microphone this agent has chosen, or empty for whatever the system offers.
  - callId — The id of the call this agent is in, or null between calls.
  - callRecordId — The id of the call record this agent's call writes into — what a transcript, a board or a call's page follows — or empty between calls.
  - callSpace — The space the call is in as { uri, name, avatar } — name and avatar empty until the host knows them — or null between calls.
  - cameraOptions — The cameras as picker options, on the same terms as microphoneOptions.
  - cameras — The cameras this machine has, on the same terms as microphones.
  - canCall — Whether a call could be started here — false in a personal space, which has nobody to call.
  - deviceSettingsOpen — Whether the camera and microphone chooser is open.
  - devicesNamed — Whether this machine will say what its devices are called. False until capture has been allowed once.
  - devicesProbed — Whether this machine has been asked for a device yet. Until it has, an empty device list means "not allowed to look", not "none here".
  - elsewhere — Whether the call this agent is in belongs to a space other than the one on screen.
  - focusedId — Whose tile the stage is giving most of its room to, or null for an even grid.
  - liveCalls — Every call running in the space on screen, whichever this agent is in — { id, recordId, anchorNodeId, peers, faces, count, mine, label } per call.
  - media — This agent's own { audioEnabled, videoEnabled, screenShareEnabled } — what the mute, camera and share toggles reflect.
  - microphoneOptions — The microphones as picker options, "System default" first — ready for a we-select.
  - microphones — The microphones this machine has — { deviceId, label, groupId } each. A label is empty until capture has been allowed once.
  - ongoing — Everyone in any call in the space on screen, as avatar faces { image, hash, initials, did }, whether or not this agent has joined.
  - problem — Why the call could not start or a device could not be reached, as a sentence to show, or null.
  - solo — Whether the spotlight has the stage to itself, with everyone else hidden.
  - tiles — One entry per participant in the call — { id, did, stream, isSelf } — changing only when somebody joins, leaves or their stream changes.
  - tileStates — Each participant's volatile flags by id — muted, camera, screen, connection, focused, hasPicture, plus retrying, attempts and transport for how the connection is faring — looked up with find() so a tile never remounts.
  - videoDevice — The camera this agent has chosen, or empty for whatever the system offers.
- Actions (`{ "$action": "modules.call.<name>" }`):
  - attachAnchor — Make the running call about the record whose id is given, without rejoining it.
  - closeDeviceSettings — Close the camera and microphone chooser.
  - continueCall — Pick a past call back up by its record id, joining anyone already in it and writing no new record.
  - dismissProblem — Dismiss the problem message.
  - focusTile — Give the participant with this id the spotlight, or take it back if they already have it.
  - goToCall — Go to the call: join the one running here, pick up the one on screen, or start one; in a call already, bring it up.
  - joinAnchoredCall — Join the call already happening about the record whose id is given, or start one about it.
  - joinCall — Join a running call by its id, as liveCalls lists it, leaving any call this agent is in.
  - leave — Leave the call, releasing the camera, the microphone and every connection.
  - nameDevices — Ask for a device once so this machine will say what its hardware is called.
  - openDeviceSettings — Open the camera and microphone chooser.
  - reconnectPeer — Build one peer's connection again from scratch, without leaving the call.
  - refreshDevices — Re-read which microphones and cameras this machine has.
  - returnToCall — Go back to the space the call is in; does nothing outside a call.
  - setArrangement — Report the { columns, rows } a stage grid settled on, so fit-to-content can solve for it.
  - setDevice — Use a different microphone or camera; an empty id means whatever the system offers.
  - startCall — Start a new call in the space on screen, optionally about the record whose id is given; resolves once joined.
  - toggleAudio — Mute or unmute this agent’s microphone.
  - toggleScreenShare — Start or stop sharing this agent’s screen; sharing replaces the camera until it stops.
  - toggleSolo — Hide everyone but the spotlight, or bring them back; does nothing while nobody is focused.
  - toggleVideo — Turn this agent’s camera on or off, reporting through problem when it is refused.
- Parts: `call.anchoredCallButton`, `call.continueCallButton`, `call.deviceSettings`, `call.startCallButton`, `call.tile`
- Panels (`meta.panels[].dock`): `stage` "Call" (module-owned openness)
- Settings: `iceServers` (string; deployment, space, agent) — ICE servers
- Presence activities: `call` { id: string, anchor: object, media: object, record: string, continued: boolean }

### Transcription (`transcribe`)
Turns what is said in a call into text blocks in the space.
Needs: kernels records, presence, media, transcription, interpretation; permissions microphone.
- State (read in an expression as `modules.transcribe.<name>`):
  - autoExtract — Whether this call is extracted as it happens — its participants’ answer, else the space’s.
  - autoJoined — Recording was started by the call rather than by this agent pressing record.
  - available — There is audio to listen to — a microphone the host is capturing.
  - callAgents — Everyone in this call, recording or not — the denominator of coverage; empty outside a call.
  - callId — The record extraction decisions for this call are written against — the call’s own record from its first second.
  - callOnScreenLive — Somebody is in the call the address names right now.
  - canEditProposals — Whether an edited suggestion can be written back on accept.
  - canInstallModel — Whether this connection may install the model the backend offers.
  - changedIds — Agreed records carrying a suggested change, by id.
  - collectionId — The record this call’s transcript lives in, or null until something has been said.
  - editingProposal — The suggestion open for editing, or empty when none is.
  - enabled — Whether this agent is recording their own microphone into the call.
  - error — Why the session stopped, when status is error; empty otherwise.
  - extractable — Whether this node can interpret at all — false when it has no language model.
  - extractCount — How many records the last pass wrote.
  - extractedId — The collection the last finished pass ran on, or empty.
  - extractError — Why the last pass failed; empty otherwise.
  - extractingId — The collection a pass is running on right now, or empty.
  - extractionFor — What one call can extract, by record id — { targets, canChoose, canExtract }, read as extractionFor[id].
  - extractionOpen — Whether the extraction panel is open.
  - extractStatus — How the last one-shot extraction pass went — idle, running, done or error.
  - extractTurns — How many transcript turns the last pass read.
  - heard — Something has been said that the record does not hold yet — buffered, being written or still with the model.
  - inCall — Whether this agent is in a call right now.
  - installError — Why the last model install failed; empty otherwise.
  - installingModel — A one-click model install is registering its model.
  - installModelLabel — The install button’s words, naming the offered model and its size; empty when none is offered.
  - invited — Somebody else in this call is recording and this agent is not, having not opted out.
  - invitedBy — The agent id of the first peer recording this call, or empty when none is.
  - level — Microphone loudness as the voice detector measures it, 0–1.
  - levelPercent — The microphone level as a CSS width for a meter.
  - listening — True only while actually transcribing — what a record button highlights on.
  - liveCollectionId — The record the call this agent is in is writing into, or empty when there is none.
  - modelDownloading — A transcription model is installed and its weights are still arriving.
  - modelDownloadText — The download line, ready to show — "Downloading the speech model — 45%".
  - modelMissing — No transcription model is installed on this node, as last read.
  - open — Whether the transcript panel is open.
  - partialCoverage — Someone in this call is not being transcribed.
  - passRunning — Whether any extraction pass is running right now, this node’s or a peer’s.
  - pending — Words heard that are not yet a row in the transcript — buffered or being written, newest last.
  - pendingIds — Every record still awaiting a decision, by id, across every call asked about.
  - pendingProposals — The same suggestions as rows — { id, kind, entity, fields, summary }.
  - proposalDraft — What has been typed into the open suggestion, keyed by property name.
  - proposals — Suggestions staged on the live call — prefer proposalsFor with the call named.
  - proposalsFor — Suggestions staged on one conversation, by record id — read as proposalsFor[id].
  - reconnecting — The link to the speech model dropped and is being re-established; what is said meanwhile is held.
  - speaking — Whether the microphone level currently counts as speech.
  - status — What the session is doing — idle, no-backend, no-model, no-audio, downloading, starting, listening or error.
  - thresholdPercent — The speech-onset threshold as a CSS width, to mark on the same meter.
  - tiedBusy — Whether a confirmed tied decision is still being written.
  - tiedDecision — A decision waiting on confirmation because it decides others too — { kind, title, body, detail, confirmLabel } — or null.
  - transcribers — Everyone recording this call, this agent included — the numerator of coverage.
  - transcribing — Speech has gone to the model and its text has not come back yet.
  - transcriptFromStart — Whether the transcript is being read from its beginning rather than following the live end.
  - transcriptShown — How many transcript lines are loaded right now.
  - unconfirmedIds — Records a pass made that nobody has kept yet, by id.
  - watchProblem — Why the standing extraction watch is not running here; empty when it is.
- Actions (`{ "$action": "modules.transcribe.<name>" }`):
  - acceptProposal — Keeps a suggestion, as proposed or as edited.
  - addMessage — Writes something a person typed into a transcript, as a typed line.
  - applyChange — Applies one suggested change to an agreed record.
  - cancelProposalEdit — Closes the open draft, discarding what was typed.
  - cancelTiedDecision — Puts the decision waiting in tiedDecision down without making it.
  - closeExtractionPanel — Closes the extraction panel.
  - closePanel — Closes the transcript panel.
  - confirmTiedDecision — Carries out the decision waiting in tiedDecision, with everything tied to it.
  - dismissChange — Dismisses one suggested change, leaving the record as it was.
  - editProposal — Opens one suggestion for editing, seeded with what the model proposed.
  - editUtterance — Corrects the words on a line of the transcript, marking a spoken line as corrected.
  - extract — Runs one extraction pass over the call this agent is transcribing.
  - extractCollection — Runs one extraction pass over any call’s record, by id.
  - flushNow — Writes what has been heard so far without waiting for the buffer to fill.
  - installModel — Installs the model the backend offers and resumes recording that was waiting on one.
  - openExtractionPanel — Opens the extraction panel.
  - openPanel — Opens the transcript panel.
  - readTranscriptFromStart — Shows the beginning of the transcript, to be read forwards.
  - readTranscriptLive — Goes back to following the end of the transcript.
  - refreshProposals — Re-reads what is staged on a call, or on the live one.
  - rejectProposal — Drops a suggestion.
  - setProposalField — Sets one field of the open draft, by property name.
  - showMoreTranscript — Loads one more page of the transcript, in whichever direction it is being read.
  - toggle — Starts or stops recording this agent’s microphone into the call, and opens the transcript when starting.
  - toggleAutoExtract — Turns automatic extraction on or off for this call, for everyone in it.
  - toggleExtractionTarget — Includes or excludes one model from what a call extracts, for everyone in it; defaults to the live call.
- Parts: `transcribe.transcriptFeed` (subject: routeStore.params.call ? routeStore.params.call : modules.transcribe.collectionId), `transcribe.transcriptLines` (subject: modules.transcribe.collectionId), `transcribe.transcriptComposer`, `transcribe.captureMeter`, `transcribe.captureStatus`, `transcribe.coverage`, `transcribe.extractionTargets`, `transcribe.pendingUtterance`
- Panels (`meta.panels[].dock`): `transcript` "Transcript" (module-owned openness), `extraction` "Extraction" (module-owned openness)
- Settings: `recordCalls` (boolean; deployment, agent, space, agent-in-space) — Record calls automatically
- Presence activities: `transcribe` { id: string, recording: boolean, anchor: object, collection: string }

### Live presence (`live`)
See each other’s cursors, and follow one person’s screen.
Needs: kernels presence, ephemeral, view.
- State (read in an expression as `modules.live.<name>`):
  - canDrive — Whether taking the wheel is possible here.
  - canFollow — Whether somebody else is driving, so this agent could follow them.
  - canShareCursors — Whether live cursors are possible here — false in a space with no transport, or where they are switched off.
  - canTakeWheel — Whether the wheel is free to take, or already this agent’s.
  - cursorsOn — Whether this agent’s pointer is shared, and other people’s shown.
  - driverName — The name of whoever is driving, or empty when nobody is.
  - driving — Whether this agent has the wheel.
  - faces — One entry per cursor on screen — { did, name, image }.
  - following — Whether this agent is following somebody’s screen.
  - followingName — The name of whoever this agent is following.
  - problem — Why something could not be done, as a sentence to show, or empty.
  - watching — How many other people here have live cursors on.
- Actions (`{ "$action": "modules.live.<name>" }`):
  - dismissProblem — Dismiss the problem message.
  - follow — Follow whoever has the wheel.
  - releaseWheel — Give up the wheel.
  - takeWheel — Take the wheel, so anybody who opts in follows this screen.
  - toggleCursors — Share this agent’s pointer and show other people’s, or stop.
  - toggleFollow — Follow whoever has the wheel, or stop — whichever this press means.
  - toggleWheel — Take the wheel, or give it up — whichever this press means.
  - unfollow — Stop following.
- Parts: `live.cursorToggle`, `live.wheelButton`, `live.driverStrip`
- Settings: `cursors` (boolean; deployment, space, agent-in-space) — Live cursors; `driving` (boolean; deployment, space) — Driving
- Presence activities: `live` { cursors: boolean }; `driving` { since: number }; `following` { id: string }

### Pocket (`pocket`) — the agent’s, not a space’s
Keep things from any space — posts, people, spaces — in a panel that follows you.
Needs: kernels agentData.
- State (read in an expression as `modules.pocket.<name>`):
  - open — Whether the Pocket panel is open.
- Actions (`{ "$action": "modules.pocket.<name>" }`):
  - close — Closes the Pocket panel.
  - show — Opens the Pocket panel and resolves the folder it was last looking at.
  - toggle — Opens the Pocket panel, or closes it if it is open.
- Parts: `pocket.toggleButton`
- Panels (`meta.panels[].dock`): `main` "Pocket" (module-owned openness)
- Entities (queryable with $query):
  - PocketFolder: name: string, icon: string, color: string, root: boolean, createdOrder: number; relations folders: HasMany → PocketFolder, items: HasMany → PocketItem
  - PocketItem: ref: string (required), entity: string, datasetKey: string, recordId: string, withinEntity: string, withinId: string, label: string, icon: string, thumbnail: string, sourceName: string, sourceAuthor: string, gatheredAt: string, note: string

### Notes (`notes`) — the agent’s, not a space’s
Private notes that follow you between spaces. Share one into a space as a post.
Needs: kernels agentData, records.
- No store: everything this module does is declared.
- Parts: `notes.toggleButton`
- Panels (`meta.panels[].dock`): `main` "Notes"
- Entities (queryable with $query):
  - NoteShare: noteId: string (required), ref: string (required), spaceName: string, sharedAt: string

### Globe (`globe`)
A globe with a modular layer system — data on the earth, borders, the sky — drawn by Cesium or MapLibre.
Needs: permissions network:gibs.earthdata.nasa.gov, network:cesium-ion, network:arcgis.com, network:mapbox.com.
- State (read in an expression as `modules.globe.<name>`):
  - drawsSpace — Whether the globe draws the space around the earth — the skybox, stars and solar system. False on MapLibre.
  - engine — Which engine draws the globe here — "cesium" or "maplibre" — from the setting and this device.
- Settings: `engine` (enum; deployment, agent) — Globe engine; `imagery` (enum; deployment, agent) — Globe imagery; `ionAccessToken` (string; deployment, agent) — Cesium ion access token; `esriApiKey` (string; deployment, agent) — Esri API key; `mapboxAccessToken` (string; deployment, agent) — Mapbox access token
- Components: CesiumGlobe

### Graph (`graph`)
A general-purpose graph engine — knowledge maps, schema maps, hierarchies and diagrams, with pluggable expanders, layouts and behaviours.
- No store: everything this module does is declared.
- Parts: `graph.schemaMap`, `graph.contentTree`, `graph.staticDiagram`, `graph.knowledgeMapPosts`
- Components: GraphView

### Polls (`polls`)
Ask the space a question and watch the answer arrive.
Needs: kernels records.
- State (read in an expression as `modules.polls.<name>`):
  - lastError — Why the last vote could not be recorded, or empty.
  - pendingVote — This agent’s vote on a poll, written and not yet read back — { author, option }, or nothing. Keyed by poll id.
  - revealBeforeVoting — Whether a poll shows its counts before this agent has voted — the community’s setting here.
  - voting — The id of the poll a vote is being written for, or empty.
- Actions (`{ "$action": "modules.polls.<name>" }`):
  - vote — Casts this agent’s vote on a poll, or changes it — one vote per person per poll.
- Parts: `polls.pollCard`, `polls.pollComposer`
- Settings: `revealBeforeVoting` (boolean; space) — Show counts before voting
- Functions:
  - tally(options) — Votes counted per choice — { option, count, share, leading }[] — one row per choice the poll offers, in its order, plus a row for any choice a vote names that the poll no longer does. Options: votes (a Vote query), options (the poll’s comma-separated choices), pending (modules.polls.pendingVote[<poll id>] — this agent’s vote written and not yet read back, counted in place of their stored one so the bars move on the press).  e.g. tally({ votes: local.votes, options: block.options, pending: modules.polls.pendingVote[block.id] })
- Views (sections a space enables): `polls` "Polls" at /polls
- Blocks: Poll (`_type: "poll"`, drawn by `polls.pollCard`)
- Entities (queryable with $query):
  - Poll extends WeNode: question: string (required), options: string (required), closed: boolean, version: number
  - Vote: pollId: string (required), option: string (required)

---

## Store Usage Patterns

Reading state — an expression naming the store:
{ "$": "storeName.property" }
Example: { "$": "routeStore.currentPath" }

Calling actions:
{ "$action": "storeName.method", "args": [...] }
Example: { "$action": "routeStore.navigate", "args": ["/home"] }

Feature-module stores:
{ "$": "modules.<moduleId>.<member>" } and { "$action": "modules.<moduleId>.<action>" }
Each feature module this deployment ships publishes its PUBLIC store members under its own id —
modules.call.active, modules.transcribe.proposals, modules.polls.vote. The modules, their members,
parts, panels, settings and functions are listed in the Feature Modules section below, and the
validator checks every modules.* reference against it: a member a module did not mark public is as
unknown as one it never had. { "$": "modules.<moduleId>" } as a bare condition is the way to depend
on an optional module — it resolves to nothing where the module is not installed.

Iterating over store data:
{
  "type": "$each",
  "props": { "items": { "$": "spaceStore.personalSpaces" }, "as": "space" },
  "children": [
    {
      "type": "we-button",
      "props": {
        "variant": "ghost",
        "onClick": { "$action": "routeStore.navigate", "args": [{ "$": "`/space/${space.uuid}`" }] }
      },
      "children": [
        { "type": "we-avatar", "props": { "image": { "$": "space.avatar" }, "hash": { "$": "space.uuid" }, "initials": { "$": "space.name" }, "size": "sm" } },
        { "type": "we-text", "children": [{ "$": "space.name" }] }
      ]
    }
  ]
}

Conditional rendering from store:
{
  "type": "$if",
  "props": {
    "condition": { "$": "routeStore.currentPath == '/'" },
    "then": { "type": "we-text", "children": ["Home"] },
    "else": { "type": "we-text", "children": ["Not home"] }
  }
}

Deriving options from store:
{ "$": "templateStore.templates.map(t, { name: t.meta.name, icon: t.meta.icon })" }

Querying model data:
{
  "$query": { "entity": "TaskBlock", "where": { "status": "todo" } }
}

Eager-loading relations with include (most common relational pattern):
When you need related data displayed alongside a list, use include to hydrate relations in one query.

Example — Channel list with conversation count and latest conversation:
{
  "type": "$each",
  "props": {
    "items": {
      "$query": {
        "entity": "Channel",
        "dataset": { "$": "currentDataset" },
        "include": {
          "$conversationCount": { "from": "conversations", "count": true },
          "$latestConversation": { "from": "conversations", "order": { "createdAt": "desc" }, "limit": 1 }
        }
      }
    },
    "as": "channel"
  },
  "children": [{
    "type": "Row",
    "children": [
      { "type": "we-text", "children": [{ "$": "channel.name" }] },
      { "type": "we-text", "children": [{ "$": "channel.$conversationCount" }] }
    ]
  }]
}

Example — Nested include (Conversations with their messages):
{
  "$query": {
    "entity": "Conversation",
    "dataset": { "$": "currentDataset" },
    "include": {
      "messages": {
        "order": { "createdAt": "desc" },
        "limit": 20
      }
    }
  }
}
Each conversation in the result has a messages array of hydrated Message instances.
Nesting works to any depth: "include": { "messages": { "include": { "reactions": true } } }
— with two limits, listed under "Nested include" in the operators section: no $-projections below the
top level, and no untyped relation nested below another.

Relational drill-down (master-detail navigation across entity relations):
Use routes + a $query `scope` when you navigate to a detail route and need only that record's children.
scope.anchor is the parent entity type; scope.via is its HasMany relation (see externalEntities) whose targets
are the query's entity; scope.anchorId is the parent record's id. The adapter resolves the relation to a
backend handle, so no protocol details live in the template.
routeStore.segments.N extracts the Nth dynamic path segment (segments splits currentPath by "/").

Example — Channel list → Conversation list:
{
  "routes": [
    {
      "path": "/",
      "type": "Column",
      "props": { "gap": "300", "p": "400" },
      "children": [{
        "type": "$each",
        "props": {
          "items": { "$query": { "entity": "Channel", "dataset": { "$": "currentDataset" } } },
          "as": "channel"
        },
        "children": [{
          "type": "we-button",
          "props": {
            "variant": "ghost",
            "onClick": { "$action": "routeStore.navigate", "args": [{ "$": "`/channels/${channel.id}`" }] }
          },
          "children": [{ "$": "channel.name" }]
        }]
      }]
    },
    {
      "path": "/channels/:channelId",
      "type": "Column",
      "props": { "gap": "300", "p": "400" },
      "children": [{
        "type": "$each",
        "props": {
          "items": {
            "$query": {
              "entity": "Conversation",
              "scope": { "anchor": "Channel", "via": "conversations", "anchorId": { "$": "routeStore.segments[1]" } },
              "dataset": { "$": "currentDataset" }
            }
          },
          "as": "convo"
        },
        "children": [{
          "type": "we-text",
          "children": [{ "$": "convo.conversationName" }]
        }]
      }]
    }
  ]
}
Notes:
- Use include when you need related data displayed inline (e.g. a post with its comments, a channel with its conversation count).
- Use a scope drill-down when you're on a detail route and want only children belonging to the current record.
- dataset must point to the dataset that holds the data. For external apps (e.g. Flux) opened as a WE space, use { "$": "currentDataset" }.
- The relation name (in include, or scope.via) is the HasMany field name on the parent entity.

Local state (form with validation):
{
  "type": "Column",
  "$localState": {
    "name": {
      "type": "string",
      "initial": "",
      "validate": [{ "rule": "required" }, { "rule": "minLength", "value": 2 }]
    },
    "loading": { "type": "boolean", "initial": false }
  },
  "children": [
    {
      "type": "we-form-field",
      "props": { "label": "Name", "error": { "$": "error('name')" } },
      "children": [{
        "type": "we-input",
        "props": {
          "value": { "$": "local.name" },
          "onInput": { "$setLocal": "name", "value": { "$": "event.detail" } }
        }
      }]
    },
    {
      "type": "we-button",
      "props": {
        "text": "Submit",
        "loading": { "$": "local.loading" },
        "disabled": { "$": "local.loading" },
        "onClick": [
          { "$touch": "$all" },
          { "$if": { "condition": { "$": "formValid()" }, "then": { "$action": "myStore.submit", "args": [{ "$": "local.name" }] } } }
        ]
      }
    }
  ]
}
The button is disabled only while the submit is in flight. Disabling it on { "$": "!formValid()" }
instead contradicts the { "$touch": "$all" } beneath it — the button is unclickable in exactly the state that
guard exists to report. See the "Typical form pattern" section for the full rationale and the two valid shapes.

Repeating lists with $each:
ALWAYS use $each for lists of similar items — never duplicate the same node structure.
Write the template once; $each renders it for each item.

Use literal arrays for fixed/sample data:
{
  "type": "$each",
  "props": {
    "items": [
      { "title": "First Post", "text": "Hello world.", "author": "Alice" },
      { "title": "Second Post", "text": "Another update.", "author": "Bob" }
    ],
    "as": "post"
  },
  "children": [
    {
      "type": "Column",
      "props": { "bg": "surface", "r": "400", "border": "1px solid border", "p": "400", "gap": "300" },
      "children": [
        {
          "type": "Row",
          "props": { "gap": "300", "ay": "center" },
          "children": [
            { "type": "we-avatar", "props": { "initials": { "$": "post.author" }, "hash": { "$": "post.author" }, "size": "sm" } },
            { "type": "we-text", "props": { "variant": "label" }, "children": [{ "$": "post.author" }] }
          ]
        },
        { "type": "we-text", "props": { "variant": "heading-sm" }, "children": [{ "$": "post.title" }] },
        { "type": "we-text", "children": [{ "$": "post.text" }] }
      ]
    }
  ]
}

Use $query or a store read for dynamic data (more common in production):
{ "type": "$each", "props": { "items": { "$query": { "entity": "TextBlock" } }, "as": "post" }, "children": [...] }
{ "type": "$each", "props": { "items": { "$": "spaceStore.posts" }, "as": "post" }, "children": [...] }

Per-item customization inside $each:
To style or highlight specific items, add a data flag to those items and use $if on the flag inside the template. Do NOT use index == N comparisons — they are fragile, repetitive, and break when items are reordered.
Example: add "highlighted": true to one item's data, then use $if on the flag in the template:
{ "type": "$if", "props": { "condition": { "$": "post.highlighted" }, "then": { "type": "we-badge", "props": { "variant": "primary" }, "children": ["Featured"] } } }
For a conditional PROP, use a ternary in an expression — NOT a prop-level $if, which is a node type
and resolves to a handler in a value position:
{ "bg": { "$": "post.highlighted ? 'accent-muted' : 'surface'" } }

Boolean toggle (show/hide, expand/collapse):
{
  "type": "Column",
  "$localState": { "showDetails": { "type": "boolean", "initial": false } },
  "children": [
    { "type": "we-button", "props": { "variant": "ghost", "onClick": { "$toggleLocal": "showDetails" } }, "children": ["Toggle Details"] },
    { "type": "$if", "props": { "condition": { "$": "local.showDetails" }, "then": { "type": "we-text", "children": ["Details content here"] } } }
  ]
}

Signal types (community-specific reactions/votes):
Signal types are created per-community by the user. Never hardcode signal type UUIDs in schemas.
Resolve them by slug from a hoisted $queries subscription on the node.

There is no store accessor for signal types, which is the trap: the community's other vocabularies
DO have one — spaceStore.taskStates, spaceStore.involvementTypes — so the analogy invites a
spaceStore read that does not exist, and a filter on undefined counts the wrong thing silently.
Query the SignalType entity instead, and look the slug up with find().

ALWAYS ask the user: "What slug should I use? (e.g. 'like', 'upvote', 'star')"
Then use that slug in the pattern below.

Pattern — live wired SignalControl (one hoisted query, reused by the projection and the control):
{
  "$queries": { "signalTypes": { "entity": "SignalType", "subscribe": true } },
  "type": "Column",
  "children": [
    {
      "type": "$each",
      "props": {
        "items": {
          "$query": {
            "entity": "MyBlock",
            "include": {
              "signals": true,
              "$totalLikeCount": {
                "from": "signals",
                "where": {
                  "signalTypeId": { "$": "find(local.signalTypes, { slug: 'like' }).id" }
                },
                "count": true
              }
            }
          }
        },
        "as": "item"
      },
      "children": [
        {
          "type": "$if",
          "props": {
            "condition": { "$": "count(local.signalTypes)" },
            "then": {
              "type": "$each",
              "props": { "items": { "$": "local.signalTypes" }, "as": "sig" },
              "children": [
                {
                  "type": "SignalControl",
                  "props": {
                    "signalType": { "$": "sig" },
                    "signals": { "$": "filter(item.signals, { signalTypeId: sig.id })" },
                    "myDid": { "$": "me.did" },
                    "onSignal": { "$action": "spaceStore.upsertSignal", "args": [{ "$": "item.id" }, { "$": "sig.id" }, { "$": "arg" }] }
                  }
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Notes:
- $queries and $localState share one local namespace, so { "$": "local.signalTypes" } reads the
  subscription from any descendant — the projection above and the controls below stay in agreement
  about which type a slug means.
- The count() guard renders nothing until the community has created a signal type.
- Iterating signalTypes renders every type the community defined; use find() with a slug only where
  one specific type is meant (e.g. a like count).
- Replace "like" with the user's slug.
- $query include adds $totalLikeCount as a computed property on each item.
- signalType prop accepts the full SignalType object (provides icon, mode, range to the UI component).

Preview / mockup mode (static, no store wiring):
{
  "type": "SignalControl",
  "props": {
    "preview": true,
    "signalType": { "icon": "❤️", "mode": "toggle", "rangeMin": 0, "rangeMax": 1 }
  }
}
Use preview: true when sketching a layout without real data. Remove it (and add the full wiring above) when going live.

---

## Common Patterns (copy these shapes)

These are the shapes WE's own templates use. Prefer them over inventing a new arrangement — they
carry decisions (loading behaviour, empty states, accessibility) that are easy to omit and hard to
notice missing. Copy the JSON and change the words; every one of them is ordinary nodes you can
then edit freely.

### Empty state — what a list shows when it has nothing to show

**A list must always have one.** An empty `$each` renders nothing at all, so a page with no content
looks identical to a page still loading, and the reader cannot tell which.

```json
{
  "type": "$animate",
  "props": { "enterTransition": { "type": "fade", "duration": 200, "delay": 400 } },
  "children": [
    {
      "type": "Column",
      "props": { "ax": "center", "ay": "center", "gap": "200", "p": "600", "width": "100%" },
      "children": [
        { "type": "we-icon", "props": { "name": "newspaper", "size": "lg", "color": "text-faint" } },
        {
          "type": "we-text",
          "props": { "color": "text-faint", "textAlign": "center" },
          "children": ["This space doesn't have any posts."]
        }
      ]
    }
  ]
}
```

The `$animate` wrapper is not decoration. A query-backed list is empty on its first frame and fills
a moment later, so without the delayed fade the placeholder blinks on every load and states
something false while it does. Drop the wrapper only when emptiness is known synchronously (a store
array, a missing model).

**If the list filters on a search box**, say so instead of claiming the space is empty:

```json
{ "$": "local.searchText ? 'No posts match your search.' : "This space doesn't have any posts."" }
```

### A list with its empty state — hoist the query so the count is readable

```json
{
  "type": "Column",
  "props": { "width": "100%" },
  "$queries": { "postRows": { "entity": "CollectionBlock", "where": { "type": "root" }, "limit": 20 } },
  "children": [
    {
      "type": "$if",
      "props": {
        "condition": { "$": "count(local.postRows)" },
        "then": {
          "type": "Grid",
          "props": { "columns": 1, "gap": "400", "width": "100%" },
          "children": [
            {
              "type": "$each",
              "props": { "items": { "$": "local.postRows" }, "as": "post" },
              "children": [{ "type": "Card", "children": ["…"] }]
            }
          ]
        },
        "else": { "…": "the empty state above" }
      }
    }
  ]
}
```

Hoisting into `$queries` rather than leaving the query on the `$each` is what makes the count
readable from outside the loop, and it means one subscription answers both branches — so the
placeholder and the grid can never disagree about how many rows there are.

### Gate / prompt page — an icon, what this is, and what to do about it

```json
{
  "type": "Column",
  "props": { "flex": "1", "height": "100%", "ax": "center", "ay": "center", "gap": "400", "p": "600" },
  "children": [
    { "type": "we-icon", "props": { "name": "lock", "size": "xl", "gradient": "primary" } },
    { "type": "we-text", "props": { "variant": "heading-md", "textAlign": "center" }, "children": ["Join this Space"] },
    {
      "type": "we-text",
      "props": { "variant": "body", "textAlign": "center", "maxWidth": "var(--we-layout-xs)" },
      "children": ["You haven't joined this space yet."]
    },
    { "type": "we-button", "props": { "variant": "primary", "onClick": { "$action": "…" } }, "children": ["Join"] }
  ]
}
```

Use `gradient` on the icon when there is something to do, and a flat `color` (`text-faint`,
or `warning-text`) when there is not — the two read apart at a glance, and a dead end that looks
like an invitation is worse than one that looks like a dead end.

A role here rather than a scale position such as `neutral-300`, and the reason is sharper than
house style. A scale position is not frozen — it follows the theme's hue, saturation and polarity —
but it cannot follow what a theme *decides* a faint foreground is, and the contrast corrections at
apply time skip it entirely, so nothing ever measures it against what is behind it.

### How wide is a modal — always `size`, never a pixel width

`we-modal` sizes itself from a `size` prop, and **every modal should set one**:

| `size` | Measure | For |
|---|---|---|
| `sm` | 420px | A confirmation, or one or two fields. |
| `md` | 640px | **The default.** A form. |
| `lg` | 900px | A workspace — a composer, a wizard, a card opened out to be read. |
| `fullscreen` | The viewport, less a gutter | A lightbox, where the content is the size. |

Each keeps a gutter between itself and the edge of the screen, so a modal on a phone is never
edge-to-edge. Do **not** write `"width": "100%"` beside a `"maxWidth"` — that is what `size`
replaced, and `100%` of a viewport-wide host is the viewport.

Without a size, `[part='base']` shrink-wraps to its widest line of text: a short confirmation comes
out too narrow to read and a wordy one too wide, from the same rule. `width`/`maxWidth` still
override `size` for the rare modal that genuinely needs its own number.

### Confirm dialog

**Use `confirmModal` from `@we/template-kit`.** Every "are you sure?" in WE goes through it, so
they share an icon, a heading, a width and a button row:

```ts
confirmModal({
  open: { $: 'local.confirmRemoveOpen' },
  close: { $setLocal: 'confirmRemoveOpen', value: false },
  title: 'Remove this column?',
  body: 'The cards in it stay on the board, in the state they are in.',
  confirmLabel: 'Remove',
  confirm: { $action: 'spaceStore.removeBoardColumn', args: [{ $: 'board.id' }, { $: 'column.id' }] },
})
```

**Never in front of a delete.** The host asks before every destructive action a space template runs
— `spaceStore.deleteCollection`, `record.delete`, `recordStore.deleteRecords` and the rest —
in its own words, saying what goes with it. Call one straight from the button. A dialog of your own
in front of it is a second question about one click, and the validator warns about it.

It returns the `$if` as well as the modal, and clears `open` from all three exits — the backdrop,
Cancel, and the action's `onSuccess`.

- `open` and `close` are **expressions**, so a dialog gated on a store flag
  (`{ $: 'shapeStore.confirmDiscard' }`) or on a string id works the same way.
- `cancel` for a cancel button that does more than close — "Keep editing" dismisses the question
  and leaves the wizard behind it open.
- `tone: 'primary'` for a question with no casualty; the default `danger` picks a warning icon and
  a danger confirm button.
- `detail` for a quieter second line, `children` for a `we-alert` naming a surprising consequence.
- `busyLocal` if the action is not instant — a write that walks a board or a thread takes a while, and
  without a spinner the button absorbs the click and invites a second one. `busy` instead when a
  store already owns the flag.

The flag must be declared by an ancestor of **the button that opens it**, not merely of the modal.
Undeclared, `$setLocal` warns and no-ops: the button renders, takes the click, and does nothing.

### A form in a modal

**Use `formModal` from `@we/template-kit`** — title, fields, Cancel and Save:

```ts
formModal({
  open: { $: 'local.composerOpen' },
  close: { $setLocal: 'composerOpen', value: false },
  title: 'New task',
  size: 'sm',
  localState: { draftTitle: { type: 'string', initial: '' } },
  children: [field({ name: 'draftTitle', label: 'What needs doing?', placeholder: 'Ship the docs' })],
  disabled: { $: '!local.draftTitle' },
  submitLabel: 'Add task',
  submit: { $action: 'record.create', args: ['TaskBlock', { title: { $: 'local.draftTitle' } }] },
})
```

- **Declare the draft in `localState`, not on the page.** The modal is mounted only while open, so
  the draft resets when it closes — for free. A draft declared higher up has to be cleared by hand
  in `onSuccess`, and the field somebody forgets is the one that re-opens holding last time's value.
- `disabled` is the **precondition** only ("a task needs a title"); the in-flight flag is OR-ed
  in for you, so the Save button cannot start a second save.
- It uses the header and footer slots, so a long form scrolls its fields and never its Save button.

Reach past it only for a form with real `validate` rules and a `{ "$touch": "$all" }` submit guard
— that shape deliberately keeps the button clickable, and is written out by hand.

### Don't lose what somebody typed — the discard guard

A modal closes on a backdrop click and on Escape. Both are easy to hit by accident, and neither is
recoverable: the modal is `$if`-mounted, so closing unmounts the draft with it. **Any modal a
person can type into must ask before throwing that away.**

| Writing | How |
|---|---|
| `formModal` | `discardWhen: <expression>` |
| `composerModal` | Nothing — on by default (`guardDraft: false` turns it off) |
| A hand-written `we-modal` | `discardGuard({ dirty, close })` |

`discardGuard` returns three pieces, because a modal cannot be guarded from outside it:

```ts
const guard = discardGuard({
  dirty: { $: 'local.name || local.description' },
  close: { $action: 'shellStore.setCreateSpaceOpen', args: [false] },
  title: 'Discard this space?',
  body: 'The name, description and images you have entered will be lost.',
});

{ type: 'we-modal',
  props: { size: 'md', close: guard.close },
  $localState: { ...myFields, ...guard.localState },
  children: [ …the form…, guard.node ] }
```

Wire the Cancel button to `guard.close` as well — one way out of a modal, not two that disagree.

**Writing `dirty` is the part that goes wrong**, and always in one direction: a guard that fires
when there is nothing to lose. A dialog people learn to click through is worse than no dialog.

- **Test only what the person typed.** A field with a default and a picker — a status, a mode, a
  colour — is set from the first frame, so including it makes the guard fire on an untouched form.
- **A form seeded from a record asks whether it _changed_**, not whether it is filled in:
  `{ "$": "local.titleDraft != call.title" }`, not `{ "$": "local.titleDraft" }`.
- **Where the fields are not known in advance, a store answers** — `recordStore.recordDraftDirty`,
  `runtimeStore.aiFormDirty`.
- **Leave it off a single-field form** ("name this board"). The guard costs more attention than one
  word is worth.

**Tall modals — pin the title and buttons.** A modal whose content can outgrow the viewport (a
long form, a settings editor) scrolls its *content*, never its own title or its action buttons.
Give the title node `"slot": "header"` and the button row `"slot": "footer"`: both are pinned
outside the scroll region, sharing the modal's padding and gap, while the default slot scrolls.
`confirmModal` and `formModal` already do this; write it out only for a modal that is neither.

### Composing a post — the BlockComposer save handshake

`BlockComposer` is **pull-based**. Its `onSave` does *not* fire when the user types or when a modal
closes — it fires when somebody calls the composer's own `save()`, which it hands out exactly once
through `onReady`. So the sequence is: `onReady` stores that function in a **`function`-typed**
`$localState` field, the button calls it with `$callLocal`, `save()` serializes the tree, and
`onSave` runs the action with the tree as `arg`.

```json
{
  "type": "we-modal",
  "props": { "size": "lg", "close": { "$setLocal": "composeOpen", "value": false } },
  "$localState": {
    "savePost": { "type": "function", "initial": null },
    "submitting": { "type": "boolean", "initial": false }
  },
  "children": [
    {
      "type": "BlockComposer",
      "props": {
        "onReady": { "$setLocal": "savePost", "value": { "$": "event.save" } },
        "onSave": [
          { "$setLocal": "submitting", "value": true },
          {
            "$action": "spaceStore.createPost",
            "args": [{ "$": "arg" }],
            "onSuccess": [{ "$setLocal": "composeOpen", "value": false }],
            "onFinally": [{ "$setLocal": "submitting", "value": false }]
          }
        ]
      }
    },
    {
      "type": "we-button",
      "props": {
        "variant": "primary",
        "loading": { "$": "local.submitting" },
        "disabled": { "$": "local.submitting" },
        "onClick": { "$callLocal": "savePost" }
      },
      "children": ["Post"]
    }
  ]
}
```

**Do not** wire the button straight to the action against a `draft` local the composer was expected
to fill in. That spelling typechecks, validates, renders — and posts `null`, surfacing as
`Cannot read properties of null (reading 'type')` from inside `persistNode`, several frames from
the cause. And because `onReady` is optional, omitting it makes the composer render a floppy-disk
save button of its own, so the screen ends up with two buttons and only the unexpected one works.
(`we-validate-schemas` rejects `onSave` without `onReady`.)

`{ "$": "arg" }` goes wherever the action wants it — first for `createPost(json, options)`, second for
`updatePost(postId, json)`.

**Prefer `composerModal` from `@we/template-kit`**, which owns all of the above; write it out by
hand only when the modal itself needs a different shape.

### Form field

```json
{
  "type": "we-form-field",
  "props": { "label": "Name", "error": { "$": "error('name')" } },
  "children": [
    {
      "type": "we-input",
      "props": {
        "placeholder": "Space name…",
        "value": { "$": "local.name" },
        "onInput": { "$setLocal": "name", "value": { "$": "event.detail" } }
      }
    }
  ]
}
```

`error()` is already empty until the field is touched, so it needs no condition around it. Which event
carries the value depends on the control: `we-input`/`we-textarea` emit `onInput` with
`event.detail`, `we-select` emits `onChange` with `event.detail`, and `Search` calls back
with the value itself as `arg`.

### Author byline

```json
{
  "type": "$agent",
  "props": { "did": { "$": "post.author" }, "as": "author" },
  "children": [
    {
      "type": "Row",
      "props": { "ay": "center", "gap": "300" },
      "children": [
        { "type": "we-avatar", "props": { "size": "sm", "image": { "$": "author.avatar" }, "hash": { "$": "author.did" } } },
        { "type": "we-text", "props": { "fontWeight": "semibold" }, "children": [{ "$": "author.name" }] },
        { "type": "we-timestamp", "props": { "value": { "$": "post.createdAt" }, "relative": true, "color": "text-muted" } }
      ]
    }
  ]
}
```

Always set `hash` as well as `image`, never as a fallback for it — and seed it with an **id**, never
a name. `hash` is the stable thing a row *is*: a DID for a person, a uuid for a space. It does two
jobs. It colours the generated initials, so the colour survives a rename; and it draws an identicon
when there are no initials to draw, which is the case it exists for — somebody whose profile has not
arrived has no name yet, and two unresolved peers must not be two identical blank discs.

What `we-avatar` draws, in order: **a picture, else letters, else a generated pattern, else a
glyph.** Letters outrank the pattern, so a row that has both shows its initials on a colour seeded
from the hash. Seeding `hash` with a *name* is the mistake to avoid: it makes the colour change when
somebody renames the thing, which is identity art contradicting the identity.

### A record of any type — rendering from the declaration

A community can define a model this morning and record one this afternoon; the feed that lists it
was written before either. So a card cannot name the fields. It reads how the model asks to be
shown — `recordStore.displays`, derived from the same declaration the form comes from — and draws
whatever is there:

```json
{
  "type": "$each",
  "props": { "items": { "$query": { "entity": "Sighting" } }, "as": "row" },
  "children": [
    {
      "type": "Card",
      "$localState": { "display": { "type": "object", "initial": { "$": "recordStore.displays['Sighting']" } } },
      "children": [
        {
          "type": "$if",
          "props": {
            "condition": { "$": "local.display.media" },
            "then": { "type": "we-image", "props": { "src": { "$": "row[local.display.media]" }, "fit": "cover", "r": "media" } }
          }
        },
        { "type": "we-text", "props": { "variant": "heading-sm" }, "children": [{ "$": "row[local.display.title]" }] },
        { "type": "we-text", "props": { "color": "text-muted" }, "children": [{ "$": "row[local.display.summary]" }] },
        {
          "type": "$each",
          "props": { "items": { "$": "local.display.fields.filter(f, f.role == 'detail')" }, "as": "field" },
          "children": [
            {
              "type": "Row",
              "props": { "gap": "300", "ay": "center" },
              "children": [
                { "type": "we-text", "props": { "variant": "label", "color": "text-muted" }, "children": [{ "$": "field.label" }] },
                {
                  "type": "$if",
                  "props": {
                    "condition": { "$": "field.kind == 'datetime' || field.kind == 'date'" },
                    "then": { "type": "we-timestamp", "props": { "value": { "$": "row[field.name]" }, "relative": true } },
                    "else": {
                      "type": "$if",
                      "props": {
                        "condition": { "$": "field.kind == 'boolean'" },
                        "then": { "type": "we-badge", "children": [{ "$": "row[field.name] ? 'Yes' : 'No'" }] },
                        "else": { "type": "we-text", "children": [{ "$": "row[field.name]" }] }
                      }
                    }
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

Nothing here names a property of `Sighting`. `row[local.display.title]` reads whichever property the
declaration (or the derivation) says is the title; the detail rows switch on `field.kind`, which is
resolved once in the store so a template switches on one word. Add branches for `image`, `url`,
`color` and `longText` as a layout needs them — the kinds are listed under `recordStore.displays`.

The `$localState` holding the display is a convenience: `recordStore.displays['Sighting']` could be
read in place each time. For a feed of *mixed* types, index by the row instead —
`recordStore.displays[row.type]` — and the same card draws every kind of record the space holds.

**A picture held by relation.** A community model carries its photo as a relation to an
`ImageBlock` rather than as a string, so `display.media` is empty and `display.mediaRelation`
names the relation. The row holds ids, not a URL — look the image up, and gate the query so an
unresolved id does not widen it to every image in the space:

```json
{
  "type": "$if",
  "props": {
    "condition": { "$": "local.display.mediaRelation && row[local.display.mediaRelation]" },
    "then": {
      "type": "Column",
      "$queries": {
        "pictures": {
          "entity": "ImageBlock",
          "where": { "id": { "$": "row[local.display.mediaRelation]" } },
          "when": { "$": "row[local.display.mediaRelation]" },
          "limit": 1
        }
      },
      "children": [
        { "type": "$if", "props": { "condition": { "$": "count(local.pictures)" },
          "then": { "type": "we-image", "props": { "src": { "$": "first(local.pictures).src" }, "fit": "cover", "r": "media" } } } }
      ]
    }
  }
}
```

### A group of faces with a count

```json
{
  "type": "Row",
  "props": { "gap": "300", "ay": "center", "minHeight": "32px" },
  "children": [
    {
      "type": "AvatarStack",
      "props": {
        "avatars": { "$": "spaceStore.members.map(m, { image: m.avatar, hash: m.did })" },
        "max": 5, "size": "sm", "ring": "0 0 0 2px var(--we-ring-color)"
      }
    },
    {
      "type": "Row",
      "props": { "gap": "100", "ay": "center" },
      "children": [
        { "type": "we-number", "props": { "value": { "$": "count(spaceStore.members)" }, "shorten": true } },
        { "type": "we-text", "children": [{ "$": "plural(count(spaceStore.members), 'Member', 'Members')" }] }
      ]
    }
  ]
}
```

**When the items are bare DIDs rather than profiles**, join each to its profile inside the
comprehension — the variable is the DID itself:

```json
"avatars": { "$": "spaceStore.memberDids.map(did, { image: find(profileStore.profiles, { did: did }).avatar, hash: did })" }
```

`minHeight` on the row is worth keeping: `AvatarStack` has no height with no avatars, and people
resolve later than the record they belong to, so without a floor the row collapses and then pushes
everything below it down a second time.

### Page shell — a route's outer box

```json
{
  "type": "Column",
  "props": { "width": "100%", "ax": "center" },
  "children": [
    {
      "type": "Column",
      "props": { "width": "100%", "maxWidth": "var(--we-layout-lg)", "gap": "500", "px": "400", "py": "500" },
      "children": ["…"]
    }
  ]
}
```

Two Columns, because centring and constraining are different jobs: the outer spans the viewport so
the route's background reaches the edges, the inner holds the measure.

### A composition placed by hand — Canvas and an artboard

For anything where the author means a specific geometry: a scrapbook, a poster, a diagram, a title
card. `Canvas` declares the coordinate space its children's `x` / `y` are in, and scales that
space to whatever box it lands in — so one authored layout is never *broken*, only smaller.

```json
{
  "type": "Canvas",
  "props": { "artboard": { "width": 1200, "height": 1600 } },
  "children": [
    {
      "type": "we-image",
      "props": { "src": "…", "x": 90, "y": 120, "rotate": -4, "width": "420px", "shadow": "lg", "r": "200" }
    },
    {
      "type": "we-text",
      "props": { "x": 560, "y": 320, "rotate": 2, "variant": "heading-lg", "maxWidth": "380px" },
      "children": ["The summer we moved"]
    }
  ]
}
```

- **`artboard` is the point.** Without it a pixel resolves against whatever positioned ancestor
  happens to be there — a docked panel, an editor preview pane, a phone — and nothing downstream can
  scale it. `{ "width": 1200, "height": 1600 }` says what those numbers *mean*.
- **Children are placed, not flowed.** Every direct child starts at the artboard's origin, so
  `x`/`y` are coordinates and not offsets from whatever precedes them. Content that should flow
  goes inside a placed `Column`, not loose on the canvas.
- **Place with `x` / `y` / `rotate`, never `top` / `left`.** Offsets do not respond to a
  breakpoint (see the Layout props) and do not compose with rotation; these do both.
- **Stack with `zIndex`.** A raw number is legal there, not only the named layers — overlap is the
  entire point of a scrapbook, and on a canvas it should be chosen rather than inherited from
  document order.
- **A tall artboard scrolls like a page.** At the default `fit: "scale"` the canvas takes the
  height the scaled artboard needs, so a composition several screens long behaves like ordinary
  content. Pair sections of it with `$animate` and `scrollReveal` to bring them in as they arrive.
- **Reach for `fit: "contain"` only where the canvas has a height of its own** — a fixed panel, a
  slide. In document flow there is no second axis to fit against and it scales by width anyway.

**Do not use a Canvas for a layout that is merely arranged.** A dashboard of cards is a `Grid`, and
a page is a `Column`. The test is whether the coordinates carry meaning the author chose: two
photos overlapping at an angle, yes; three cards in a row, no.

### Titled section on a card

```json
{
  "type": "Card",
  "props": { "bg": "surface", "border": "1px solid border" },
  "children": [
    {
      "type": "Column",
      "props": { "gap": "100" },
      "children": [
        { "type": "we-text", "props": { "variant": "heading-md" }, "children": ["About this space"] },
        { "type": "we-text", "children": ["Manage how this space appears to others."] }
      ]
    },
    "…"
  ]
}
```

### Labelled attribute with an optional control

```json
{
  "type": "Row",
  "props": { "ay": "center", "ax": "between", "wrap": true },
  "children": [
    {
      "type": "Row",
      "props": { "ay": "center", "gap": "400", "py": "100" },
      "children": [
        { "type": "we-icon", "props": { "name": "globe", "color": "accent-text" } },
        {
          "type": "Column",
          "props": { "gap": "100" },
          "children": [
            {
              "type": "Row",
              "props": { "gap": "300" },
              "children": [
                { "type": "we-text", "props": { "fontWeight": "bold", "color": "text" }, "children": ["Discovery:"] },
                { "type": "we-text", "props": { "fontWeight": "bold" }, "children": ["Listed"] }
              ]
            },
            { "type": "we-text", "props": { "variant": "body" }, "children": ["Appears on the WE discovery globe"] }
          ]
        }
      ]
    },
    { "type": "we-switch", "props": { "checked": true, "onChange": { "$action": "…" } } }
  ]
}
```

Drop the outer `Row` and the control for the read-only form.

### A rail that opens on hover — collapsed navigation

The shape of WE's shell sidebar: a narrow strip of icons that widens when pointed at, with the
labels opening sideways beside them.

Three pieces of state do all of it, and none of it needs a component. The shell owns `expanded`
and writes it from `onMouseEnter`/`onMouseLeave`; every label reads it. Groups hold their
collapsed ids in one `array` field rather than a boolean each, which is what lets the groups
themselves come from a `$query`.

```json
{
  "type": "Column",
  "$localState": {
    "expanded": { "type": "boolean", "initial": false, "persist": "shell.sidebarExpanded" },
    "collapsedGroups": { "type": "array", "initial": [] }
  },
  "props": {
    "width": { "$": "local.expanded ? '240px' : '80px'" },
    "transition": "width 300 ease-in-out",
    "height": "100%",
    "overflow": "hidden",
    "position": "fixed",
    "bg": "page",
    "onMouseEnter": { "$setLocal": "expanded", "value": true },
    "onMouseLeave": { "$setLocal": "expanded", "value": false }
  },
  "children": [
    {
      "type": "we-button",
      "props": { "variant": "ghost", "width": "100%", "ax": "start", "gap": "300", "p": "300" },
      "children": [
        { "type": "we-icon", "props": { "name": "user" } },
        {
          "type": "$if",
          "props": {
            "condition": { "$": "local.expanded" },
            "enterTransition": [{ "type": "reveal", "axis": "inline", "duration": 250 }, { "type": "fade", "duration": 150 }],
            "exitTransition": [{ "type": "reveal", "axis": "inline", "duration": 250 }, { "type": "fade", "duration": 150 }],
            "then": { "type": "we-text", "props": { "truncate": true }, "children": ["Profile"] }
          }
        }
      ]
    }
  ]
}
```

The label is mounted only while the rail is open rather than narrowed to nothing: at collapsed width
there is no room for it, and a hidden-but-present label is still in the accessibility tree and still
found by find-in-page.

A group heading toggles its own id in the set, and its body reveals on the block axis:

```json
{
  "type": "we-button",
  "props": { "variant": "ghost", "onClick": { "$toggleLocalIn": "collapsedGroups", "value": "spaces" } },
  "children": [
    {
      "type": "we-icon",
      "props": { "name": { "$": "'spaces' in local.collapsedGroups ? 'caret-right' : 'caret-down'" } }
    },
    { "type": "we-text", "children": ["Spaces"] }
  ]
}
```

**Prefer `railShell` / `railGroup` / `railItem` from `@we/template-kit`**, which own all
of the above. `railItem` and `railGroup` read `expanded` from the shell above them, so they
are only valid inside a `railShell`.

For drag-to-reorder, wrap a group's items in `we-sortable` and give each row a `data-we-id` on
a **native element** — a web component's props are assigned as DOM properties, so the attribute
`we-sortable` looks for would never exist on a `we-button`. Listen with `onReorder` and read
the new order from `{ "$": "arg.detail" }`.

---

## Routing Structure

Define nested routes using the "routes" array at the root node of the schema.
Each route object describes a path and the UI node to render when that path is active.
Routes can be nested to support sub-pages and layouts.

Route objects follow the same structure as schema nodes, with an additional "path" property.

- The "routes" array MUST be placed on the ROOT template node (or on a route node for nested routing). The router only reads routes from these positions — placing routes on an arbitrary child node means the router will never find them and nothing will render.
- Use "path: '*'" or "path: '/*'" for catch-all/not-found routes.
- Use ":paramName" for dynamic route parameters (e.g. "/space/:spaceId").
- Use nested "routes" arrays for sub-pages and layouts.
- Use { "type": "$routes" } in children to indicate where nested routes should render. The $routes outlet can be deeply nested — only the routes array placement matters.
- EVERY { "type": "$routes" } outlet MUST have a "routes" array defined on the same node or an ancestor node. A $routes outlet without a routes array is invalid and will fail validation.
- NEVER duplicate a route path — every route in the same "routes" array MUST have a unique path.
- When using tabs, each tab's key and navigate path MUST have a matching route. Ensure a 1:1 correspondence between tabs and routes.

### Tabs + Routing

IMPORTANT: we-tabs only manages visual selection — clicking a tab does NOT navigate automatically.
Each we-tab MUST have an onClick with { "$action": "routeStore.navigate" } to trigger route changes.
Bind we-tabs selectedKey to the matching route segment so the active tab stays in sync.
(Alternatively, a single onChange on we-tabs can replace per-tab onClick — see onChange pattern below.)

Recommended pattern — header above tabs (routes on ROOT, $routes outlet nested inside):
{
  "type": "Column",
  "routes": [
    { "path": "/", "type": "we-text", "children": ["Select a tab"] },
    { "path": "/posts", "type": "Column", "children": [{ "type": "we-text", "children": ["Posts content"] }] },
    { "path": "/articles", "type": "Column", "children": [{ "type": "we-text", "children": ["Articles content"] }] }
  ],
  "children": [
    { "type": "Row", "props": { "p": "300", "ax": "between" }, "children": [
      { "type": "we-text", "props": { "variant": "heading-lg" }, "children": ["My App"] }
    ]},
    {
      "type": "we-tabs",
      "props": { "selectedKey": { "$": "routeStore.segments[0]" } },
      "children": [
        { "type": "we-tab", "props": { "key": "posts", "label": "Posts", "onClick": { "$action": "routeStore.navigate", "args": ["/posts"] } } },
        { "type": "we-tab", "props": { "key": "articles", "label": "Articles", "onClick": { "$action": "routeStore.navigate", "args": ["/articles"] } } }
      ]
    },
    { "type": "$routes" }
  ]
}
Note: "routes" is on the root Column, NOT on a child. The $routes outlet is a child — that's fine. Only the routes array placement matters.

WRONG — two common mistakes that produce empty tabs (validator will catch both):
{
  // MISTAKE 1: routes defined on an inner child node, not the root.
  // The router never inspects children for routes arrays — this routes array is invisible.
  "type": "Column",
  "children": [
    { "type": "we-tabs", "children": ["...tabs..."] },
    {
      "type": "Column",
      "routes": [                          // ← WRONG: router never reads this
        { "path": "/posts", "type": "Column", "children": ["..."] }
      ],
      "children": [{ "type": "$routes" }]  // ← outlet here does nothing without a live routes array
    }
  ]
}

{
  // MISTAKE 2: using { type: "$routes" } as a route entry's component type.
  // $routes is an outlet slot marker — as a leaf route entry it has no children injected,
  // so it returns null. Every tab navigates to a route that renders nothing.
  "type": "Column",
  "routes": [
    { "path": "/posts", "type": "$routes" }  // ← WRONG: renders null, use a real component
  ],
  "children": [{ "type": "$routes" }]
}

Alternative: single onChange on we-tabs (fires with event.detail.value = selected key):
{ "onChange": { "$action": "routeStore.navigate", "args": [{ "$": "`/${arg.detail.value}`" }] } }
This replaces all per-tab onClick handlers but requires an interpolation to build the path.

Nested routing example:
{
  "routes": [
    { "path": "*", "type": "Column", "props": { "ax": "center", "p": "500" }, "children": [{ "type": "we-text", "children": ["Page not found"] }] },
    { "path": "/", "type": "Column", "props": { "ax": "center", "p": "500" }, "children": [{ "type": "we-text", "children": ["Home page"] }] },
    {
      "path": "/space/:spaceId",
      "type": "Row",
      "children": [{ "type": "$routes" }],
      "routes": [
        { "path": "/*", "type": "we-text", "children": ["Space page not found"] },
        { "path": "/", "type": "we-text", "children": ["About sub-page"] },
        { "path": "/posts", "type": "Column", "children": [{ "type": "$routes" }],
          "routes": [
            { "path": "/*", "type": "we-text", "children": ["Post not found"] },
            { "path": "/", "type": "we-text", "children": ["No posts selected"] },
            { "path": "/1", "type": "we-text", "children": ["Post 1 page"] }
          ]
        }
      ]
    }
  ]
}

---

## Panels

A **panel** is a floating or docked surface the host places over a template's content: it can be
moved, resized, closed, and it survives navigation. A template declares which panels its interface
has and where each one starts, in `meta.panels`.

### When something should be a panel

**A region is a panel if any of these is true:**

- it must float over other content
- the reader must be able to move or resize it, and have that remembered
- it must be closable
- it must survive navigation
- it competes with other panels for a screen edge

**Otherwise it is ordinary layout** — `Column` / `Row` / `Grid`, in flow, inside the route,
arranged by its parent.

This matters more than it looks. A dashboard where nothing overlaps, nothing is dragged and nothing
persists position is a `Grid` of cards, and building it from panels instead gives something
busier, harder to read and worse on a phone. **Do not reach for a panel because somebody said the
word "panel"** — reach for one when a region needs to move, close, float or outlive the route.

### Declaring them

```json
{
  "meta": {
    "name": "Workshop",
    "description": "…",
    "icon": "…",
    "panels": [
      { "id": "transcript", "module": "transcribe", "snap": "left", "order": 0, "size": "sm", "grow": 1 },
      { "id": "notes", "node": { "type": "Column", "children": ["…"] }, "title": "Notes", "snap": "left", "order": 1, "grow": 0 },
      { "id": "inspector", "node": { "…": "…" }, "snap": "right", "size": "md" }
    ]
  }
}
```

Two kinds of entry, one list:

- **`module`** places a panel a feature module already contributes, and opens it. The module still
  owns what is inside it.
- **`node`** supplies the content itself. Use `title` to name it in the titlebar.

| Field      | What it means                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `id`       | **Stable, and yours to choose.** Where the reader drags a panel is remembered per id.          |
| `snap`     | One of `top-left` `top` `top-right` `left` `right` `bottom-left` `bottom` `bottom-right`. |
| `order`    | Position *along* the edge among the panels sharing its lane — lower is nearer the start.       |
| `band`     | Which lane, counting inward from the edge. `displace` only. Absent means a lane of its own.    |
| `size`     | `sm` `md` `lg` `full`. The default way to size a panel — see "Sizes" below.                  |
| `box`      | `{ width?, height? }` in pixels — the box it opens at, when no named size is the right shape. |
| `grow`     | Share of the *spare* room in a lane, relative to lane-mates. Absent means 1; 0 pins a size.    |
| `displace` | Push the content aside instead of covering it. Edge snaps only — ignored on a corner.          |
| `tab`      | Position in a seat shared with others — entries with the same lane and `order` are tabs.      |
| `home`     | Start **in the template**, at the `$panels` outlet of this name. See "Home lanes" below.        |
| `fixed`    | Not promotable: no break-out grip, no drop can move it. For a section with no standalone value. |
| `min`      | `{ width?, height? }` in pixels — the smallest box the content is usable in. A fact, not a size.  |
| `route`    | Only while one of these segments is in the path — a segment or a list. Absent means every route. |
| `open`     | Whether to open it as well as place it. Absent means yes — see the warning below.               |

**`open: false` when a panel should wait for its moment.** Placing a `module` panel opens it as
well — through the host's own flag, or through the `show` action a module named when it owns
its panel's openness. That is not always wanted on entering a space: the call module's stage is
open while there is a call to watch, and declaring it without `open: false` would put an empty
stage over the content until somebody started one. The declaration still says where it lands.

### Sizes

**Positions are always named.** A template cannot see the viewport, and a coordinate it guessed is
wrong on a display it never ran on — that is what `snap`, `order` and `grow` are for.

**Reach for `size` first.** A named size is a card whose width comes from the host's table and
whose height is 16:9 of that, which is the right shape for most panels on every screen.

**`box` is for a panel with a shape of its own** — a legend that is tall and narrow, a strip of
faces that is wide and low. It is an opening bid in pixels, not a size the panel is held to:

- **The host clamps it** to the room there is, exactly as it does a named size, so a box too big
  for a laptop is capped rather than hung off the edge. A drag still beats it.
- **It is the whole panel**, titlebar and frame included — the same box `min` is measured against.
  Content that needs a given area adds the host's chrome (a 33px titlebar, a 1px border each side).
- **Either side may be left out.** A width alone keeps the 16:9 height derived from it; a height
  alone keeps the width `size` gives.
- **In a lane, `grow` still has the last word** along the edge: a box's height on a side edge is
  the base the lane divides, not a height the panel keeps.

```json
{ "id": "key", "node": { "…": "…" }, "title": "Key", "snap": "top-right", "box": { "width": 252, "height": 545 } }
```

### An edge is two axes

**`band` is how far inboard, `order` is how far along.** A **lane** is a band across the edge;
the panels sharing one divide it along its length. Between them the two numbers say everything an
edge can hold:

```
 lanes of one panel each          one lane of two            a lane of one, then a lane of two
 ┌────┬────┬──────────┐    ┌─────────┬──────────┐     ┌────┬─────┬──────────┐
 │    │    │          │    │    A    │          │     │    │  B  │          │
 │ A  │ B  │ content  │    ├─────────┤ content  │     │ A  ├─────┤ content  │
 │    │    │          │    │    B    │          │     │    │  C  │          │
 └────┴────┴──────────┘    └─────────┴──────────┘     └────┴─────┴──────────┘
   band 0  band 1              band 0, order 0/1        band 0    band 1, order 0/1
```

- **`band` is for panels that `displace`.** Two that name the same band are one sidebar cut into
  pieces: they share a width, meet flush, and cost the content that width **once**. Two that name
  different bands stack inward and cost it both.
- **Absent `band` means a lane of its own**, after every lane that named one. So a declaration that
  says nothing about lanes gets the old behaviour — panels stacking inward — rather than silently
  halving each other.
- **A floating panel has no band.** It takes no room, so there is nothing to be inboard of: every
  float on an edge already shares one lane, and `order` divides it. Two panels snapped `left`
  share the height, one above the other.

A lane divides by base size and `grow`: spare room goes out by grow ratio. "The transcript takes
most of the height and the panel under it keeps its own" is a large panel with `grow` and a small
one with `grow: 0`.

**Seats.** Two entries in one lane with the same explicit `order` share a seat: one shows, the rest
stack behind it as tabs, and the one showing carries a strip naming them all. `tab` orders the
strip. Absent `order` is a seat of its own, so nothing that never said `order` starts sharing.
A seat has **one size**: joining one means taking it, and resizing one member resizes all of them, so
reading along the strip never reshapes the panel.

A stack the reader drags into open space, or into a corner, stays a stack — it just stops being a
place and starts being a name, since there is no lane left to imply membership from. That is a
reader's doing and not something a template can declare: **declare seats with `order`, in a lane.**

Below 900px of window width nothing displaces and a floating lane becomes one seat — every member a
full-bleed sheet, tabbed, since two narrow cards over content leave nothing of either.

### Home lanes — sections that start in the template

Picture-in-picture, for any region of a page. A **home lane** is a lane in the template's own flow:
an outlet in the tree says where it is, and `meta.panels` entries say which sections start there.

```json
{
  "meta": {
    "panels": [
      { "id": "feed",     "node": { "…": "…" }, "home": "main",  "order": 0, "fixed": true },
      { "id": "trending", "node": { "…": "…" }, "home": "right", "order": 0, "title": "Trending" },
      { "id": "people",   "node": { "…": "…" }, "home": "right", "order": 1, "title": "Who to follow" }
    ]
  },
  "type": "Row",
  "children": [
    { "type": "$panels", "props": { "lane": "left", "width": "280px" } },
    { "type": "$panels", "props": { "lane": "main", "flex": "1" } },
    { "type": "$panels", "props": { "lane": "right", "width": "320px", "accepts": "trending,people" } }
  ]
}
```

A section renders inline, with no frame, indistinguishable from the layout around it — until the
reader hovers it, when a grip appears in its corner. Dragging the grip breaks the section out into
a panel under the pointer; clicking it breaks it out to its declared `snap`. It is then an
ordinary panel: it can be docked, folded, stacked, saved in a layout — and its position menu offers
"Return to page". While it is away the outlet shows a placeholder in its place with the same offer.

- **`$panels` is a layout node.** It takes `lane` (required), `direction` (`column` by default, or
  `row`), `accepts` (section ids it will take, comma-separated; empty means any), and the ordinary
  layout props — `width`, `flex`, `minWidth` — which is how a template holds room for an empty lane.
- **Reordering within a lane is arrangement, not editing.** Dragging one section above another
  rewrites `order` on the reader's placement; nothing touches the tree, and "Reset layout" restores
  the author's order. Dragging a section to another lane changes `home`; to an edge, `snap`.
- **A lane holds sections; a section does not hold a lane.** A `$panels` inside a panel's node is
  refused. Fixed depth is what keeps every position a few integers, which is what keeps a
  template's declaration a suggestion a drag can overrule.
- **Not every region should be a section.** The test is standalone value: would somebody want it
  beside a *different* page? Trending, yes; the compose box, no — say `fixed: true`, or leave it as
  ordinary layout. A template where every region grows a corner grip reads as a widget grid. And
  `$each` over collections is content, never lanes: a kanban's columns are data.
- **A lane is not a Column.** Reach for one when a region should be movable by the reader. Two
  Columns side by side that nobody will ever rearrange are two Columns.

### Placing a module's own pieces

A module publishes **named parts** and composes its own panel out of them, so an interface that
wants them arranged differently places the pieces rather than copying them:

```json
{ "type": "$part", "props": { "id": "transcribe.transcriptFeed" } }
```

`subject` points a part at a different record from the one its module is about — a transcript feed
over a call somebody opened from a link rather than the one being recorded:

```json
{ "type": "$part", "props": { "id": "transcribe.transcriptFeed", "subject": { "$": "routeStore.params.call" } } }
```

A part naming a module nobody has installed renders nothing and reports itself, the same way a
contribution to an unprovided anchor does. Placing the module's *whole* panel is still
`{ "module": "<id>" }` in `meta.panels`; parts are for building something else out of it.

**Supplying a module's panel yourself.** A `meta.panels` entry carrying **both** `module` and
`node` means "that module's panel, arranged here": the module goes on deciding whether the surface
is up and how big it is, and the entry decides what is inside. Without it, an interface that wrote
its own version got *two* panels — the module opens its own when its state says so, and it had no
way to know somebody else was already showing it.

### It is a suggestion, not a setting

`meta.panels` is the middle rung of three. Whatever the reader last dragged a panel to wins; then
the template's declaration; then the module's own opening bid. The declaration is resolved live and
never written, so switching template or section is non-destructive.

A shell that routes itself — every showcase template does — scopes a declaration with `route`
instead, since it has no sections to hang one on. `route` says **whether**, never **where**: a
panel that changed position from one page to the next would work until the reader dragged it once,
since a stored placement is keyed by template and panel rather than by route and outranks every
declaration. A page that genuinely needs its own arrangement wants to be a view.

A **section** (`meta.role: 'view'`) may declare panels too, and should when the layout is about
that section rather than the whole interface — a graph wants a transcript beside it and an inbox
does not. The shell's declaration wins on a collision of `id`.

### Fixed chrome

If a shell pins its own bar or nav strip over the content, declare the band it occupies so floating
panels clear it:

```json
{ "meta": { "chromeReserve": { "top": 56, "width": 420 } } }
```

Report the height it has when **collapsed**. Chrome that grows as somebody opens a disclosure would
otherwise shove a floating panel down the screen mid-read.

---

## Rules & Best Practices

- Always use the correct prop names and value types for each component.
- Never use null as a value in any children array. Only use valid schema nodes or strings.
- Each item in a children array must be either a valid schema node object or a string.
- Use design tokens for spacing, color, radius, etc. (do not use raw CSS except in styles).
- Use the styles prop for custom inline CSS (e.g., { "width": "100px" }).
- Use hoverProps for hover state overrides, activeProps for pressed state, focusProps for keyboard-focus state. Supported on @we/primitives (we-text, we-button, etc.) and layout components (Column, Row). focusProps fires on `:focus-visible` (keyboard), not on mouse click. Do not add a focus ring by hand — `we-button` and `we-input` already have one, themeable via the `ringColor` theme key.
- Use expressions ({ "$": "…" }) for anything computed and handler tokens ($action, $setLocal, …) for anything that happens on an event; a plain string is always text.
- Nest components using children or slots as needed.
- For routes, use the routes array with path and child nodes.
- Do not invent new components or props — use only those listed in the component registry.
- Do not set props to their default/inherited values — omit them. fontSize and fontWeight inherit from parents (~16px / normal), so only set them when you need a different value.
- Omit empty `props` and `children` — both are optional. Do not write `props: {}` or `children: []`.
- Do not use `as const` on schema node `type` fields — `SchemaNode.type` is `string`, so it is never needed.
- For icon-only buttons, nest a `we-icon` child inside `we-button` rather than using a `text` prop with a Unicode character. **Omit the `size` prop on `we-icon` when nesting inside sized primitives** (`we-button`, `we-input`, `we-badge`, `we-textarea`) — these components auto-size nested icons via `--we-context-icon-size` (xs→12px, sm→16px, md→24px, lg→32px, xl→40px). Only set an explicit icon `size` if you need to override the automatic sizing. Example: `{ type: 'we-button', props: { variant: 'ghost', size: 'sm' }, children: [{ type: 'we-icon', props: { name: 'x' } }] }`.
- NEVER pass a bare number like "16" as a size or dimension prop — it is not valid CSS. Always check the component's declared prop type: if it's a string union, use one of the listed values; if it accepts arbitrary strings, include a CSS unit (e.g. "16px", "2rem").
- For interactive list items and selectable options, use `we-button` with variant switching (e.g., `secondary` when selected, `ghost` when not) instead of manually styling `Row` with cursor, bg, and onClick. Buttons provide hover, focus, and active states for free.
- To make a block of content clickable **without any button appearance**, use `we-button` with `variant: 'bare'` — never a `Column`/`Row` with an `onClick`. `bare` is the appearance-free variant: no background, no hover, no padding, no radius, inherited colour — but still a real `<button>`, so it keeps keyboard activation, the `disabled` prop, and the accessibility role that a clickable `Column` silently loses. Do not use `ghost` for this: ghost's hover background is deliberate, and it paints a rectangle over content that supplies its own affordance. Example: `{ type: 'we-button', props: { variant: 'bare', disabled: { $: 'someStore.busy' }, onClick }, children: [{ type: 'Column', props: { gap: '100', ax: 'center' }, children: [...] }] }`.
- For card-like layouts, compose from `Column` with DS props (bg, r, border, p, gap). This gives full control over spacing and appearance.
- When rendering lists of similar items (posts, cards, users, etc.), ALWAYS use `$each` with a single template child — never duplicate the same node structure multiple times. Use literal arrays in `items` for static data, or a store read/`$query` for dynamic data.

### Icon Names (Phosphor Icons)

we-icon uses **Phosphor Icons** (v2.1). Do NOT use Heroicons, Material, or FontAwesome names.
Phosphor names are lowercase-kebab-case. The `weight` prop controls style: "regular" (default), "bold", "fill", "light", "thin", "duotone".

Common Phosphor icon names (use these, NOT Heroicons equivalents):
- Navigation: house, arrow-left, arrow-right, caret-left, caret-right, caret-down, caret-up, arrows-clockwise
- Actions: plus, minus, x, check, pencil-simple, trash, copy, download, upload, share, link, magnifying-glass, funnel, sliders-horizontal
- Communication: chat-circle, chat-dots, envelope-simple, paper-plane-tilt, bell, megaphone
- Social: heart, thumbs-up, thumbs-down, star, share-network, users, user, user-plus
- Media: image, camera, play, pause, stop, microphone, speaker-high, video-camera
- Files: file, file-text, folder, folder-open, clipboard-text, note
- UI: list, squares-four, gear, dots-three, dots-three-vertical, warning, info, question, check-circle, x-circle, eye, eye-slash
- Misc: lightning, rocket, globe, map-pin, calendar, clock, tag, bookmark, flag, lock, shield-check

WRONG icon names (Heroicons/Material — do NOT use):
- "chat-bubble-left" → use "chat-circle"
- "chevron-right" → use "caret-right"
- "cog" / "settings" → use "gear"
- "trash-can" → use "trash"
- "magnifying-glass-circle" → use "magnifying-glass"
- "home" → use "house"
- "favorite" → use "heart"
- "delete" → use "trash"
- "search" → use "magnifying-glass"
- "close" → use "x"
- "menu" → use "list"
- All schemas must be valid JSON with property names and string values in double quotes.
- The meta property at the root is required: { "meta": { "name": "...", "description": "...", "icon": "..." } }
- Always set `bg: 'page'` on root-level schema nodes (templates, pages). Without a background, dark mode renders white. Use the role, not `neutral-50`: the role is what a theme redefines, and a theme that wants a page darker than its cards cannot say so through a scale position.
- Colour every `bg`, `color` and border with a **semantic role** — `surface`, `text-muted`, `border`, `accent-text`, `danger-text` — rather than a scale position. See "Semantic Colour Roles" in the Design System Props section for the full table and what each is for. Scale positions are for palettes (a graph's node colours by category, a chart series), not for meanings.
- Use `we-text`'s `loading` prop for text bound to data that has not arrived — never a hand-authored `$if` + `we-skeleton` beside it. A separate placeholder needs a height nobody can derive from the schema, and any value you measure drifts the moment a theme changes `fontScale` or the type scale. `we-text` sizes its own placeholder from the line it would occupy, so it stays right. Set `loadingWidth` (default `'100%'`) for the one thing the element cannot infer: how wide the absent text would have been.
- An empty `we-text` already reserves one line, so text that simply arrives late does not shift the layout even without `loading`. Only `inline` text still collapses, which is correct for a run inside a sentence.
- Distinguish "not loaded yet" from "loaded and empty" when the difference is visible. A condition like `{ $: 'spaceStore.currentSpace.description' }` is falsy in both cases, so an `else` branch saying "No description" asserts it about a space that has not arrived. Test the container first (`currentSpace`), then its field.
- Prefer intrinsic sizing to a fixed pixel width. A wrapping `Row` whose children carry `flex: '1'` and `minWidth: '0'`, or a `Grid` with `minChildWidth`, adapts at every width rather than at three thresholds and cannot overflow a narrow surface. An unconditional `minWidth: '500px'` inside a non-wrapping row pushes the whole route sideways on a phone or in a docked panel. Where the layout must genuinely change its mind rather than merely stretch, reach for `mdUpProps` — and write the narrow value at base, since every tier is min-width.
- A set of same-shaped things filling a box — video tiles, a photo wall, a board of cards — wants `Grid` with `childAspect: '16 / 9'`, which solves for the arrangement that makes them largest in the box it is given. `columns` is fixed and letterboxes; `minChildWidth` uses width alone and gives columns of postage stamps in a tall box.
- Size a template root with `minHeight`, never `height`. `height: '100%'` makes the root exactly as tall as the viewport, so a route with more content than that overflows the *box* — and the root's background stops at the fold while the content keeps scrolling. `minHeight: '100%'` fills the viewport when a route is short and grows when it is long, which is what a page background needs. The same applies to `'100vh'` — and prefer `'100dvh'` to `'100vh'` anywhere a full-viewport height is meant: on a phone the address bar makes `vh` taller than what is actually visible, so the last rows of the page sit under the browser chrome. Identical on a desktop.

Most @we/primitives inherit all Design System Props documented above (layout, visual, flex, typography, state).
Some layout-only primitives (we-avatar, we-icon, we-image, we-spinner, etc.) only accept Layout props — see the Design System Props section for the full list.

Native HTML elements (lowercase tags render directly without registry entries):
- Layout: div, section, article, aside, main, nav, header, footer
- Text: p, span, h1-h6, pre, code, blockquote
- Lists: ul, ol, li
- Forms: form, input, button, label, select, textarea
- Media: img, video, audio, canvas, figure, figcaption
- Other: a, table, tr, td, th, details, summary, dialog

Only elements that display, group or take input may be mounted; the full list is
TEMPLATE_HTML_ELEMENTS in @we/schema-shared. Anything else renders nothing and the validator reports
it — script, style, link, meta, base, iframe, object, embed, template, svg among them, because each
runs code, loads something into the page or makes a document of its own. For an embedded page use
we-iframe; for formatted markup use we-html or we-markdown.

A URL prop (href, src, action, poster and the like) may not hold a javascript: URL, or a data: URL
other than an image, audio or video — it is dropped, whether written out or built by an expression.
srcdoc is dropped everywhere, and a lowercase on… prop such as onerror is dropped from a native
element: handlers are written onError and hold a handler token, never a string.

## Schema Validation

Run `we-validate-schemas` (or `node packages/schema-system/shared/dist/cli/we-validate-schemas.js`) from the monorepo root to validate all `.schema.ts` files.
For a specific file: `we-validate-schemas packages/app-shell/src/shared/schemas/MyTemplate.schema.ts`

After creating or modifying a `.schema.ts` file, always run validation to catch:
- Unknown component types (typos, missing registry entries)
- Invalid or misspelled props (with "did you mean?" suggestions)
- Prop type mismatches (e.g., number where string expected)
- Missing required `meta` field on root TemplateSchema nodes
- `$routes` outlet without a `routes` array on an ancestor
- Orphan `local.*` reads / `$setLocal` writes without a `$localState` ancestor, and references in the old string spelling (`'$item.name'`)
- DS layer consistency (mixing props from layers the component doesn't support)

---

## Developer Patterns (codebase work — not for JSON schema authoring)

---

### Using the Design System in TypeScript Components

When writing Solid TSX components (stores, editor panels, settings UI, etc.), always
reach for design system primitives before writing raw HTML elements with inline styles.

**Layout:** Use `Column`, `Row`, and `Grid` from `@we/components/solid` for all
flex and grid layouts. DS props (`gap`, `p`, `px`, `bg`, `r`, `border`, etc.)
cover the vast majority of layout needs without inline styles.
- `Grid` supports uniform columns (`columns={3}`), responsive auto-fill
  (`minChildWidth="280px"`), and custom templates (`template="28px 1fr 28px"`).
- Use the `styles` prop only for CSS that genuinely has no DS equivalent.

**Text:** Use `we-text` with its own props (`fontSize`, `fontWeight`, `color`,
`truncate`, `variant`, etc.) rather than passing everything through `style={{}}`.

**Interactive controls:** Use `we-button`, `we-input`, `we-checkbox`, `we-select`,
`we-switch` etc. — they bring theming, focus rings, hover states, and accessibility
for free. Never roll custom `<button>` or `<input>` elements when a primitive fits.

**Scrollable areas:** Use `we-scroll-area` instead of `overflow: auto` on a div —
it gives consistently styled scrollbars across themes.

**Dividers:** Use `we-divider` or the `borderBottom`/`borderTop` DS prop on a
`Column`/`Row` rather than a raw `<hr>` or border on a wrapper div.

**Token values:** Use `tokenVar` from `@we/design-utils` when you need a token value
inside a `style={{}}` object. Prefer DS props directly where possible.

**Name a colour ROLE, in code as well as in a schema.** `tokenVar('color', 'text-muted')`, not
`tokenVar('color', 'neutral-600')` — a step is invisible to the contrast corrections at apply time
wherever it is written, and `tokenVar` accepts a role name directly. `pnpm audit:roles` covers the
TypeScript and SCSS as well as the schemas, and gates CI.

Note what `tokenVar` does with a name it does not know: it warns in development and returns
`var(--we-color-<name>)` anyway, so a typo or an invented family compiles to a variable nothing
declares and the declaration is dropped. The element paints nothing, which reads as a design
decision rather than a bug.

Raw inline styles and hardcoded CSS variable strings (`var(--we-color-neutral-400)`)
are a signal that a DS prop or primitive is being missed — check before reaching for
`style={{}}`.

---

### Auto-generated Files — Never Edit Directly

The following files are fully regenerated by `pnpm --filter @we/ai-context generate-context`.
**Never edit them manually** — changes will be overwritten on the next generation run.

| File | Source to edit instead |
|---|---|
| `CLAUDE.md` | `packages/ai-context/src/fragments/` |
| `AGENTS.md` | `packages/ai-context/src/fragments/` |
| `.github/copilot-instructions.md` | `packages/ai-context/src/fragments/` |
| `.cursor/rules/we-schema.mdc` | `packages/ai-context/src/fragments/` |
| `packages/ai-context/src/schemaContext.ts` | `packages/ai-context/src/fragments/` or `assembler.ts` |
| `packages/ai-context/src/contextData.ts` | `packages/ai-context/src/generate.ts` or `storeEntries` |

To add or change documented schema fields, tokens, conventions, or rules:
1. Edit the appropriate fragment in `packages/ai-context/src/fragments/`
2. Run `pnpm --filter @we/ai-context generate-context` to regenerate all output files
3. Commit both the fragment source change and the regenerated files together

---

### Git Workflow — Default Branch & PR Summaries

`main` is the production branch — it only receives periodic merges for releases, each tagged
`v<version>` (the release steps are in `docs/contributing/ad4m-and-deploys.md`).
`dev` is where all active work happens. Always branch from `dev`, and always
diff/compare against `dev` (e.g. `git diff dev...HEAD`, `git log dev..HEAD`) —
never `main`, even though it exists.

**PR summary convention:** a PR description follows `docs/contributing/pull-requests.md`. When
asked to write one for a branch, create `PR_<DESCRIPTIVE_NAME>.md` at the repo root, based on
`git diff dev...<branch>` and the branch's commit log, with these sections:

- **What** — what merging it changes, in a few bullets.
- **Why** — the problem, and why this is the right fix for it.
- **How** — where a reviewer should start and the route through the change; a table of files when
  it is wide, explaining *why* each changed rather than restating the diff.
- **Test plan** — what was actually verified, ticked, and what was not, unticked with the reason.
  **A checkbox is a thing that must be true before this merges, and nothing else is a checkbox.**
  `- [x]` done; `- [ ]` not done, and the PR is not finished. Anything that will never be
  ticked is a BULLET, not a box — a deferral is `- **Deferred — …**` with the reason and where it
  goes instead. GitHub counts every checkbox in a description and prints "6 of 7 tasks" on the PR,
  so a box nobody intends to tick makes that number wrong on every PR, and a number that is always
  wrong is one everybody learns to ignore. `scripts/pr-tasks.mjs` fails CI on an unticked box.

The file is the description and nothing else — no title heading above the sections, since it is
passed as `gh pr create --body-file` and anything above a pairing block (below) breaks it. Give
the **title** alongside it, for `--title`, in Conventional Commits form: `type(scope):
description`, the type lowercase (`feat`, `fix`, `refactor`, `perf`, `docs`, `test`,
`ci`, `chore`), the scope optional, and the description short — under 60 characters, naming the
change rather than explaining it: `ci: pair PRs with an ad4m alert block`.

**If the branch needs an ad4m change that has not been published yet**, the file must START with
this block, exactly — the preview builds against it and a check tests the PR there, and
anything close (no colon, another heading or alert, lower down) fails rather than pairing:

```markdown
> [!IMPORTANT]
> ### Paired with: coasys/ad4m#<N>
```

`coasys/ad4m@<branch>` names an ad4m branch instead — only for a change with no ad4m PR, since a
branch pairing gets no link, no "ready to bump" label, and breaks once the branch is deleted. While
paired, import the new SDK API directly; never redeclare its types or feature-check a method to
compile against the pin. The PR cannot merge until the block is removed. The rules are in
`docs/contributing/ad4m-and-deploys.md`.

**Never commit `PR_*.md` files.** They're scratch documents for the PR description.

---

### Building the AD4M Executor Binary (CRITICAL)

The ad4m repo has two artefacts with confusingly similar names:

| Artefact | Cargo flag | Crate location | What it builds |
|---|---|---|---|
| `ad4m-executor` **library** | `-p ad4m-executor` | `rust-executor/` | Library only — **does NOT update the binary** |
| `ad4m-executor` **binary** | `--bin ad4m-executor` | `cli/` (package `ad4m`) | The actual executable used by WE |

**Always use `--bin` to rebuild the running binary:**
```sh
cargo build --release --bin ad4m-executor
```

Using `-p ad4m-executor` will appear to succeed (Cargo reports "Finished") but the
binary at `target/release/ad4m-executor` will NOT be updated — any Rust changes
(log lines, bug fixes) will be silently absent from the running app.

After rebuilding, verify with:
```sh
ls -la target/release/ad4m-executor   # timestamp must be fresh
strings target/release/ad4m-executor | grep "your log string"
```

**After modifying `@coasys/ad4m` TypeScript (e.g. `core/src/model/Ad4mModel.ts`):**

The root `package.json`'s pnpm `overrides` pin `@coasys/ad4m` and `@coasys/ad4m-connect` to a
**published version**, not a local `file:` link, and every WE build uses that pin except a deploy
preview whose PR description pairs it with an ad4m change. The pairing is this exact block, first in
the description — anything close (no colon, another heading or alert, lower down, the old
`ad4m: coasys/ad4m#<N>` line) is an error, not a pairing:

```markdown
> [!IMPORTANT]
> ### Paired with: coasys/ad4m#<N>
```

So a local
`cd ad4m/core && pnpm run build` does NOT get picked up by WE — changes to `@coasys/ad4m` reach WE
once a version is published from the ad4m repo and the pin moves. A bot keeps one PR open that moves
it to the newest ad4m `dev` version (`.github/workflows/bump-ad4m.yaml`); a feature that needs a
new ad4m moves it in its own PR with `pnpm bump:ad4m`. Run `pnpm verify:ad4m` before merging either. The whole policy is in
`docs/contributing/ad4m-and-deploys.md`.

For active local iteration you can temporarily switch the override to
`"@coasys/ad4m": "file:../ad4m/core"` (then `pnpm install`) so `pnpm run build` in
`ad4m/core` is picked up directly — just remember to switch it back to the pinned npm tag
before committing `package.json`.

Type-only changes (e.g. widening a TS type) don't need any of this — WE's schema types
(`packages/schema-system/shared/src/types.ts`) type dynamic query fields (`where`,
`order`, `include`) as loose `Record<string, unknown>` shapes, so they pass through
as plain JSON regardless of which `@coasys/ad4m` build is installed.

Rust changes to the `ad4m-executor` binary are unaffected by any of this — see below.

---

These patterns apply to TypeScript code in stores, services, tests, and scripts
that work directly with AD4M model classes. They do NOT apply to JSON template schemas.

---

### Looking at something that needs other people

Some UI cannot be reached alone. The call stage solves its layout against the panel's box, so
judging it means dragging a real panel around with a real multi-party call running — which one
person cannot start, and which no unit test can answer.

In a development build the call bar carries a `−  N  +` pair: press `+` and a synthetic
participant with real moving video joins the stage, which re-solves on the click. They join at the
*tile* layer, so the mesh and presence are untouched and this says nothing about signalling — it is
a layout harness. What it does exercise is everything downstream of "there are N participants": the
tiling solve, the spotlight's choice of axis, fit-to-content at each arrangement, the mute badge and
the avatar fallback. The count persists in `localStorage` so it survives a reload, and is on screen
so it cannot be silently left on. See `module-system/call/src/devPeers.ts`.

Worth copying the shape when another module has the same problem. Two things make it safe and
usable: the whole path is behind `import.meta.env.DEV`, spread conditionally into the module's
`slots` and store at *definition* time so a production build contains no node and no callable
action rather than an inert one — and the control is where the thing it changes is, rather than a
console incantation, so the loop it exists to support is not broken by leaving the app to use it.

### Rebuilding — scope it to what changed

A full `pnpm build` walks the whole monorepo and takes minutes. Reserve it for the end of a piece of
work, where the point is to prove the packages still agree. During iteration, rebuild only what you
touched and what depends on it:

```sh
pnpm --filter @we/tokens --filter @we/themes build     # a design-token change
pnpm --filter @we/primitives build                      # a Lit primitive
```

**Do rebuild, though — a stale `dist` is invisible and wastes more time than the build saves.** Three
symptoms worth recognising, all of which have happened here:

- *"I changed the source and the app is unchanged."* The package ships a `dist` and it was not
  rebuilt. Note that packages differ: `@we/template-shell` has no `dist` and is consumed as source,
  so a change there lands immediately, while `@we/module-call` does — which is how the call bar and
  the chrome rail, which are meant to match, ended up different colours from one edit.
- *"The build says it failed but the error names a package I did not touch."* A dependency's types
  moved. Rebuild the chain in dependency order — tokens, then themes, then schema-shared, then
  whatever consumes them.
- *"The adapter's test still sees the old behaviour."* A test that imports `@we/backend-ad4m` by its
  own name resolves through the package's `exports` to `dist`, so it runs the last build rather than
  `src`. Rebuild the package before `pnpm --filter @we/backend-ad4m test`.

To find what is stale rather than guessing:

```sh
for d in $(find packages -name dist -maxdepth 3 -type d | grep -v node_modules); do
  p=$(dirname $d)
  [ -f "$d/index.js" ] && [ -n "$(find $p/src -newer $d/index.js -name '*.ts*' 2>/dev/null | head -1)" ] && echo "STALE: $p"
done
```

Vite caches too. If a rebuilt package still is not picked up by a running dev server, clear
`node_modules/.vite` in the app and restart it — an `ERR_MODULE_NOT_FOUND` or a "does not provide an
export named X" for something that plainly is exported is the tell.

### Running Schema Validation (no build needed)

During codebase work, use the `pnpm validate` script in `schema-system/shared` — it runs
the validator directly from TypeScript source via `tsx`, so no build step is required:

```sh
pnpm --filter @we/schema-shared validate
```

This validates every `.schema.ts` under `packages/app-shell/src/shared/schemas/`,
`packages/templates/` (shell, default, views and showcase) and `packages/module-system/`. Route and
section files that are not named `.schema.ts` are still covered, because the template that composes
them is — the walk descends into whatever a validated schema imports.

Further audits run over the same trees and are easy to miss. They all **import and walk the composed
tree** rather than grepping source, which is the only way to attribute a node that a fragment from
another package contributed:

```sh
pnpm audit:roles                               # a scale position where a role belongs
pnpm audit:surfaces                            # a surface-sunken invisible against its ground
pnpm --filter @we/schema-shared tooltip-audit  # nodes asking the browser for a tooltip via `title`
pnpm --filter @we/schema-shared query-audit    # queries that read a growing list whole
pnpm --filter @we/schema-shared size-audit     # how big each template is, and what it says twice
```

Run them after any template, view or fragment change. A `neutral-600` label is invisible to the
whole contrast layer — never measured against what is behind it — so `role-audit` is the only thing
that will report it.

**The first two gate CI**, so a scale position or an invisible well fails the build rather than
waiting to be noticed. Both are at zero; keep them there.

`role-audit` has a **code half** as well, which the root script runs by default: paths after
`--code` are scanned textually rather than imported, because a colour in a `style={{}}`, an
`.scss` rule or a CodeMirror theme is a string in a file and there is no tree to walk. It reads
four spellings — `var(--we-color-<hue>-<step>)`, `tokenVar('color', '<hue>-<step>')`, a DS prop in
TSX (`color="neutral-800"`), and a raw hex or `rgb()` next to a property that paints — plus a name
handed to `tokenVar` that is **no colour at all**, which compiles to a variable nothing declares and
paints nothing. Four of the editor's dividers were `ui-200`, a ramp that has never existed.

A genuine palette is exempt, with its reason, in one of two places: `CODE_PALETTES` for a whole file
(syntax highlighting, a WebGL scene, a theme's own definitions) or a `role-audit: palette` marker in
the comment above the line, for a file that is mostly chrome and has one swatch. The reasons print on
every run. `EditorOverlay` is the case worth reading: its annotation colours are fixed on purpose,
because they are drawn over the template being edited in whatever theme its author is choosing.

`surface-audit` judges a well by what is behind it rather than by the roles table's wording, which
is looser than the ramp. `surface-sunken` is derived from `page`, so a trough on the page is right;
on `chrome` it is half a lightness point away and **inverts** between light and dark, and on another
`surface-sunken` there is no difference at all. Those two fail.

`query-audit` is the one whose findings are invisible in development and expensive in a real space.
A `$query` with no `limit` re-reads, re-hydrates and re-fingerprints every row of its entity on
every change to that entity, so a list that grows costs O(n²) over a session — fine at twenty rows
and unusable at two thousand, which is a transcript after forty minutes. It reports only what
nothing else bounds: `where.id`, a `scope` with `levels` or `limitPerAnchor`, and a curated
vocabulary all count as bounded. A list that really is read whole on purpose is declared in
`DELIBERATE` in the script, **with the reason**, and the reasons are printed on every run so they
get reviewed rather than accumulated.

Two things about its reach, both worth knowing when adding a schema:

- **Every export in a file is checked**, not just the first one found — so a fragment file
  exporting several sections is judged on all of them.
- **A schema that fails to import is an error**, not a skip, so an unloadable schema cannot look
  identical to a clean one.

`size-audit` measures what a template COSTS to carry around, which is a different question from
whether it is correct. A template is data, and everything downstream pays for its size by the
character: the editor sends the whole schema to a language model on every turn and gets a whole
schema back, the undo history holds a copy per edit, and a template crossing the wire carries all
of it. The hard limit is a model's context window, so a shape written twice is not untidy — it
halves what can be reasoned about.

It reports two things per schema, and they want different answers:

- **`$if sides share N chars`** is a branch pair whose two sides say some of the same thing. This
  is the one to fix, and the fix is usually one node with the condition in its props rather than a
  `$if` holding the content down both sides — the same DOM, half the bytes, no new machinery.
  `buildCard` in `@we/schema-kit` was exactly that, at 150,445 characters a copy in `CardsView`.
- **`repeat ×N`** is a shape written out N times, which is usually a FRAGMENT called N times and
  not a defect at all: a tree cannot name a shape and point at it, so a fragment's output is a
  copy by construction. Reported because it is where the cost is, not because there is an edit.

Neither gates CI. Size is a judgement — a rich template is big — and the honest summary is the
`gzip` ratio beside it: around 4× means a template that says each thing once, and past about 8×
means most of it is repetition. Pass `--show` to print the head of each repeated subtree, without
which the report names a shape it gives no way to find.

Asset imports (`import cover from './cover.jpg'`) resolve to a stub, so a schema that references
an image validates without a bundler. See `src/cli/assetHooks.mjs`.

For per-file validation or other options, see the **Schema Validation** section above.

---

### Schema System — The Grammar Is Closed

**No new value operators, and no new syntax.** The value layer is one expression language —
`{ "$": "count(local.rows) > 0 && local.search != ''" }` — with a closed grammar (references,
comparison, boolean and arithmetic operators, interpolation, a ternary, five comprehension macros)
and an open **function library** (`packages/schema-system/shared/src/expressions/functions.ts`).
There are no other value tokens: a store read, a local read, a comparison, a count, a label — each
is an expression, and a plain string anywhere in a schema is text.

A need for computation the language lacks is answered on the **code** side of the data/code line:

- **A function in the library** — `defineFunction({ name, category, params, doc, example, impl })`.
  Pure and total: wrong-typed input answers with the empty value of its kind, never a throw. Same
  bar as a component: three real uses, not one. The generated context lists it from the registry, so
  there is no doc to update.
- **A host source** — a function this deployment registers in
  `packages/app-shell/src/shared/sources/index.ts`, reachable as `calendarMonth({ … })`.
  Catalogued from the registry into the context and known to the validator.

Neither changes the parser, the validator's grammar, the renderer or the LLM's view of the syntax.
That is the whole reason for the split: the accretion pressure that produced forty operators now
lands where a docblock and a registry entry absorb it.

**Common mistake:** rebuilding a library function out of operators. `count(filter(arr, { id: val })) > 0`
is `val in arr` — hmm, no: it is `arr.exists(x, x.id == val)`; `val in arr` tests the values
themselves. Read the library table in the schema reference before composing.

**Common mistake:** `count(local.items) > 0` as a `$if` condition. Conditions use truthiness; `0`
is falsy, so `count(local.items)` alone is the condition. Keep the comparison where a prop wants a
real boolean — `&&`/`||` already answer with one.

**Handlers stay tokens.** `$action`, `$setLocal`, `$toggleLocal`, `$toggleLocalIn`, `$callLocal`,
`$touch`, `$resetLocal` are the statement layer — about seven verbs, enumerable on purpose because
capability grants and `destructive` flags attach to verbs. Their *arguments* take expressions, and an
expression naming `event`/`arg`/`result` at the top level of `args` or as a `$setLocal` `value`
is evaluated when the handler fires.

---

### Package Conventions

Each package may have a `CONVENTIONS.md` at its root with package-specific rules.
Always read `CONVENTIONS.md` before creating or modifying files in that package.

Key packages with conventions files:
- `packages/design-system/2-themes/THEME_AUTHORING.md` — **read this before writing or editing a
  theme.** A theme is an object of numbers, not a stylesheet: polarity plus a lightness range, hues
  as OKLCH angles (blue is 263, not 220), saturation as a fraction of what the hue can hold, and
  roles pinned only where the parametric default is wrong. Several roles are *derived at apply time*
  — foregrounds, fills and interaction states all correct themselves — so pinning them is overruling
  a measurement, which is occasionally right and usually not.
- `packages/entities/CONVENTIONS.md` — entity authoring: what makes one a block, predicates, @Flag, WeNode, the Entity.create() pattern
- `packages/templates/kit/CONVENTIONS.md` — fragment authoring: what belongs in the kit, extraction threshold, options-object API, body style

---

### Record CRUD Patterns

A record is written through its entity's class. Use the static factory method for creation —
**never** `new Entity() + manual property assignment + save()`.

**Create**
```ts
const space = await Space.create(perspective, {
  uuid: crypto.randomUUID(),
  name: 'My Space',
  description: 'A description',
  visibility: 'public',
});
```

**Read all**
```ts
const spaces = await Space.findAll(perspective);
```

**Read one** (first match by property)
```ts
const space = await Space.findOne(perspective, { where: { name: 'My Space' } });
```

**Read by id** — there is no `findById`; use `findOne` with a `where` clause:
```ts
// ✅ Correct
const space = await Space.findOne(perspective, { where: { id } });

// ❌ Wrong — findById does not exist
const space = await Space.findById(perspective, id);
```

**Update**
```ts
space.name = 'New Name';
await space.save();
```

**Delete**
```ts
await space.delete();
```

**HasMany relations**
```ts
await space.addLocations(locationBlock);     // add<RelationName>(instance)
const locs = await space.getLocations();     // get<RelationName>()
await space.removeLocations(locationBlock);  // remove<RelationName>(instance)
```

Accessor names derive from the `@HasMany` property name: e.g. `locations` → `addLocations` / `getLocations` / `removeLocations`.

---

### Include / Projection Patterns

Relations declared with `@HasMany` or `@HasOne` can be eagerly loaded or counted
in the same query using the `include` option on `findAll` / `findOne`.

**Eager-load a relation (full instances)**
```ts
// signals is declared on WeNode as `signals: string[]`. Include hydrates
// the URIs into Signal instances at runtime, but the static field type stays
// string[] (it reflects the unhydrated state). Cast to read the instances:
const nodes = await Space.findAll(perspective, { include: { signals: true } });
const sigs = nodes[0].signals as unknown as Signal[];
```

**Count a relation (number, no instances fetched)**

Use a `$`-prefixed key with `{ from, count: true }`. The projection key flows
into the result row's type via `IncludeExtras`, so the value is typed directly:
```ts
const spaces = await Space.findAll(perspective, {
  include: { $signalCount: { from: 'signals', count: true } },
});
const n: number = spaces[0].$signalCount ?? 0;
```

**Filtered subset — named `$`-projection returning instances**

Use a `$`-prefixed key with `{ from, where, limit }`. The matched instances are
attached to each result under that key. With `limit: 1` the value is the scalar
or `null`; without a limit (or with limit > 1) it's an array:
```ts
const spaces = await Space.findAll(perspective, {
  include: {
    $mySignal: {
      from: 'signals',
      where: { signalTypeId: 'some-id', author: myDid },
      limit: 1,
    },
  },
});
const mySignal = spaces[0].$mySignal; // Signal | null — typed via IncludeExtras
```

In JSON schema nodes the `where` values are resolved tokens. Signal types have no store accessor —
resolve one by slug from a hoisted `$queries` subscription (see the Signal types pattern above):
```ts
// Schema node — tokens resolved at render time
$queries: { signalTypes: { entity: 'SignalType', subscribe: true } },
// …
include: {
  $myLikeSignal: {
    from: 'signals',
    where: {
      signalTypeId: { $: "find(local.signalTypes, { slug: 'like' }).id" },
      author: { $: 'me.did' },
    },
    limit: 1,
  },
}
// Access the result: { $: 'post.$myLikeSignal.value' }
```

Note: `count: true` works as a plain literal — the typed projection (`TypedIncludeProjection`)
contextually narrows it to the `true` literal, so it needs no `as const`.

---

### Signal Predicate

Signals on any `WeNode` subclass (Space, AgentProfile, TextBlock, …) use the
predicate **`we://signal`** — the relation is declared as:
```ts
@HasMany(() => Signal, { through: 'we://signal' })
signals: string[] = [];
```

When creating a signal manually (not via the ORM relation helpers), pass the
correct predicate to the `parent` option:
```ts
await Signal.create(perspective, { signalTypeId, value }, {
  parent: { id: nodeId, predicate: 'we://signal' },
});
```

**`we://has_signals` is wrong** — it is a different predicate that the ORM does not
know about. Using it creates orphaned links invisible to `include: { signals: true }`.

---

**Anti-pattern — do not use:**
```ts
// ❌ Wrong
const space = new Space(perspective);
space.uuid = crypto.randomUUID();
space.name = 'My Space';
await space.save();

// ✅ Correct
const space = await Space.create(perspective, { uuid: crypto.randomUUID(), name: 'My Space' });
```

---

### Watching the graph from `@we/backend-ad4m`

To hear that something changed in a perspective, subscribe on the executor with `subscribeQuery`
rather than `addListener('link-added' | 'link-removed')`. A link listener receives every link of a
peer-sync burst in JS and filters there. The executor re-runs a subscription only for a diff that
touches one of its predicates, and pushes only when the result changes.

That filter needs SPARQL that writes each predicate out as a full `<iri>`: the executor reads the
predicates from the query text. A variable predicate (even one a `FILTER` pins down), a prefixed
name, or a Prolog query makes it re-run the subscription on every diff. `onProposalsChanged` in
`interpretationAdapter.ts` shows the pattern, and `interpretationDecisions.test.ts` pins its query.

What the SDK and executor do around a subscription, so a watch can rely on it:

- A callback registered after `subscribeQuery` resolves does not receive the initial result — only
  the changes after it.
- After a websocket reconnect, the SDK re-subscribes and hands the current result to every
  callback, so a watch hears a refresh rather than nothing.
- The executor shares one server-side subscription between identical queries from the same user.
  Disposing one ends it for the other too, until the other's 30-second keepalive fails and
  re-subscribes. So hold one subscription per perspective and query, count its holders, and dispose
  it a grace period after the last one lets go — `onProposalsChanged` shows how. The grace matters:
  a dispose racing a fresh subscribe with the same text can land after it and end that one too.

### Reading shapes from `@we/backend-ad4m`

The `PerspectiveProxy` the app holds comes from the SDK copy bundled inside `@coasys/ad4m-connect`,
not from the `@coasys/ad4m` this repo pins. An SDK fix reaches the app only when ad4m-connect
republishes, so measure performance work against that copy, not the workspace one.

In that copy, `getAllShacl()` reads every shape one at a time — `getShaclNames()`, then `getShacl()`
per shape at 3 + P calls for P properties — and it rejects outright when one shape carries a
property transform a newer SDK encoded. For a question about many shapes, ask the executor
once with SPARQL, and read a shape in full only when the answer needs it: `readShapeProperties` and
`getForeignShacl` in `perspectiveHelpers.ts` show how.

---

### Solid + Lit Web Component Event Handling

**How the event type generator works** (`packages/design-system/3-primitives/scripts/generate-framework-declarations.ts`):

For Solid, two categories of event props are generated per element:
- **Native DOM events** → camelCase delegated handlers (`onClick`, `onInput`, `onChange`, etc.) via Solid's synthetic delegation system
- **Custom Lit events** declared in the Custom Elements Manifest → `'on:eventname'` direct listeners (e.g. `'on:select'`, `'on:toggle'`)

The `on:eventname` syntax is Solid's escape hatch for adding a direct `addEventListener` on the host element, bypassing delegation entirely.

**`we-menu-item` — always use `on:select`, not `onClick`**

`we-menu-item` dispatches a `select` CustomEvent (composed, bubbles) when clicked — this is its designed public API. The generated Solid type already includes `'on:select'?: (event: CustomEvent) => void`.

```tsx
// ✅ Correct — uses designed API, already typed, works through shadow DOM + popover
<we-menu-item value={opt.value} on:select={() => handleSelect(opt)}>
  <we-text>{opt.label}</we-text>
</we-menu-item>

// ❌ Wrong — 'on:click' is not in the generated type (TypeScript error)
<we-menu-item value={opt.value} on:click={() => handleSelect(opt)}>

// ❌ Unreliable — onClick uses Solid delegation which may not reach elements
// inside shadow DOM or we-popover's browser top-layer
<we-menu-item value={opt.value} onClick={() => handleSelect(opt)}>
```

**Why delegation fails inside `we-popover`**: Solid's delegated events (`onClick`, etc.) are registered at the Solid root element. Events from inside shadow DOM stacks or the browser's Popover API top layer may not reach the delegation root correctly due to shadow boundary retargeting. Always prefer `on:select` for `we-menu-item` — it adds a direct listener on the host element itself.

**General rule for other web component events**: if you need to listen to a native DOM event (e.g. `click`, `input`) on a `we-` primitive inside a deep shadow DOM context and `onClick`/`onInput` prove unreliable, use a `ref` callback with `addEventListener` directly — this never has delegation issues:
```tsx
<we-some-element ref={(el) => el.addEventListener('click', handler)} />
```

---

### Shadow DOM + Slots: Third-party Library Root Detection

Lit primitives (`we-scroll-area`, `we-popover`, etc.) use Shadow DOM with `<slot>`.
Light-DOM children are slotted through, but their `assignedSlot` property points into
the Shadow Root. Any library that auto-detects its document root by walking up via
`assignedSlot` will end up scoped to the **ShadowRoot** rather than the main document.

**Symptoms when a library is incorrectly scoped to a ShadowRoot:**
- Styles injected by the library don't apply to its own DOM elements (which live in the light DOM)
- `document.activeElement` checks fail because the library checks `shadowRoot.activeElement` instead
- Everything works only after another instance of the same library mounts outside the web component

**Known affected library: CodeMirror 6**

CM6's `getRoot()` follows `assignedSlot` into the Shadow Root. Symptoms: editor shows
only the gutter (unstyled), cursor/focus detection broken. Fix: always pass
`root: containerRef.ownerDocument` to the `EditorView` constructor. `ownerDocument`
skips the slot chain and always returns the main `Document`.

```tsx
// ✅ Always do this when mounting a CodeMirror EditorView inside any we-* component
view = new EditorView({
  parent: containerRef,
  root: containerRef.ownerDocument,
  ...
});
```

**General rule for other libraries**: if a third-party library accepts a `document`,
`root`, or `container` option and uses it for style injection or focus detection,
pass `element.ownerDocument` explicitly rather than letting the library auto-detect.