API reference

--field-* metrics

The field writes measured state back to each body as CSS custom properties. Style with them directly — no JavaScript readback needed. The primary seven are updated every frame by the core loop; the sub-variables are written by the agent layer on interaction ticks.

How readback works

When the field runs, each registered body receives its own set of --field-* properties on its style attribute. Because they are scoped to the element, you can read them in CSS with var(--field-density) — no need to query the handle or listen for events.

/* density drives visual weight — no JS needed */
.card {
  scale: calc(1 + var(--field-density, 0) * 0.08);
  box-shadow: 0 0 calc(var(--field-heat, 0) * 24px) rgba(77,163,255,0.35);
}

You can also read a metric from JavaScript via getComputedStyle(el).getPropertyValue('--field-density'), or use it as a data-feedback target to write it back as a discrete state attribute.

Primary metrics

Written every frame by the core loop. Available immediately when a body is registered.

--field-density 0–1every frame

Eased fraction of nearby matter gathered at this body. The primary field intensity signal — high density means the body is a convergence point.

Use for Drive visual weight, font size, bloom, or z-elevation. The most reliable general-purpose readback.

--field-attention 0–1every frame

Accumulated interaction-weighted attention at this body — a composite of recency, dwell, and interaction events.

Use for Distinguish hot items (read, clicked, hovered) from cold ones without a separate state tracker.

--field-heat 0–1every frame

Thermal intensity at the body — rises with interaction events and decays over time. Distinct from density: heat is event-driven, density is proximity-driven.

Use for Highlight recently-interacted elements. Pairs with the `thermal` force for visible heat traces.

--field-pressure 0–∞ (typically 0–5)every frame

Local force pressure — the net magnitude of forces acting on this body. High pressure signals contested or highly attracted positions.

Use for Surface overloaded zones in dashboards. Flag items under competing forces.

--field-entropy 0–1every frame

Disorder of the local field — high entropy means inconsistent or competing forces. Low entropy means stable, predictable behavior.

Use for Show field stability. Trigger warnings (`--field-entropy-warning: 0.72`) when the layout becomes chaotic.

--field-coherence 0–1every frame

Inverse of entropy — how aligned the local forces are. A coherent field is one where bodies move in consistent directions.

Use for Validate that a recipe produces stable behavior. Surface consensus vs. conflict.

--field-memory 0–1every frame

Decaying trace of past attention — a long-window integral that fades when the body is ignored. Distinct from `--field-attention` (which is current-weighted).

Use for Show recency or staleness. An item not visited in a while will have high memory decay — use it for "stale" badges or fade-out.

Agent-layer sub-variables

Written by the agent layer on interaction ticks — not every frame. May be absent until the first tick.

--field-pull-x -∞–∞ (px/frame)every frame

Net horizontal force vector acting on this body — the signed sum of all x-axis forces this frame.

Use for Read raw directional pressure. Rarely needed for styling; more useful for custom overlay renderers.

--field-pull-y -∞–∞ (px/frame)every frame

Net vertical force vector acting on this body.

Use for Pair with `--field-pull-x` for directional indicators or custom arrow overlays.

--field-attention-share 0–1per agent tick

This body's fraction of the total attention budget across the field. A normalised view of competitive attention.

Use for Compare items on equal footing — useful for analytics-style readouts where you want relative, not absolute, scores.

--field-attention-rank 0–N (integer)per agent tick

Ordinal rank of this body by attention within the field. 0 = highest-attended.

Use for Drive visual priority tiers (top-3 highlighted, rest dimmed) without threshold-tuning.

--field-related-attention 0–1per agent tick

Attention propagated from linked bodies — if a related body is being attended, this rises. Requires a relationship defined via `data-field-relation`.

Use for Highlight contextually relevant siblings without explicit user interaction on each one.

--field-path-use 0–1per agent tick

How frequently this body appears on high-traffic paths through the field graph. High path-use bodies are structural connectors.

Use for Show navigational importance — items used as stepping-stones score high regardless of direct attention.

--field-user-wake 0–1on interaction events

Rises to 1 on any user interaction near this body and decays quickly. A pure recency-of-touch signal.

Use for Trigger micro-animations or feedback only on recent touch — distinct from `--field-heat` which accumulates.

--field-layout-shift 0–1on position change

Normalised magnitude of the most recent position displacement. Non-zero during and briefly after a FLIP-style reposition.

Use for Coordinate CSS transitions with field-driven layout changes. Lets the stylesheet know "a shift just happened here".