@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.

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, FIGURE_INSTANCE_SIZE_DEFAULT, defaultInstanceSizeRange, foldInstanceSizeRange, figureInstanceSizeLimitsOf | | Motion and state | driverValue, driverStates, normalisePhase, validateFigureDrivers, validateFigureStateInputs, advanceStateValue, stateInputPolicy | | Authoring commands | createFigureAsset, addFigureBox, addFigurePrimitive, editFigurePart, applyFigureAuthoring, proposeFigureOccupancy, proposeFigureProportion, checkFigureJoints, figureAttachmentsOf, figureBindingsOf | | Authoring session | createFigureAuthoringSession, createFigureEditorWorkspace | | Release gate | inspectFigureAsset, figureWorldBoxesOf, figureOccupiedBoxesOf, figureWritersOf, figurePartsExtentOf, figureContractChanges | | Score and cost | figureScoreOf, figureGradeOf, figurePartCountOf, figurePartBudgetOf, figureCostOf, figureTrianglesOf | | 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 |

Commands

npm test               type check, then all tests
npm run test:coverage  coverage (thresholds: lines 100% · branches 95% · functions 100%)
npm run check          type check (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