@hatiolab/figure-model
Implementation and verification status: docs/status.md.
The figure format, figure-asset-1: its kernel, authoring commands, release gate, score and AI proposal
grammar. No runtime dependencies.
The package contains no renderer. The modeller authors with it, the server judges and stores with it, and the scene draws from what it compiles.
Runtime LOD: ADR-0116. Render-only view helpers are implemented; camera selection and GPU resources belong to things-scene.
What it solves
It moves adding a component from development to authoring. A new kind of equipment should be a data document, not a class that a developer writes, builds and deploys. That requires three things at once:
| Condition | |
|---|---|
| 1 | Expressiveness — a shape that could be written in code can be written as data |
| 2 | Equal performance — drawing from data is as fast as drawing hard-coded geometry |
| 3 | A live component — events, animation and data binding attach, not only the shape |
A figure is a graph of named parts whose dimensions, poses and states are typed expressions of the instance size and state inputs. The names are what let a binding say "tie the lamp colour to temperature" or "open the door".
Use
npm install @hatiolab/figure-model
Everything is exported from the package root.
import { parseFigureAsset, compileFigureAsset, inspectFigureAsset, figureScoreOf } from '@hatiolab/figure-model'
Main exports
| Area | Exports |
|---|---|
| Asset document | parseFigureAsset, serializeFigureAsset, compileFigureAsset, captureFigureAuthoredInputs; types from asset-types.ts, FIGURE_PLACEMENTS |
| Kernel (typed graph) | compileFigureGraph, FIGURE_OPERATORS, FIGURE_NON_AFFINE_OPERATORS, FIGURE_STATE_NON_AFFINE_OPERATORS, FIGURE_OPERATOR_STATE_POLICY, figureShapeFaces, FIGURE_KERNEL_VERSION, FIGURE_FACE_NORMALS; graph types (FigureGraph, FigureCompiledGraph, …) |
| Instance size | FIGURE_INSTANCE_SIZE_INPUTS, figureInstanceSizeRangeOf, figureInstanceSizeLimitsOf, recordFigureInstanceSize, forgetRecordedInstanceSize, fitNarrowedInstanceSize, figureSizeRangeFitsOf |
| Motion and state | driverValue, driverStates, normalisePhase, validateFigureDrivers, validateFigureStateInputs, advanceStateValue, stateInputPolicy |
| Authoring commands | createFigureAsset, addFigureBox, addFigurePrimitive, editFigurePart, applyFigureAuthoring, proposeFigureOccupancy, proposeFigureProportion, checkFigureJoints, figureAttachmentsOf, figureBindingsOf |
| Editor workspace | createFigureEditorWorkspace |
| Release gate | inspectFigureAsset, FIGURE_INSPECT_LIMITS, figureWorldBoxesOf, figureOccupiedBoxesOf, figureWritersOf, figurePartsExtentOf, figureContractChanges |
| Score and cost | figureScoreOf, figureGradeOf, figurePartCountOf, figurePartBudgetOf, figureCostOf, figureTrianglesOf |
| Runtime tessellation | figureRenderViewOf, figureRenderSegmentsOf, FigureRenderLevel; source evaluation, inspection and score remain full |
| AI proposal grammar | applyFigureProposal, FIGURE_PROPOSAL_GRAMMAR, FIGURE_PROPOSAL_KINDS |
| Capabilities and documents | compileFigureCapabilities, compileFigureDocument, parseFigureDocument, serializeFigureDocument |
| JSON input boundary | parseFigureJson, assertFigureJson, FIGURE_JSON_MAX_BYTES, FIGURE_JSON_MAX_DEPTH, FigureContractError |
| Shared words | AXES, FIGURE_CAPABILITIES, MATERIAL_PRESETS, SEGMENT_PRESETS, DETAIL_LEVELS, PART_LIMIT, LIMITS, … (words.ts) |
| Example | robotArmFigure, ROBOT_ARM_CHAIN |
Input previews, revision checks and undo/redo are accessed through createFigureEditorWorkspace.
The standalone createFigureAuthoringSession API has been removed; input edit request types remain exported from the package root.
Evaluation results: who owns what
| Call | What the caller gets |
|---|---|
plan.evaluate(inputs) -- a whole evaluation (compileFigureGraph, compileFigureDocument, compileFigureAsset(...).evaluate) | Keeps nothing. Everything in it is the caller's own, to keep or to write into. Types FigureGraphEvaluation, FigureCapabilityEvaluation. |
plan.evaluator().evaluate(inputs), and an advance that evaluates | A snapshot. The values record and the geometry (and bindings) lists are the caller's own; every value and body in them is frozen (Object.freeze) and handed on, as the same object, to later results while it does not change. A write into one throws a TypeError and reaches nothing. Types FigureInstanceEvaluation, FigureCapabilityInstanceEvaluation, whose contents are FigureFrozen<…> (deep readonly). |
advance(inputs) that takes a pose step (kind: 'poses') | Not a snapshot. bodies and poses are the caller's own copies. read(ref) and changed(ref) look into the evaluator and answer only until the next call on it (evaluate or advance, refused or not); after that they throw FigureContractError STEP_EXPIRED. What read returns is frozen. |
Compile, serialize and parse refuse the same assets: compileFigureAsset checks the joint records against the nodes
they make (JOINT_SCHEMA, JOINT_DRIFT), as parseFigureAsset does. compileFigureGraph keeps no size limit of its
own; the byte and node limits belong to the document and asset entrances. inspectFigureAsset refuses settings it
cannot run (INSPECT_OPTION), and runs of more states than FIGURE_INSPECT_LIMITS.maxStates (INSPECT_BUDGET),
before it evaluates anything.
Commands
npm test type check, source tests, then maintained prototype tests
npm run test:coverage coverage (thresholds: lines 97% · branches 90% · functions 96%)
npm run test:prototypes maintained prototype tests (30 tests in three files)
npm run check type check (source tests included)
npm run build build to dist (tests excluded)
npm run format format sources and docs
Requirements
| Consumers | Node 20 or later. ESM only; no CommonJS output. |
| Development | Node 22.6 or later — npm test runs TypeScript directly (type stripping). |
No enum: Node's type stripping cannot run syntax that needs code generation.
No runtime dependencies; it runs unchanged in the browser. The three devDependencies (typescript, @types/node,
prettier) are not part of dist.
Documents
- design.md — the design and its reasons
- core-semantics.md — core semantics of the kernel
- shape-dimension-contract.md — shape dimensions and how they respond to size
- spatial-contracts.md — spatial contracts
- motion-contract.md — joints, state inputs and drivers
- asset-persistence.md — the stored asset document
- authoring-transactions.md — authoring commands
- capability-bindings.md — capability bindings
- status.md — implementation and verification status