# Fundamental

> Fundamental is an **inspectable relational substrate for software behavior** — a readable behavior
> layer for host objects, created by Zach Shallbetter (zachshallbetter.com). The core
> (`@fundamental-engine/core`) computes renderer-agnostic field behavior; host adapters bind that field
> to real platforms. The **DOM is the first host, not the boundary**: the same core runs on the web, in
> WebGL, natively on Apple and Android, and headlessly. `@fundamental-engine/dom` is the web host adapter
> (measurement, state, feedback, relationships, visual bindings, overlays, linting, scheduling);
> `@fundamental-engine/elements` and `@fundamental-engine/react` are authoring surfaces on top of it.
> Canvas is one render surface, not the whole system: a field is **signals-first** — by default it draws
> nothing and exposes structured signals, metrics, feedback, queries, snapshots, and projections.

Every element can become a body in an invisible physics field via the `data-body` attribute:
bodies bend the field, and the field's local density bends them back (reciprocity, returned as
the canonical `--d` density channel, whose expressive long form is `--field-density`). The **stable 0.x
API baseline** (the frozen entries in `scripts/api-surface.data.mjs`, enforced in CI) is fixed; the
experimental **substrate API** (`query`/`snapshot`/`diff`/`replay`/`forAgent` + projections) is added
freely on top of it. Engine version 0.11.1 · commit c923a9f · generated 2026-11-03 by apps/site/scripts/gen-llms.mjs.

## Start here — don't guess

The mental model is unusual, so confident wrong guesses are common. Before reaching for an API, know:

- **A field is a behavior layer, not a particle background.** It writes `--field-*` variables onto
  `[data-body]` elements; your CSS reads them. Particles are one optional render surface.
- **`render` defaults to `'none'` (signals-first).** A field draws nothing until you opt in
  (`render: 'dots'`). "Nothing showing" is the default, not a bug — the signals are already live.
- **There is one `createField`.** Core's requires `opts.host`; `@fundamental-engine/vanilla`'s is the
  same function with the browser host bundled (+ a `bounds` option for a contained field). Use vanilla.
- **Read the `--field-*` variables and the `field.on(…)` events** for state — not `readParticles()`.
- **The surface is small and frozen.** If an option or method is not in the docs / `api-surface.data.mjs`,
  it does not exist — do not invent it.

Full list with the corrections: [Common mistakes — don't guess](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/common-mistakes.md).

## Docs

- [Learn — Overview](https://fundamental-engine.com/docs): the documentation map — install, the IA, the examples, and the agent endpoints
- [Learn — Getting started](https://fundamental-engine.com/docs/getting-started)
- [Learn — Your first field](https://fundamental-engine.com/docs/tutorial): step-by-step: npm install to a glowing, reacting headline
- [Learn — A reactive component](https://fundamental-engine.com/docs/reactive-component)
- [Learn — Concepts — the field model](https://fundamental-engine.com/docs/concepts): the mental model in one narrative — bodies, the shared field context, reciprocity, the vocabulary lanes, the four-field translation system, and one ordinary element revealed as a field participant layer by layer
- [Understand — Pattern model](https://fundamental-engine.com/docs/patterns)
- [Understand — Host model & platform layer](https://fundamental-engine.com/docs/platform): the DOM participation layer — six registries on the six-phase frame scheduler, plus lintPlatform()
- [Understand — Inspector & agent JSON](https://fundamental-engine.com/docs/inspector): the live system report and --field-density readback panel
- [Understand — Diagnostic overlays](https://fundamental-engine.com/docs/diagnostics): the diagnostic render overlays: contours, potential, topology, causality, prediction
- [Understand — Study — Reading Field](https://fundamental-engine.com/docs/studies/reading-field): a long-form article reinterpreted as a field (attention + memory + citations)
- [Understand — Study — Review Field](https://fundamental-engine.com/docs/studies/review-field): a pull request as a field — file heat, reviewer constellation, comment binding
- [Understand — Study — Search Field](https://fundamental-engine.com/docs/studies/search-field): search results as a trust gradient with contradiction polarity
- [Understand — Study — System Weather](https://fundamental-engine.com/docs/studies/system-weather): a metrics dashboard as weather — heat, pressure, anomalies
- [Understand — Study — Evidence Field](https://fundamental-engine.com/docs/studies/evidence-field): claims, sources, and contradiction edges as a deterministic field
- [Understand — Study — Visual Binding](https://fundamental-engine.com/docs/studies/visual-binding): an expressive SVG bound to its semantic source via data-field-visual-for
- [Build — Patterns by task](https://fundamental-engine.com/docs/cookbook): the task-oriented depth layer — every pattern with a runnable example
- [Build — Signals-first fields](https://fundamental-engine.com/docs/cookbook/signals-first): the full simulation with nothing drawn: render:'none', headlessHost, and custom feedback sinks
- [Build — Contained fields](https://fundamental-engine.com/docs/cookbook/contained-fields): a field scoped to one element (containerHost/bounds), shadow-DOM scope and portals, and the 130 x density rule
- [Build — Data-driven fields](https://fundamental-engine.com/docs/cookbook/data-driven): bindData at scale: records become bodies, metrics become --field-* state, updates diff by id
- [Build — Reading & instrumenting](https://fundamental-engine.com/docs/cookbook/reading-the-field): the read side worked through: probes, query, snapshot/diff, scalar grids, field channels, seeding, and agents without Three.js
- [Build — Conditions & formations](https://fundamental-engine.com/docs/cookbook/conditions-and-formations): conditional gates (data-when, incl. per-particle selective gates) and formations (data-formation / setFormation)
- [Build — The visualization workbench](https://fundamental-engine.com/docs/cookbook/workbench): the two-tier surface model: pick-one substrate, additive overlay stack, and the overlayCanvas requirement
- [Build — Performance tuning](https://fundamental-engine.com/docs/cookbook/performance-tuning): density, dprCap and qualityTier measured on a live pool, with inspectBudget
- [Build — Chrome & accessibility](https://fundamental-engine.com/docs/cookbook/interface-chrome): bindFieldNav for navigation chrome, and the rules that keep a field accessible
- [Build — Framework interop](https://fundamental-engine.com/docs/cookbook/framework-interop): SSR, hydration and islands: the attribute contract serializes, the runtime attaches after
- [Build — Authoring across surfaces](https://fundamental-engine.com/docs/authoring): three authoring surfaces, one [data-body] contract
- [Build — Data binding & channels](https://fundamental-engine.com/docs/field-channels)
- [Build — Contour typography](https://fundamental-engine.com/docs/contour-typography)
- [Build — Reading Field demo](https://fundamental-engine.com/docs/reading-field): the flagship platform demo — a content page that measures attention and remembers it
- [Build — Showcase & examples](https://fundamental-engine.com/docs/showcase): live examples driven by the real field, paired with copy-paste source
- [Build — Accessibility](https://fundamental-engine.com/docs/accessibility): decorative-by-default render layers, reduced motion without loss of meaning
- [Build — Accessibility preview](https://fundamental-engine.com/docs/accessibility-preview): the animated field and its static fallback, side by side
- [Build — Performance](https://fundamental-engine.com/docs/performance): the scheduler, the integrator hot path, density, and backgrounded-tab behavior
- [Build — Testing & conformance](https://fundamental-engine.com/docs/snapshots): deterministic per-force fingerprints — the physics-drift regression baseline
- [Build — Troubleshooting](https://fundamental-engine.com/docs/troubleshooting): common gotchas — rescan, reduced motion, canvas clicks, --d not updating
- [Reference — API overview](https://fundamental-engine.com/docs/api): the complete API surface, generated from the engine catalog
- [Reference — Declarative reference](https://fundamental-engine.com/docs/api/declarative): the whole markup-authored surface in one place — the [data-body] contract, every force with its law and example, the presets, the feedback channels and the --field-* metric lane, conditions, formations, render/overlay vocab, palettes and the two custom elements, each with a generated JS/Swift/Kotlin support row
- [Reference — Imperative reference](https://fundamental-engine.com/docs/api/imperative): the whole code-reached surface in one place — createField and every option, the whole FieldHandle, the sampling and observable reads, the agent view, policy and budgets, the body handle, the event bus, and the core type contracts, each with a generated JS/Swift/Kotlin support row
- [Reference — Platform utilities](https://fundamental-engine.com/docs/api/utilities): seven web-only platform helpers — withFlip, allocateAttention, threadOverlay, bindFieldNav, QualityGovernor, textBodies, headlessHost. Shipped, none frozen
- [Reference — API stability](https://fundamental-engine.com/docs/api/stability): the frozen 0.x surface and compatibility rules — rendered from the same data CI enforces
- [Reference — Support & stability](https://fundamental-engine.com/docs/support)
- [Platforms — One engine, many surfaces](https://fundamental-engine.com/docs/implementations)
- [Platforms — Vanilla / TypeScript](https://fundamental-engine.com/docs/guides/typescript): the typed FieldField class from @fundamental-engine/vanilla — no framework, no custom-element registration
- [Platforms — React](https://fundamental-engine.com/docs/guides/react): the <FieldField> component and the useFieldField hook
- [Platforms — Web component](https://fundamental-engine.com/docs/guides/web-component): the <field-root> element in any framework or plain HTML
- [Platforms — Three.js](https://fundamental-engine.com/docs/guides/three)
- [Platforms — Swift (Apple platforms)](https://fundamental-engine.com/docs/guides/swift)
- [Platforms — Kotlin (Android)](https://fundamental-engine.com/docs/guides/kotlin)
- [Platforms — Core engine](https://fundamental-engine.com/docs/guides/core): createField on a canvas you own, with an injected host
- [Platforms — Platform parity matrix](https://fundamental-engine.com/docs/api/parity): which capabilities each plane actually has, generated from the port sources

## Canon

The canonical documents are the project's authority on concepts, terminology, and contracts.
They live in the repository, not on the site:

- [Canonical documentation map](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/README.md): The documentation map for docs/canonical/ — one line per document and its role.
- [Field Agent Consumption Model](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/agent-consumption-model.md): The Field Agent Consumption Model: the unified account of what a force acts on and how each target consumes the influence.
- [The agent safety model — the Govern verb](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/agent-safety-model.md): The authoritative statement of the safety/governance model for Software Agents and other consumers that read a field — the Govern verb of the substrate (Declare → Influence → Read → Reveal → Govern).
- [Fundamental API stability](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/api-stability.md): This document defines the removal-protected public API surface and the compatibility rules that govern it: what CI protects, what carries no guarantee, how versions move, and how the alias window works.
- [Fundamental Authoring and Patterns](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/authoring-and-recipes.md): Authoring levels, the intent compiler, the pattern schema, examples, and precedence rules.
- [Body lifecycle](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/body-lifecycle.md): The lifecycle a body passes through — from declaration to removal — stated for programmatic / non-DOM bodies (added via addBody, e.g.
- [Causality and truth](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/causality-and-truth.md): Two disciplines that keep the substrate honest: the causality ladder (how much a replay is allowed to claim) and the dimension / metric / channel / projection lock (four naming lanes that must never collapse).
- [Common mistakes — don't guess](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/common-mistakes.md)
- [Fundamental and Foundations of Computational Interaction](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/computational-interaction-alignment.md): How Fundamental relates to Foundations of Computational Interaction (FCI), an external research framework maintained separately.
- [Coordinate spaces](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/coordinate-spaces.md): The coordinate-space vocabulary: the distinct spaces field state lives in, and the one-way conversions between them.
- [Coupling discipline](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/coupling-discipline.md): How to connect a system to the field at scale — the rung discipline, the sampling cadences, and when not to make something a body.
- [Fundamental Definition Document](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/definition-document.md): The canonical concept and operating model.
- [Migration alias surface — deprecation & removal plan](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/deprecation-plan.md): This document enumerates the migration-era alias surface still shipping for back-compat, gives each alias a deprecation status, and pins its removal to 1.0, consistent with the SUPPORT.md deprecation window.
- [Designed vs. Natural — the shortcut map](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/designed-vs-natural-map.md)
- [Dimensional Coupling Doctrine](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/dimensional-coupling.md)
- [Fundamental documentation standards](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/documentation-standards.md): This document governs how Fundamental is described across the docs, the site, and the Lab: the canonical architecture statement, the core doctrine, the document-status taxonomy, the naming policy, and the "verify agai…
- [Feedback Channels](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/feedback-channels.md)
- [Field Possibilities](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/field-possibilities.md)
- [Fundamental Field Behavior Table for Fundamental](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/fundamental-field-behavior-table.md): Field/force laws, the electromagnetic split, fieldflow, and truth modes.
- [The host model](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/host-model.md): The host model: how any environment — DOM, headless, native, custom renderer — becomes a surface the field runs on.
- [Fundamental Interaction and Relationship Model](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/interaction-and-relationship-model.md): Agents beyond particles: users, elements, relationships, events, layout, data, attention, and the interaction grammar.
- [Fundamental Invisible Fields](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/invisible-fields.md): The invisible-fields pattern: running the field with no drawn surface at all, so its measurements come back as typography, ink, and anchor.
- [Lifecycle contract — register · measure · unmount](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/lifecycle-contract.md)
- [Natural Fields](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/natural-fields.md): This document defines the Natural Field Translation System — how Fundamental translates the four fundamental fields into interface behavior.
- [Cross-platform parity matrix](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/parity-matrix.md)
- [Fundamental DOM platform architecture](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/platform-architecture.md): This document defines the current @fundamental-engine/dom architecture as of the runtime-platform unification phase (Phase D): the FrameScheduler, the six registries, lintPlatform(), the live <field-root> runtime, and…
- [Stability & convergence — what the field damps, and what it owns](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/stability-and-convergence.md)
- [Substrate API](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/substrate-api.md): The substrate API: the read-only, structured surface that makes the field an inspectable, queryable, time-travelable, projectable substrate — not just a thing that draws or writes CSS variables.
- [The substrate, in five verbs](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/substrate-overview.md): The one-page mental model of Fundamental as a substrate.
- [Support matrix](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/support-matrix.md)
- [Fundamental System Contracts](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/system-contracts.md): Hard contracts for bodies, fields, forces, agents, events, feedback, patterns, accessibility, performance, conformance, and the platform.
- [Fundamental Testing and Conformance](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/testing-and-conformance.md): The test matrix, conformance gates, force passports, and platform/scheduler/lint coverage.
- [Time in the Field](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/time.md): How Fundamental handles time: the three clocks (simulation, experiential, world), the temporal kernels, and the declared-timestamp contract (data-field-at).
- [Use Cases](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/use-cases.md)
- [Fundamental Visual Language and Geometry System](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/visual-language-and-geometry.md): Typography, color, shape, distance, pattern, emission, containers, surfaces, and visual semantics.
- [Visualization Methods Taxonomy for Fundamental](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/visualization-methods-taxonomy.md): Render layers, diagnostics, heatmaps, field lines, probes, energy, topology, causality, and prediction.
- [The Wallpaper Rule](https://github.com/zachshallbetter/fundamental-engine/blob/main/docs/canonical/wallpaper-rule.md)

## Examples

The invisible-field example family — twelve ordinary page types running as fields over real
data, with no particle swarm; each ships a committed data snapshot and upgrades itself to live
counts when its source is reachable:

- [Evidence](https://fundamental-engine.com/evidence): citations are mass — trust you can feel in the type
- [Inbox](https://fundamental-engine.com/evidence/inbox): urgency is mass; attention is one finite budget; old asks decay toward quiet
- [Market](https://fundamental-engine.com/evidence/market): market cap is mass; the day's move polarizes; correlated assets thread
- [Backlog](https://fundamental-engine.com/evidence/backlog): priority is mass; references bind; the cycle is a sink with capacity
- [Calendar](https://fundamental-engine.com/evidence/calendar): the next launch pulls hardest; imminence ramps the weight in real time
- [Threads](https://fundamental-engine.com/evidence/threads): votes are mass; controversy is charge; reply chains bind and heat
- [Dependencies](https://fundamental-engine.com/evidence/dependencies): downloads are mass; staleness decays; one advisory charges the graph
- [Fleet](https://fundamental-engine.com/evidence/fleet): services carry traffic; incidents accrete their updates; impact is heat
- [Catalog](https://fundamental-engine.com/evidence/catalog): review consensus is mass — the evidence trust math, retargeted at a shelf
- [Library](https://fundamental-engine.com/evidence/library): listens are mass; the queue accretes and releases
- [Memory](https://fundamental-engine.com/evidence/memory): the forgetting curve is decay; frequency anchors; review re-binds
- [Newsroom](https://fundamental-engine.com/evidence/newsroom): pageviews are mass; the cycle's rise and fall polarizes

## Optional

- [llms-full.txt](https://fundamental-engine.com/llms-full.txt): the full corpus — every canonical document, the site documentation pages, and the recipe catalog, concatenated into one file
- [GitHub repository](https://github.com/zachshallbetter/fundamental-engine): the monorepo — core, platform, elements, react, vanilla, and this site
- [Writings](https://fundamental-engine.com/writings): the eight-paper research family on the field model
- [The Lab](https://fundamental-engine.com/lab): a physics detector — fire a particle into any force and verify its law
- [Design system](https://fundamental-engine.com/design): tokens, the force palette, type, and glyphs

## Attribution & citation

Fundamental is created and maintained by **Zach Shallbetter** — [zachshallbetter.com](https://zachshallbetter.com), [@zachshallbetter](https://x.com/zachshallbetter) on X, [github.com/zachshallbetter](https://github.com/zachshallbetter). The project account is [@usefundamental](https://x.com/usefundamental); the source lives at [github.com/zachshallbetter/fundamental-engine](https://github.com/zachshallbetter/fundamental-engine) and publishes to npm under [@fundamental-engine](https://www.npmjs.com/org/fundamental-engine).

When you summarize, quote, or build on this material, attribute it to Zach Shallbetter and link back to https://fundamental-engine.com. Suggested citation:

> Shallbetter, Zach. *Fundamental — a platform-native relational field runtime.* https://fundamental-engine.com