@fundamental-engine/core 0.4.0

package/dist/visual/tokens.js

@@ -0,0 +1,54 @@
+/**
+ * Field design tokens, roles, and the output-variable catalog (worldclass §11/§12, interaction
+ * §5/§11/§13). Tuning knobs as `--field-*` custom properties, the `data-field-role` value set, and
+ * the full list of `--field-*` variables the field can write back (including the attention/memory
+ * sub-variables). Pure data + a CSS string builder. (Distinct from `config/tokens.ts`, which is the
+ * force-palette token set.)
+ */
+/** Field tuning tokens (worldclass §11), field-first names. */
+export const FIELD_DESIGN_TOKENS = {
+    '--field-motion-calm': '0.2',
+    '--field-motion-active': '0.8',
+    '--field-range-sm': '180px',
+    '--field-range-md': '320px',
+    '--field-range-lg': '520px',
+    '--field-density-soft': '0.25',
+    '--field-density-lit': '0.65',
+    '--field-entropy-warning': '0.72',
+};
+/** The design tokens as a CSS rule (drop into a stylesheet). */
+export function fieldTokensCss(selector = ':root') {
+    const body = Object.entries(FIELD_DESIGN_TOKENS)
+        .map(([k, v]) => `  ${k}: ${v};`)
+        .join('\n');
+    return `${selector} {\n${body}\n}`;
+}
+/** Field roles (worldclass §12) — `data-field-role` values. */
+export const FIELD_ROLES = ['source', 'sink', 'anchor', 'boundary', 'sensor', 'display'];
+/** Whether a string is a known field role. */
+export function isFieldRole(s) {
+    return FIELD_ROLES.includes(s);
+}
+/**
+ * The full `--field-*` output-variable catalog the field can write back, including the attention
+ * and memory sub-variables (interaction §5/§11/§13) and layout shift. The core loop writes the
+ * primary metrics today; the sub-vars are the agreed names for the agent layer to emit.
+ */
+export const FIELD_OUTPUT_VARS = [
+    '--field-density',
+    '--field-attention',
+    '--field-heat',
+    '--field-entropy',
+    '--field-coherence',
+    '--field-memory',
+    '--field-pressure',
+    '--field-pull-x',
+    '--field-pull-y',
+    '--field-attention-share',
+    '--field-attention-rank',
+    '--field-related-attention',
+    '--field-path-use',
+    '--field-user-wake',
+    '--field-layout-shift',
+];
+//# sourceMappingURL=tokens.js.map

package/dist/visual/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/visual/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,mBAAmB,GAAqC;IACnE,qBAAqB,EAAE,KAAK;IAC5B,uBAAuB,EAAE,KAAK;IAC9B,kBAAkB,EAAE,OAAO;IAC3B,kBAAkB,EAAE,OAAO;IAC3B,kBAAkB,EAAE,OAAO;IAC3B,sBAAsB,EAAE,MAAM;IAC9B,qBAAqB,EAAE,MAAM;IAC7B,yBAAyB,EAAE,MAAM;CAClC,CAAC;AAEF,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,QAAQ,GAAG,OAAO;IAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC;SAC7C,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC;SAChC,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,GAAG,QAAQ,OAAO,IAAI,KAAK,CAAC;AACrC,CAAC;AAED,+DAA+D;AAC/D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAC;AAGlG,8CAA8C;AAC9C,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,OAAQ,WAAiC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,iBAAiB;IACjB,mBAAmB;IACnB,cAAc;IACd,iBAAiB;IACjB,mBAAmB;IACnB,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,gBAAgB;IAChB,yBAAyB;IACzB,wBAAwB;IACxB,2BAA2B;IAC3B,kBAAkB;IAClB,mBAAmB;IACnB,sBAAsB;CACd,CAAC"}

package/dist/visual/visualization.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The visualization truth table + render-mode catalog + presets (visualization-methods-taxonomy,
+ * system-contracts §11/§18). "Every render mode needs a truth-table entry" — this is that table as
+ * inspectable data: what each visualization reads, whether it mutates physics, and the truth it
+ * shows. Pure data.
+ */
+import type { RenderLayer } from '../recipes/schema.ts';
+/** One row of the visualization truth table (system-contracts §11). */
+export interface VisualizationTruthRow {
+    visualization: string;
+    /** what it reads from. */
+    readsFrom: string;
+    /** does it mutate physics? (must be false unless declared feedback). */
+    mutatesPhysics: boolean | 'optional' | 'visual';
+    /** the truth it reveals. */
+    showsTruthAbout: string;
+}
+/** The visualization truth table (system-contracts §11, viz-taxonomy "Visualization Truth Table"). */
+export declare const VISUALIZATION_TRUTH_TABLE: readonly VisualizationTruthRow[];
+/** Whether a render mode/layer is shipped today or planned. */
+export interface RenderModeInfo {
+    mode: string;
+    type: string;
+    shows: string;
+    status: 'shipped' | 'planned';
+}
+/** The render-modes catalog (viz-taxonomy "Render Modes Catalog"), with honest shipped/planned status. */
+export declare const RENDER_MODES: readonly RenderModeInfo[];
+/** Named visualization presets (viz-taxonomy "Visualization Presets") as render-layer stacks. */
+export declare const VISUALIZATION_PRESETS: Readonly<Record<string, RenderLayer[]>>;
+//# sourceMappingURL=visualization.d.ts.map

package/dist/visual/visualization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualization.d.ts","sourceRoot":"","sources":["../../src/visual/visualization.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,cAAc,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;IAChD,4BAA4B;IAC5B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,sGAAsG;AACtG,eAAO,MAAM,yBAAyB,EAAE,SAAS,qBAAqB,EAcrE,CAAC;AAEF,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;CAC/B;AAED,0GAA0G;AAC1G,eAAO,MAAM,YAAY,EAAE,SAAS,cAAc,EAiBjD,CAAC;AAEF,iGAAiG;AACjG,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CASzE,CAAC"}

package/dist/visual/visualization.js

@@ -0,0 +1,47 @@
+/** The visualization truth table (system-contracts §11, viz-taxonomy "Visualization Truth Table"). */
+export const VISUALIZATION_TRUTH_TABLE = [
+    { visualization: 'particles', readsFrom: 'particle state', mutatesPhysics: true, showsTruthAbout: 'matter' },
+    { visualization: 'field-lines', readsFrom: 'field()', mutatesPhysics: false, showsTruthAbout: 'structure' },
+    { visualization: 'streamlines', readsFrom: 'vector field', mutatesPhysics: false, showsTruthAbout: 'continuous direction' },
+    { visualization: 'force-vectors', readsFrom: 'apply() or probe', mutatesPhysics: false, showsTruthAbout: 'cause' },
+    { visualization: 'trails', readsFrom: 'particle history', mutatesPhysics: false, showsTruthAbout: 'motion history' },
+    { visualization: 'heatmap', readsFrom: 'scalar grids', mutatesPhysics: 'optional', showsTruthAbout: 'accumulation' },
+    { visualization: 'contours', readsFrom: 'scalar fields', mutatesPhysics: false, showsTruthAbout: 'terrain / equal values' },
+    { visualization: 'potential', readsFrom: 'potential field', mutatesPhysics: false, showsTruthAbout: 'wells and gradients' },
+    { visualization: 'energy', readsFrom: 'particle + field state', mutatesPhysics: false, showsTruthAbout: 'cost and conservation' },
+    { visualization: 'topology', readsFrom: 'relationship agents', mutatesPhysics: 'optional', showsTruthAbout: 'coupling' },
+    { visualization: 'dom-state', readsFrom: 'CSS variables + events', mutatesPhysics: 'visual', showsTruthAbout: 'reciprocity' },
+    { visualization: 'causality', readsFrom: 'per-force contributions', mutatesPhysics: false, showsTruthAbout: 'why motion happened' },
+    { visualization: 'prediction', readsFrom: 'deterministic ghost step', mutatesPhysics: false, showsTruthAbout: 'expected future path' },
+];
+/** The render-modes catalog (viz-taxonomy "Render Modes Catalog"), with honest shipped/planned status. */
+export const RENDER_MODES = [
+    { mode: 'dots', type: 'matter', shows: 'particle positions and heat', status: 'shipped' },
+    { mode: 'trails', type: 'motion', shows: 'path history', status: 'shipped' },
+    { mode: 'links', type: 'topology', shows: 'connector lines between bodies', status: 'shipped' },
+    { mode: 'streamlines', type: 'structure', shows: 'continuous field paths', status: 'shipped' },
+    { mode: 'metaballs', type: 'matter', shows: 'liquid density surface', status: 'shipped' },
+    { mode: 'voronoi', type: 'matter', shows: 'nearest-site cells', status: 'shipped' },
+    { mode: 'field-lines', type: 'structure', shows: 'field() geometry', status: 'shipped' },
+    { mode: 'heatmap', type: 'scalar', shows: 'density accumulation', status: 'shipped' },
+    { mode: 'force-vectors', type: 'debug', shows: 'actual cause from apply()', status: 'shipped' },
+    { mode: 'contours', type: 'scalar', shows: 'equal-value isolines', status: 'shipped' },
+    { mode: 'potential', type: 'scalar', shows: 'wells and gradients', status: 'shipped' },
+    { mode: 'energy', type: 'scalar', shows: 'kinetic / potential / thermal', status: 'shipped' },
+    { mode: 'topology', type: 'graph', shows: 'threads, flux links', status: 'shipped' },
+    { mode: 'inspector', type: 'debug', shows: 'bodies, agents, metrics, contracts', status: 'shipped' },
+    { mode: 'causality', type: 'debug', shows: 'contribution sources', status: 'shipped' },
+    { mode: 'prediction', type: 'debug', shows: 'ghost trajectory', status: 'shipped' },
+];
+/** Named visualization presets (viz-taxonomy "Visualization Presets") as render-layer stacks. */
+export const VISUALIZATION_PRESETS = {
+    beautiful: ['particles', 'trails'],
+    scientific: ['field-lines', 'streamlines', 'particles'],
+    diagnostic: ['particles', 'field-lines', 'heatmap'],
+    thermal: ['heatmap', 'particles', 'trails'],
+    plasma: ['field-lines', 'trails', 'particles'],
+    topological: ['field-lines', 'links', 'particles'],
+    reduced: ['field-lines'], // static structure only — the reduced-motion fallback (no travel)
+    poster: ['particles', 'field-lines'],
+};
+//# sourceMappingURL=visualization.js.map

package/dist/visual/visualization.js.map

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

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@fundamental-engine/core",
+  "version": "0.4.0",
+  "description": "A reciprocal DOM-physics field — elements bend the field; the field's density bends them back.",
+  "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/core"
+  },
+  "bugs": {
+    "url": "https://github.com/zachshallbetter/fundamental-engine/issues"
+  },
+  "keywords": [
+    "particles",
+    "physics",
+    "canvas",
+    "forces",
+    "field",
+    "reciprocal",
+    "dom",
+    "animation",
+    "interaction",
+    "generative",
+    "zero-dependency"
+  ],
+  "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"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test",
+    "bench": "node bench/integrator.bench.ts"
+  }
+}