@fundamental-engine/vanilla 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Shallbetter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @fundamental-engine/vanilla
+
+**The framework-free door to [`@fundamental-engine/core`](../core)** — a reciprocal DOM-physics field as a typed
+`FieldField` class and the imperative `mountField()`. Elements you mark with `data-body` become forces;
+the single background field reacts to them, and its density reacts back. No custom-element
+registration, no framework dependency, no import side effects.
+
+→ Live manual, Lab, and gallery at **[fundamental-engine.com](https://fundamental-engine.com)**.
+
+## Install
+
+```sh
+npm i @fundamental-engine/vanilla
+```
+
+The only dependency is the zero-dependency core plus [`@fundamental-engine/platform`](../platform) (which supplies
+the browser host). Reach for this from plain TypeScript, or any stack where you want to drive the field
+by hand.
+
+## The class
+
+```ts
+import { FieldField } from '@fundamental-engine/vanilla';
+
+const field = new FieldField({ accent: '#4da3ff', render: 'dots' });
+field.setFormation('wells');
+field.burst(window.innerWidth / 2, 200);
+// field.scan();    // re-pick-up bodies after a DOM change
+// field.destroy(); // stop the loop and remove the managed canvas
+```
+
+`new FieldField()` builds a fixed, full-viewport canvas behind your page and starts the engine on it.
+It takes every `FieldOptions` value, implements the full `FieldHandle` surface, and exposes the
+`canvas` it runs on — the same engine the `<field-root>` custom element and the React `<FieldField>`
+wrap.
+
+### Options (`FieldOptions`)
+
+| Option | Type | Effect |
+|---|---|---|
+| `accent` | `string` | base hue (any CSS color) |
+| `density` | `number` | particle density multiplier |
+| `render` | `'dots' \| 'trails' \| 'links' \| 'metaballs' \| 'voronoi' \| 'streamlines'` | underlay render method |
+| `palette` | `string \| string[]` | named palette (`ours` / `heatmap` / `infrared` / `spectrum`) or colors |
+| `waves` | `boolean` | wave propagation |
+| `mass` | `boolean` | first-class mass in the integrator |
+| `attention` · `causality` · `heatmap` | `boolean` | diagnostics |
+| `canvas` | `HTMLCanvasElement` | drive a canvas you own (the field won't create/remove one) |
+
+### Methods (`FieldHandle`)
+
+| Method | Use |
+|---|---|
+| `scan()` / `rescan()` | re-read `[data-body]` elements after the DOM changes |
+| `setAccent(hex)` · `setPalette(p)` | recolor live |
+| `setFormation(name)` | arrange particles into a named formation |
+| `setRender(mode)` · `setOverlay(mode)` | underlay (behind content) / overlay (in front) |
+| `setAttention(on)` · `setCausality(on)` · `setHeatmap(on)` | toggle diagnostics |
+| `burst(x, y, hex?)` · `flowTo(x, y)` · `clearFlow()` | impulses and a movable focus |
+| `threads(list)` | draw relationship threads between bodies |
+| `destroy()` | stop the engine (and remove the managed canvas, if it created one) |
+
+> **Client only.** The field is a browser effect: `new FieldField()` (and `mountField()`) touch
+> `document` right away and throw a clear error during server-side rendering. In Next.js, Astro,
+> SvelteKit, and similar, construct it on the client — inside `useEffect`, `onMount`, or a "client
+> only" boundary.
+
+Drive a `<canvas>` you own instead by passing it — then the field never creates or removes a canvas,
+and `destroy()` only stops the engine:
+
+```ts
+const field = new FieldField({ canvas: myCanvas, density: 1.2 });
+```
+
+## The function
+
+If you prefer a plain factory over a class, `mountField()` returns the bare `FieldHandle`:
+
+```ts
+import { mountField } from '@fundamental-engine/vanilla';
+
+const field = mountField({ render: 'trails' });
+// field.destroy() also removes the canvas it created.
+```
+
+To run the engine on a `<canvas>` with no managed wrapper at all, the host-bundled `createField` is
+re-exported (this one supplies `browserHost()` for you, unlike the core primitive):
+
+```ts
+import { createField } from '@fundamental-engine/vanilla';
+
+const field = createField(document.querySelector('canvas')!, { accent: '#2dd4bf' });
+```
+
+## Marking bodies — the `data-body` vocabulary
+
+| Attribute | Meaning |
+|---|---|
+| `data-body="attract"` | the force token (`attract`, `gravity`, `charge`, `sink`, …) |
+| `data-strength` | how hard it bends the field |
+| `data-range` | radius of influence, in px |
+| `data-feedback` | opt in to receiving `--field-*` variables back |
+| `data-absorb` / `data-max` | for `sink` bodies: accretion load and capacity |
+
+Call `field.scan()` after adding new `[data-body]` elements so the engine picks them up.
+
+## Catalog
+
+For building UI around the field (a force picker, a legend), the catalog data is re-exported so you
+need no second install: `FORCES`, `FORMATIONS`, `CONDITIONS`, `PALETTE`.
+
+```ts
+import { FORCES, FORMATIONS } from '@fundamental-engine/vanilla';
+```
+
+## Recipes & data binding
+
+To apply a named recipe over your markup or bind data to the field, use `applyRecipe()` / `bindData()`
+from [`@fundamental-engine/platform`](../platform); browse all 64 recipes at
+[`/docs/gallery`](https://fundamental-engine.com/docs/gallery).
+
+## Related
+
+[`@fundamental-engine/core`](../core) · [`@fundamental-engine/platform`](../platform) · [`@fundamental-engine/elements`](../elements)
+· [`@fundamental-engine/react`](../react) · the [documentation map](../../docs/README.md).
+
+## License
+
+MIT © Zach Shallbetter

package/dist/field.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `FieldField` — the reciprocal DOM-physics field as a typed class, for plain TypeScript
+ * apps that want object-oriented ergonomics without a framework or a custom element.
+ *
+ * `new FieldField()` builds a managed, full-viewport canvas and starts the engine on it;
+ * pass `{ canvas }` to drive a `<canvas>` you own instead. The class implements the full
+ * `FieldHandle` surface, so an instance is type-compatible anywhere a handle is expected,
+ * and it exposes the `canvas` it renders to.
+ *
+ * ```ts
+ * import { FieldField } from '@fundamental-engine/vanilla';
+ *
+ * const field = new FieldField({ accent: '#4da3ff', render: 'dots' });
+ * field.setFormation('wells');
+ * field.burst(window.innerWidth / 2, 200);
+ * // field.scan(); field.destroy();
+ * ```
+ */
+import { type AtomPayload, type FieldHandle, type FieldOptions, type ThreadLink, type FlowOptions } from '@fundamental-engine/core';
+export interface FieldFieldInit extends FieldOptions {
+    /** drive a `<canvas>` you own; when omitted, a managed full-viewport canvas is created
+     *  (and removed again by `destroy()`). */
+    canvas?: HTMLCanvasElement;
+    /** where to append the managed canvas; ignored when you pass your own `canvas`. */
+    target?: HTMLElement;
+}
+export declare class FieldField implements FieldHandle {
+    /** the `<canvas>` the field renders to — the one created for you, or the one you passed. */
+    readonly canvas: HTMLCanvasElement;
+    private readonly field;
+    /** did this instance create the canvas (and so should remove it on `destroy()`)? */
+    private readonly managed;
+    constructor(init?: FieldFieldInit);
+    /** (re)scan the document for `[data-body]` bodies after a layout change. */
+    scan(): void;
+    /** alias of `scan`. */
+    rescan(): void;
+    /** recolor the travelling accent (§9). */
+    setAccent(hex: string): void;
+    /** swap the accent's color template live: a built-in name or custom hex stops (§9). */
+    setPalette(palette: string | readonly string[]): void;
+    /** switch the global formation (§7). */
+    setFormation(name: string): void;
+    /** toggle conserved attention (§2.4) live — one finite strength budget. */
+    setAttention(on: boolean): void;
+    /** toggle cross-boundary causality (Concept 4) live — density spills to neighbours. */
+    setCausality(on: boolean): void;
+    /** toggle the density heatmap layer (field-systems H1) live. */
+    setHeatmap(on: boolean): void;
+    /** switch the underlay render mode (§20.6) live. */
+    setRender(mode: Parameters<FieldHandle['setRender']>[0]): void;
+    /** render a field-structure visualization on the overlay surface (in front of content). */
+    setOverlay(mode: Parameters<FieldHandle['setOverlay']>[0]): void;
+    /** wire glowing connector lines between a set, or clear with null (§10). */
+    threads(list: ThreadLink[] | null): void;
+    /** a discrete one-shot: shove + heat matter near (x, y), optionally tinting it (§11). */
+    burst(x: number, y: number, hex?: string): void;
+    /** place/move a dynamic flow focus the field bends toward — pulls matter, curves the streamlines. */
+    flowTo(x: number, y: number, opts?: FlowOptions): void;
+    /** remove the flow focus. */
+    clearFlow(): void;
+    seed(atoms: readonly AtomPayload[]): void;
+    atomAt(x: number, y: number): AtomPayload | null;
+    focusAt(x: number, y: number): AtomPayload | null;
+    clearFocus(): void;
+    particleCount(): number;
+    /** copy live particle state into `out` (stride 5: x, y, z, heat, size); returns the count written. */
+    readParticles(out: Float32Array): number;
+    energy(): {
+        kinetic: number;
+        thermal: number;
+        total: number;
+        count: number;
+    };
+    /** sample the live field at `(x, y)` — the net force vector a still test particle would feel. */
+    sample(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    scrollV(): number;
+    setVisible(on: boolean): void;
+    setBackground(mode: Parameters<FieldHandle['setBackground']>[0]): void;
+    /** stop the loop, release listeners, and remove the canvas if this instance made it. */
+    destroy(): void;
+}
+//# sourceMappingURL=field.d.ts.map

package/dist/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"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"}

package/dist/field.js

@@ -0,0 +1,133 @@
+/**
+ * `FieldField` — the reciprocal DOM-physics field as a typed class, for plain TypeScript
+ * apps that want object-oriented ergonomics without a framework or a custom element.
+ *
+ * `new FieldField()` builds a managed, full-viewport canvas and starts the engine on it;
+ * pass `{ canvas }` to drive a `<canvas>` you own instead. The class implements the full
+ * `FieldHandle` surface, so an instance is type-compatible anywhere a handle is expected,
+ * and it exposes the `canvas` it renders to.
+ *
+ * ```ts
+ * import { FieldField } from '@fundamental-engine/vanilla';
+ *
+ * const field = new FieldField({ accent: '#4da3ff', render: 'dots' });
+ * field.setFormation('wells');
+ * field.burst(window.innerWidth / 2, 200);
+ * // field.scan(); field.destroy();
+ * ```
+ */
+import {} from '@fundamental-engine/core';
+import { createBrowserField } from '@fundamental-engine/platform';
+import { makeFieldCanvas, assertBrowser } from "./mount.js";
+export class FieldField {
+    /** the `<canvas>` the field renders to — the one created for you, or the one you passed. */
+    canvas;
+    field;
+    /** did this instance create the canvas (and so should remove it on `destroy()`)? */
+    managed;
+    constructor(init = {}) {
+        assertBrowser(); // browser-only: fail loudly during SSR instead of a cryptic crash
+        const { canvas, target, ...opts } = init;
+        this.managed = !canvas;
+        this.canvas = canvas ?? makeFieldCanvas(target);
+        this.field = createBrowserField(this.canvas, opts);
+    }
+    /** (re)scan the document for `[data-body]` bodies after a layout change. */
+    scan() {
+        this.field.scan();
+    }
+    /** alias of `scan`. */
+    rescan() {
+        this.field.rescan();
+    }
+    /** recolor the travelling accent (§9). */
+    setAccent(hex) {
+        this.field.setAccent(hex);
+    }
+    /** swap the accent's color template live: a built-in name or custom hex stops (§9). */
+    setPalette(palette) {
+        this.field.setPalette(palette);
+    }
+    /** switch the global formation (§7). */
+    setFormation(name) {
+        this.field.setFormation(name);
+    }
+    /** toggle conserved attention (§2.4) live — one finite strength budget. */
+    setAttention(on) {
+        this.field.setAttention(on);
+    }
+    /** toggle cross-boundary causality (Concept 4) live — density spills to neighbours. */
+    setCausality(on) {
+        this.field.setCausality(on);
+    }
+    /** toggle the density heatmap layer (field-systems H1) live. */
+    setHeatmap(on) {
+        this.field.setHeatmap(on);
+    }
+    /** switch the underlay render mode (§20.6) live. */
+    setRender(mode) {
+        this.field.setRender(mode);
+    }
+    /** render a field-structure visualization on the overlay surface (in front of content). */
+    setOverlay(mode) {
+        this.field.setOverlay(mode);
+    }
+    /** wire glowing connector lines between a set, or clear with null (§10). */
+    threads(list) {
+        this.field.threads(list);
+    }
+    /** a discrete one-shot: shove + heat matter near (x, y), optionally tinting it (§11). */
+    burst(x, y, hex) {
+        this.field.burst(x, y, hex);
+    }
+    /** place/move a dynamic flow focus the field bends toward — pulls matter, curves the streamlines. */
+    flowTo(x, y, opts) {
+        this.field.flowTo(x, y, opts);
+    }
+    /** remove the flow focus. */
+    clearFlow() {
+        this.field.clearFlow();
+    }
+    seed(atoms) {
+        this.field.seed(atoms);
+    }
+    atomAt(x, y) {
+        return this.field.atomAt(x, y);
+    }
+    focusAt(x, y) {
+        return this.field.focusAt(x, y);
+    }
+    clearFocus() {
+        this.field.clearFocus();
+    }
+    particleCount() {
+        return this.field.particleCount();
+    }
+    /** copy live particle state into `out` (stride 5: x, y, z, heat, size); returns the count written. */
+    readParticles(out) {
+        return this.field.readParticles(out);
+    }
+    energy() {
+        return this.field.energy();
+    }
+    /** sample the live field at `(x, y)` — the net force vector a still test particle would feel. */
+    sample(x, y) {
+        return this.field.sample(x, y);
+    }
+    scrollV() {
+        return this.field.scrollV();
+    }
+    setVisible(on) {
+        this.field.setVisible(on);
+    }
+    setBackground(mode) {
+        this.field.setBackground(mode);
+    }
+    /** stop the loop, release listeners, and remove the canvas if this instance made it. */
+    destroy() {
+        this.field.destroy();
+        if (this.managed)
+            this.canvas.remove();
+    }
+}
+//# sourceMappingURL=field.js.map

package/dist/field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.js","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@fundamental-engine/vanilla` — the framework-free TypeScript door to the reciprocal field.
+ *
+ * The same engine the `<field-root>` custom element and the React `<FieldField>` wrap,
+ * exposed as a typed `FieldField` class and the imperative `mountField()` / `createField()`,
+ * with **no** custom-element registration and **no** framework dependency. This package has
+ * no side effects: importing it never defines a custom element. Reach for it from plain
+ * TypeScript, or any stack where you want to drive the field by hand.
+ *
+ * Spec: `docs/engine-reference/forces-system.md`.
+ */
+export { FieldField } from './field.ts';
+export type { FieldFieldInit } from './field.ts';
+export { mountField, makeFieldCanvas } from './mount.ts';
+export type { MountOptions } from './mount.ts';
+export { createBrowserField as createField, browserHost } from '@fundamental-engine/platform';
+export type { FieldHandle, FieldOptions, ThreadLink, Particle, Body, Force, Formation, Vec2, } from '@fundamental-engine/core';
+export { FORCES, FORMATIONS, CONDITIONS, PALETTE } from '@fundamental-engine/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,OAAO,EAAE,kBAAkB,IAAI,WAAW,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC9F,YAAY,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,SAAS,EACT,IAAI,GACL,MAAM,0BAA0B,CAAC;AAIlC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@fundamental-engine/vanilla` — the framework-free TypeScript door to the reciprocal field.
+ *
+ * The same engine the `<field-root>` custom element and the React `<FieldField>` wrap,
+ * exposed as a typed `FieldField` class and the imperative `mountField()` / `createField()`,
+ * with **no** custom-element registration and **no** framework dependency. This package has
+ * no side effects: importing it never defines a custom element. Reach for it from plain
+ * TypeScript, or any stack where you want to drive the field by hand.
+ *
+ * Spec: `docs/engine-reference/forces-system.md`.
+ */
+export { FieldField } from "./field.js";
+export { mountField, makeFieldCanvas } from "./mount.js";
+// The engine entry, wired to the browser host (core is renderer-agnostic and requires a host).
+// `createBrowserField` = `createField` + `browserHost()`; re-exported here as `createField` so the
+// framework-free door stays a one-liner. `browserHost` is re-exported for custom wiring.
+export { createBrowserField as createField, browserHost } from '@fundamental-engine/platform';
+// The catalog data a vanilla UI commonly reads — the force list, formations, `data-when`
+// gates, and the palette — so a force picker or legend needs no second install.
+export { FORCES, FORMATIONS, CONDITIONS, PALETTE } from '@fundamental-engine/core';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGzD,+FAA+F;AAC/F,mGAAmG;AACnG,yFAAyF;AACzF,OAAO,EAAE,kBAAkB,IAAI,WAAW,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAY9F,yFAAyF;AACzF,gFAAgF;AAChF,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/mount.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `mountField` — the framework-free imperative mount (no custom element, no framework).
+ *
+ * Creates a fixed, full-viewport canvas behind the page, starts the engine on it, and
+ * returns the `FieldHandle` (whose `destroy()` also removes the canvas it made). It is the
+ * same engine the `<field-root>` custom element and the React `<FieldField>` wrap, for
+ * plain scripts and imperative mounts: `const field = mountField(); field.scan()`.
+ *
+ * This is the canonical home of the imperative mount; `@fundamental-engine/elements` re-exports it.
+ * For object-oriented ergonomics (and driving a canvas you own), see the `FieldField` class.
+ */
+import { type FieldHandle, type FieldOptions } from '@fundamental-engine/core';
+export interface MountOptions extends FieldOptions {
+    /** where to append the canvas; defaults to `document.body`. */
+    target?: HTMLElement;
+}
+/**
+ * Throw a clear error when there is no DOM (server-side render or build step). The field is a
+ * browser-only, client-side effect; construct it on the client (a `useEffect` / `onMount` /
+ * "client only" boundary), never during SSR. Call before any `document`/`window` access.
+ */
+export declare function assertBrowser(): void;
+/**
+ * Create the fixed, full-viewport, decorative canvas the managed mounts run on. Internal —
+ * shared by `mountField` and the `FieldField` class so the styling lives in one place.
+ */
+export declare function makeFieldCanvas(target?: HTMLElement): HTMLCanvasElement;
+/** Mount and start the field; returns the handle. `destroy()` also removes the canvas. */
+export declare function mountField(opts?: MountOptions): FieldHandle;
+//# sourceMappingURL=mount.d.ts.map

package/dist/mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../src/mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGjG,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,+DAA+D;IAC/D,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAOpC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,GAAE,WAA2B,GAAG,iBAAiB,CAMtF;AAED,0FAA0F;AAC1F,wBAAgB,UAAU,CAAC,IAAI,GAAE,YAAiB,GAAG,WAAW,CAY/D"}

package/dist/mount.js

@@ -0,0 +1,50 @@
+/**
+ * `mountField` — the framework-free imperative mount (no custom element, no framework).
+ *
+ * Creates a fixed, full-viewport canvas behind the page, starts the engine on it, and
+ * returns the `FieldHandle` (whose `destroy()` also removes the canvas it made). It is the
+ * same engine the `<field-root>` custom element and the React `<FieldField>` wrap, for
+ * plain scripts and imperative mounts: `const field = mountField(); field.scan()`.
+ *
+ * This is the canonical home of the imperative mount; `@fundamental-engine/elements` re-exports it.
+ * For object-oriented ergonomics (and driving a canvas you own), see the `FieldField` class.
+ */
+import { FIELD_CANVAS_CSS } from '@fundamental-engine/core';
+import { createBrowserField } from '@fundamental-engine/platform';
+/**
+ * Throw a clear error when there is no DOM (server-side render or build step). The field is a
+ * browser-only, client-side effect; construct it on the client (a `useEffect` / `onMount` /
+ * "client only" boundary), never during SSR. Call before any `document`/`window` access.
+ */
+export function assertBrowser() {
+    if (typeof document === 'undefined' || typeof window === 'undefined') {
+        throw new Error('field-ui: the field runs in the browser only. Create it on the client (inside ' +
+            'useEffect / onMount / a "client only" boundary), not during server-side rendering.');
+    }
+}
+/**
+ * Create the fixed, full-viewport, decorative canvas the managed mounts run on. Internal —
+ * shared by `mountField` and the `FieldField` class so the styling lives in one place.
+ */
+export function makeFieldCanvas(target = document.body) {
+    const canvas = document.createElement('canvas');
+    canvas.setAttribute('aria-hidden', 'true'); // decorative field (§18 a11y)
+    canvas.style.cssText = FIELD_CANVAS_CSS; // single source of truth (core/surface.ts)
+    target.appendChild(canvas);
+    return canvas;
+}
+/** Mount and start the field; returns the handle. `destroy()` also removes the canvas. */
+export function mountField(opts = {}) {
+    assertBrowser();
+    const { target = document.body, ...fieldOpts } = opts;
+    const canvas = makeFieldCanvas(target);
+    const field = createBrowserField(canvas, fieldOpts);
+    return {
+        ...field,
+        destroy: () => {
+            field.destroy();
+            canvas.remove();
+        },
+    };
+}
+//# sourceMappingURL=mount.js.map

package/dist/mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.js","sourceRoot":"","sources":["../src/mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAuC,MAAM,0BAA0B,CAAC;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAOlE;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CACb,gFAAgF;YAC9E,oFAAoF,CACvF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,SAAsB,QAAQ,CAAC,IAAI;IACjE,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC,8BAA8B;IAC1E,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,gBAAgB,CAAC,CAAC,2CAA2C;IACpF,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,UAAU,CAAC,OAAqB,EAAE;IAChD,aAAa,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,SAAS,EAAE,GAAG,IAAI,CAAC;IACtD,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACpD,OAAO;QACL,GAAG,KAAK;QACR,OAAO,EAAE,GAAG,EAAE;YACZ,KAAK,CAAC,OAAO,EAAE,CAAC;YAChB,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@fundamental-engine/vanilla",
+  "version": "0.4.0",
+  "description": "Framework-free TypeScript wrapper for Fundamental — the reciprocal DOM-physics field as a typed FieldField class + mountField(), with no custom-element registration and no framework dependency.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Zach Shallbetter <hi@zachshallbetter.com> (https://zachshallbetter.com)",
+  "homepage": "https://fundamental-engine.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zachshallbetter/fundamental-engine.git",
+    "directory": "packages/vanilla"
+  },
+  "bugs": {
+    "url": "https://github.com/zachshallbetter/fundamental-engine/issues"
+  },
+  "keywords": [
+    "Fundamental",
+    "typescript",
+    "vanilla",
+    "particles",
+    "physics",
+    "canvas",
+    "field",
+    "reciprocal",
+    "dom"
+  ],
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@fundamental-engine/platform": "0.4.0",
+    "@fundamental-engine/core": "0.4.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test"
+  }
+}