Fundamental v0.10.1

Documentation

Build with Fundamental.

A platform-native relational field runtime; the DOM is its first host — framework-agnostic, with a renderer-agnostic core. This page is the map; every card below is drawn from the same source as the sidebar, and every card is a body in this page's field. Engage one.

Install

Most projects want @fundamental-engine/vanilla — the framework-free door, host-bundled so createField works with no wiring. React users want @fundamental-engine/react. The other packages are there when you need them; the core engine has zero runtime dependencies.

  • Plain JS/TS, or any framework, no opinion? → @fundamental-engine/vanilla — start here.
  • React app? → @fundamental-engine/react
  • Vue / Svelte / Angular / plain HTML? → @fundamental-engine/elements — the <field-root> custom element.
  • Your own renderer, or a canvas you own? → @fundamental-engine/core — you supply the host.
npm i @fundamental-engine/vanilla the framework-free FieldField class, mountField(), and host-bundled createField. The recommended starting point.
npm i @fundamental-engine/react the <FieldField> React component + useFieldField hook
npm i @fundamental-engine/elements the <field-root> web component — drops into any framework or plain HTML
npm i @fundamental-engine/core the renderer-agnostic engine — when you own the canvas and wire your own host

No build step? Import straight from a CDN: import { createField } from 'https://esm.sh/@fundamental-engine/vanilla'. Install the specific package you need — the umbrella packages were retired in 0.7.0. In a hurry? Your first field goes from install to a reacting headline in eight steps.

Reactive, not ambient

Fundamental is a behaviour layer, not a background effect. A field reads each [data-body]'s position every frame and writes the local field back as --field-* CSS variables your styles consume — so it reacts to your layout and engagement, not to the cursor over a decorative canvas. Since #538 it is signals-first: a field draws nothing by default — it runs the simulation and emits signals, and you opt into a visible surface (render: 'dots', or the warped grid) when you want one. The particles are one optional surface; the signals are the point.

One createField — which door?

There is one createField. The @fundamental-engine/core export is the renderer-agnostic primitive and requires opts.host; the @fundamental-engine/vanilla export is the same function with browserHost() bundled for you (and a bounds option). Same function, host supplied or not — not three different APIs. Pick the door that matches your stack:

  • Plain TS/JS, any framework → new FieldField(opts) or createField(canvas, opts) (vanilla) — host auto-supplied, signals-first.
  • Scope the field to a component → new FieldField({ bounds: el }) — the field lives in the element, not the window.
  • HTML / Vue / Svelte / Angular → <field-root> — add render="dots" for particles, omit it for signals-only.
  • React → <FieldField> / useFieldField().
  • Your own renderer, or a canvas you own → createField(canvas, { host }) (core) — requires a host.
  • Declared metrics on real bodies, no canvas → applyPattern(root, pattern, { bodies }) (dom) — the signals-only metric pipeline; bind data with bindData.

Copyable, end to end: a reactive component (no particles) for the contained, signals-only path, and your first field for the window path.

Choose your path

Start where you are. The normal developer path — install, then build — is first; the substrate model is here when you want to read, reveal, and govern the field.

Substrate demos

The substrate is legible three ways — as an agent-readable graph, as live physics with an agent-json readout, and as ordinary pages that measure themselves. All three run the real engine.

The map

The documentation, whole. These groups mirror the sidebar exactly — both render from one navigation tree, so this map cannot drift from it.

Start

  • Overview this page — the map
  • Getting started install to a first field, the shortest route in
  • Your first field npm install to a glowing, reacting headline, step by step
  • A reactive component a contained, signals-only component — no particles
  • Concepts bodies, the shared field context, reciprocity — the mental model
  • Natural fields gravity → priority, EM → polarity, strong → binding, weak → transformation
  • Narrative walkthrough one ordinary element, revealed as a field participant layer by layer

Build

Reference

Examples

The examples

The applied tier. Twelve ordinary page types — an inbox, a market, a backlog, a front page — run as fields over real data, with no particle swarm: the field's measurements come back as type, ink, and anchor. Each ships a committed data snapshot, upgrades itself to live counts when its source is reachable, and says which mode it is in.

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

Start with Evidence — the family's front door →

For agents

The docs ship as plain text too — /llms.txt is this map in the llms.txt format, and /llms-full.txt is the full canonical documentation concatenated; the field's agent consumption model, applied to its own docs. For a live agent-readable example, see AI Evidence — claims, sources, relationships, and confidence as a field an agent can read.