⌬ Yantra4D: The Hyperobjects Commons

Manifest-driven parametric design for the decentralized manufacturing age.

Yantra4D is not just a CAD tool; it is a Poly-Kernel Engine, a Continuous SDF Geometry Compiler, and a thriving Hyperobjects Commons. It bridges the mathematical precision of programmatic CAD with the accessibility of a visual, web-native storefront — integrating material metadata into the geometry pipeline, with interactive Digital Twin simulation in progress (see "Current status" below: parts of the simulation stack are heuristic or mocked today).

---

🛰️ The Vision: Hyperobjects & CDG

We are building the Hyperobjects Commons — a repository of "Bounded 4D Hyperobjects" designed for interoperability. By leveraging Common Denominator Geometry (CDG) interfaces (standardized snaps, threads, and joints), projects in the Yantra4D ecosystem can physically and mathematically interface with one another natively.

📼 Cartridge-Like Architecture

Every project in Yantra4D is a self-contained "Cartridge".

• The Manifest: A project.json file serves as the single source of truth, defining parameters, modes, and parts.
• Poly-Kernel: four kernels — high-performance OpenSCAD (CSG) for browser-side WASM reactivity, mathematically exact CadQuery (B-Rep) for engineering-grade STEP exports, a native Implicit SDF engine for lattices, and a node-graph engine that compiles graphs to sandboxed CadQuery.
• Portability: Drop a project folder into projects/ and the platform instantly white-labels the UI to serve it.

🧠 Material Hyperobjects & Hyperawareness

Geometry is meaningless without material context. The Yantra4D Commons pioneers the integration of Material Hyperobjects—metadata modules (/materials/) capturing the Topological Data Analysis (TDA), spatial compensations, and semantic ontologies of physical AM substrates. By feeding this nanoscale intelligence directly into the geometric compiler, our additively manufacturable hyperobjects are imbued with "hyperawareness", actively warping and adapting their dimensions to survive physical reality.

🌡️ Interactive Digital Twin (4D Simulation) — partially implemented / roadmap

The vision: apply simulated energy to any hyperobject and watch the continuous SDF morph in real-time as it crosses material phase boundaries (glass transition, yield, melt).

What is real today: the Studio energy slider (simulated_energy) drives a thermodynamic-collapse heuristic in the implicit SDF engine (sag past glass-transition temperature), and a render whose browser estimate exceeds the device's budget is placed on the server by apps/studio/src/services/engine/renderPlacement.ts — one rule in the placement table below, not a "circuit breaker" bolted onto renderService.ts.

What is estimated or unavailable today: no physics solver ships with this repo. POST /api/projects/:slug/simulate/physics answers 501 physics_solver_unavailable and creates no job until a solver backend is registered with configure_physics_solver (apps/api/tasks/simulation_tasks.py). The stress endpoint returns a labeled geometry-derived estimate (method: "geometry_proxy", approximation: true), not a structural solve, and the optimize endpoint is a deterministic heuristic (method: "heuristic", approximation: true). Real PPF/FEM execution on GPU nodes is roadmap. See the Current status section.

---

Render caches are scoped to published renderer builds; see release cache identity for invalidation, missing-identity behavior and remaining limits.

Native renderer output and cancellation explains pipe draining, per-request process ownership, deadlines and remaining isolation limits.

Mode-specific controls documents the commons-owned visibility contract and actual-pin fastener regression.

Native dropdown values retain the declared numeric or string option type; direct CLI comparisons must also match the platform checkbox encoding.

Viewer resource ownership documents the 32 MiB/16-entry CPU cache, per-consumer geometry, GLTF and animated-grid cleanup, and the limits of these budgets.

Publication source acceptance describes the exact-main CI gate, stale-source pin refusal and runtime verification boundary.

🛠️ The Stack

• CAD Engines: Four-kernel execution via OpenSCAD (CSG), CadQuery (B-Rep), a native Implicit SDF Engine (TPMS/Lattice), and a Graph Engine that transpiles .graph.json node graphs into sandboxed CadQuery (see authoring guide).
• The Studio: React 19 + Three.js + Manifold-3d for blisteringly fast volumetric browser rendering.
• The API: Python Flask backend with Docker-orchestrated render clusters and slicer-grade physics estimation.
• The Knowledge Base: 4D Docs source — Astro Starlight; the public docs site is not deployed yet (see "Deep Documentation" below).

---

✅ Current status (2026-09-02)

Honest, code-verified snapshot. Working today:

• Interactive 3D preview — Studio (React 19 + Three.js) renders projects live with parameter controls.
• Browser-first rendering — the visitor's browser is the default placement: the OpenSCAD WASM worker renders there, free for us and unmetered for them, and the server's native OpenSCAD/CadQuery is the only metered path. Which one runs is decided by decideRenderPlacement(), a pure 11-rule precedence function: four HARD server rules first (a cadquery/graph/implicit mode, manifest render.server_only, an unusable wasm bundle, and any export_format but stl — the browser kernel writes one /output.stl and has no converter), then the ?render= override, the visitor's preference, the measured device tier, this session's browser failures, the estimate budget, the legacy force_backend soft hint, and finally the browser. A soft server decision flips back to the browser when the API is unreachable; a hard one does not. Full table: docs/guides/wasm-mode.md.
• STL / mesh export — server render pipeline produces STL/GLB/3MF artifacts.
• Geometry verification — dedicated verify endpoint (apps/api/routes/engine/verify.py); the parity check CI runs is tests/scripts/geometric_regression.py (the test-geometric-parity job). scripts/qa/verify_parity.py is a local dual-engine comparison tool, not a CI lane: it reports 18 of 28 comparable mode pairs passing after #115 pinned the ten parity-fixed cartridges, so the dual-engine parity claim is an intent rather than an enforced invariant — see docs/architecture/dual-engine.md.
• Cartridge project system — project.json manifests, 512-cartridge CadQuery-first Commons catalog (including curated art/misc projects), admin app, Janua-authenticated admin flows.
• Implicit SDF engine — TPMS/lattice field generation, including the energy→sag "phase shift" heuristic behind the digital-twin slider.
• Per-mode engine resolution — a single cartridge can mix modes across kernels; the render engine is resolved per mode (ManifestService.mode_engine), so the flagship hyperobjects ship dual-engine (exact CadQuery B-Rep modes alongside their original OpenSCAD modes).

Estimated, heuristic or unavailable today (presented as roadmap, not shipped):

• PPF physics simulation — the endpoint answers 501 physics_solver_unavailable and creates no job until a solver backend is registered with configure_physics_solver; the PPF script generator builds the input such a backend would run. No solver or GPU execution path ships in this repo yet.
• Stress heatmap — a deterministic geometry-derived estimate (method: "geometry_proxy", approximation: true, schema_version: stress_proxy_v1), not a finite-element solve.
• Parameter estimate (formerly labelled topology optimization) — a deterministic heuristic (method: "heuristic", approximation: true; apps/api/services/simulation/optimizer.py describes itself as the stand-in used "when full PDE-backed" solving is unavailable), not a generative or PDE-based optimization. Its status field current_sigma is a deprecated alias of current_score for one release.

---

📦 The Commons Catalog (CadQuery-first)

The Commons is a demand-grounded catalog of Bounded 4D Hyperobjects, authored CadQuery-first (exact B-Rep, STEP export). Each projects/<slug>/ is a self-contained cartridge (main.py + project.json + docs); the flagship interfaces are also published as independent madfam-org git submodules.

Counts below are generated from the manifests, not maintained by hand — see docs/commons-catalog.json:

Cartridges	512
With declared CDG interfaces	502
Carrying an explicit license	512
Dual-engine (CadQuery B-Rep + OpenSCAD CSG)	20
Distinct external standards referenced	416
Licensed CERN-OHL-W-2.0	512 of 512

Licensing

Two licenses apply to this repository and they cover different things:

• The platform — everything outside projects/ — is AGPL-3.0 (see LICENSE).
• The cartridges in projects/ are hardware designs, licensed CERN-OHL-W-2.0 (see the table above). Weakly reciprocal: modifications to a design must be shared, but a larger product incorporating one need not be.

Every one of the 512 cartridges is CERN-OHL-W-2.0. There are no licence exceptions left in the commons.

Five cartridges that carried a non-CERN origin licence were removed whole on 2026-09-04 under ADR-021, and their slugs are reserved pending clean-room re-creation:

Reserved slug	Origin licence that caused the removal
stemfie	GPL-3.0-or-later (stemfie.org)
keyv2	GPL-3.0 (rsheldiii/KeyV2)
multiboard	CC-BY-NC-SA-4.0 (Multiboard — NonCommercial)
polydice	BSD-2-Clause (PolyDiceGenerator, © 2020 charmaur)
rugged-box	CC-BY-NC-SA-4.0 on vendored upstream files (Iceman)

Each will return only as a CERN-OHL-W-2.0 cartridge written from a recorded baseline by an implementer who has not read the removed source. For the two whose upstream licence covers the design rather than code (multiboard, rugged-box), the re-creation targets the interface standard, not the shape.

Every cartridge's license is machine-readable in the catalog, and CI fails if a declared license ever diverges from the one a cartridge actually ships, if a manifest declares two conflicting licenses, or if an excluded cartridge appears in the published catalog (scripts/qa/check_licenses.py --strict-all).

Two cartridges are deliberately excluded from the published Commons: they are client-owned private cartridges, so they live outside the commons repo entirely, mount at private-projects/, and are served only to authorized identities. (cq-hyperobject-test used to be a third exclusion; since RFC 0038 P2 it is an engine test fixture vendored under apps/api/tests/fixtures/cartridges/ and is not a cartridge at all.)

What is verified, precisely. Every manifest is schema-validated in CI, and every mode is geometrically distinct (each mode's parts[] id drives target_part dispatch). Cross-kernel geometric parity and watertightness are enforced in CI for the cartridges on the VERIFIED_PARITY_PROJECTS allowlist in apps/api/tests/scripts/geometric_regression.py; for the rest, divergence is reported but non-blocking, and each run prints how many cartridges were compared versus skipped. Treat a green parity job as covering the allowlist, not the whole catalog.

The first 100 — ordered by Common Denominator Geometry leverage:

Tier	Focus
1 · Universal Interfaces	Gridfinity, VESA, ¼-20, GoPro, bottle thread, DIN clip, T-slot, gears, fasteners, box
2 · Household Organization	dividers, pegboard/Multiboard, bins, hooks, shelf brackets
3 · Kitchen / Bath / Utility	coasters, tube squeezers, jar racks, funnels, knobs
4 · Mechanical & Kinematic	pulleys, bearings, gear trains, drag chain, springs, cams, lead-screw nuts
5 · Fastening & Joining	connectors, snap-fits, dovetails, threaded bosses, ball-sockets
6 · Electronics & Desk	enclosures, SBC cases, stands, risers, media caddies
7 · Jigs & Fixtures	soft jaws, drill guides, gauges, templates, handwheels
8 · Medical / Lab / Assistive	prosthetic sockets, slide holders, tube/pill racks, splints
9 · Filtration / Water / Garden	Faircap filter, pipe/hose fittings, planters, drip fittings
10 · Mobility / Automotive / EDC	Picatinny, bike/vent mounts, carabiners, keytags, French cleat

The second 100 — deeper cuts plus new domains (mounting systems, drone/FPV, automotive, kitchen, garden, workshop, electronics/maker, wearable/EDC, musical/studio, sports, marine/RV, pet, generative art, safety).

Dual-engine flagships (CadQuery B-Rep modes + original OpenSCAD modes): Gridfinity · Gears · Fasteners · DIN Rail Clip · Soft Jaw · Faircap Filter · Parametric Connector · Microscope Slide Holder — plus 13 more; COMMONS.md lists all 21 (counts.dual_engine in the catalog).

Machine-readable catalog: docs/commons-catalog.json — one entry per cartridge with its CDG interfaces, referenced standards, engines, and clone instructions. Human-readable index: COMMONS.md. Both are generated by scripts/qa/generate_commons_catalog.py and checked for staleness in CI.

Note for agents: llms.txt and llms-full.txt are not the catalog. They are the org-wide agent operating contract, regenerated across every MADFAM repo by internal-devops/scripts/sync-agent-docs.py, which overwrites whatever is placed there.

---

📖 Deep Documentation

For peak Developer Experience and Agentic Discovery, consult our interconnected docs.

docs.yantra4d.com is not deployed yet — the hostname does not resolve. The Starlight source below is complete and readable in-repo; the site build, ingress, and DNS record are still outstanding. Links point at the source until it is live.

• Getting Started — Launch your first project.
• Manifest Specs — How to author a "Cartridge".
• Poly-Kernel Logic — Understanding the dual SCAD/Python pipeline.
• Hyperobjects Guide — CDG interfaces and the Commons model.
• Commons Catalog — Machine-readable entry point for AI agents.

---

🚀 Quick Start

Clone (with all project submodules)

git clone --recurse-submodules https://github.com/madfam-org/yantra4d

Development

./scripts/dev/dev.sh      # Full Stack (Backend + Studio + Landing)
./scripts/dev-stop.sh     # Cleanup

Docker (Production-Ready)

docker compose up --build

Open localhost:3000 to enter the Studio.

---

🤝 Community & License

Yantra4D is licensed under the GNU Affero General Public License v3.0 (AGPLv3). Our hyperobjects are always released under the CERN-OHL-W-2.0 (Weakly Reciprocal) open hardware license.

Join the movement. Print the Hyperobjects.

Shared configuration links preserve Unicode text through JSON escapes and retain legacy decoding. See the share-link contract and limits.

Viewer artifact loading has independent completion and lifecycle guarantees. See blank-viewer diagnostics and shared STL task ownership; render completion alone does not prove canvas delivery.