@hatiolab/figure-model

中文文档
0.12.15发布于 2026/11/16UNLICENSEDTypeScriptES Module零依赖近 30 天下载 1.7万

The figure format (figure-asset-1): a kernel that evaluates a figure from its declared relations, the authoring commands a modeller and an AI share, the release gate and the score.

原始使用文档
文档目录7 节
  1. What it solves
  2. Use
  3. Main exports
  4. Evaluation results: who owns what
  5. Commands
  6. Requirements
  7. Documents

@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
1Expressiveness — a shape that could be written in code can be written as data
2Equal performance — drawing from data is as fast as drawing hard-coded geometry
3A 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

AreaExports
Asset documentparseFigureAsset, 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 sizeFIGURE_INSTANCE_SIZE_INPUTS, figureInstanceSizeRangeOf, figureInstanceSizeLimitsOf, recordFigureInstanceSize, forgetRecordedInstanceSize, fitNarrowedInstanceSize, figureSizeRangeFitsOf
Motion and statedriverValue, driverStates, normalisePhase, validateFigureDrivers, validateFigureStateInputs, advanceStateValue, stateInputPolicy
Authoring commandscreateFigureAsset, addFigureBox, addFigurePrimitive, editFigurePart, applyFigureAuthoring, proposeFigureOccupancy, proposeFigureProportion, checkFigureJoints, figureAttachmentsOf, figureBindingsOf
Editor workspacecreateFigureEditorWorkspace
Release gateinspectFigureAsset, FIGURE_INSPECT_LIMITS, figureWorldBoxesOf, figureOccupiedBoxesOf, figureWritersOf, figurePartsExtentOf, figureContractChanges
Score and costfigureScoreOf, figureGradeOf, figurePartCountOf, figurePartBudgetOf, figureCostOf, figureTrianglesOf
Runtime tessellationfigureRenderViewOf, figureRenderSegmentsOf, FigureRenderLevel; source evaluation, inspection and score remain full
AI proposal grammarapplyFigureProposal, FIGURE_PROPOSAL_GRAMMAR, FIGURE_PROPOSAL_KINDS
Capabilities and documentscompileFigureCapabilities, compileFigureDocument, parseFigureDocument, serializeFigureDocument
JSON input boundaryparseFigureJson, assertFigureJson, FIGURE_JSON_MAX_BYTES, FIGURE_JSON_MAX_DEPTH, FigureContractError
Shared wordsAXES, FIGURE_CAPABILITIES, MATERIAL_PRESETS, SEGMENT_PRESETS, DETAIL_LEVELS, PART_LIMIT, LIMITS, … (words.ts)
ExamplerobotArmFigure, 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

CallWhat 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 evaluatesA 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

ConsumersNode 20 or later. ESM only; no CommonJS output.
DevelopmentNode 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

版本与发布记录

@hatiolab/figure-model 共发布 164 个版本,首次发布于 2026/09/04;过去 12 个月发布了 164 个版本。

版本发布日期距今
0.12.15latest2026/11/161 天前
0.12.142026/11/161 天前
0.12.132026/11/161 天前
0.12.122026/11/152 天前
0.12.112026/11/152 天前
0.12.102026/11/143 天前

关于 @hatiolab/figure-model 的常见问题

@hatiolab/figure-model 是什么?

The figure format (figure-asset-1): a kernel that evaluates a figure from its declared relations, the authoring commands a modeller and an AI share, the release gate and the score.

如何安装 @hatiolab/figure-model?

在项目目录运行 npm install @hatiolab/figure-model,或使用 pnpm add / yarn add / bun add。

@hatiolab/figure-model 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hatiolab/figure-model 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hatiolab/figure-model 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@hatiolab/figure-model 可以商用吗?

@hatiolab/figure-model 使用 UNLICENSED 许可。作者声明为 UNLICENSED,即不授予公开使用许可(与公共领域的 Unlicense 不同)。使用前需获得作者授权。以上为概括,不构成法律意见,请以许可原文为准。

@hatiolab/figure-model 的下载量有多少?

根据 npm 官方下载统计,@hatiolab/figure-model 在 2026/10/18 – 2026/11/16 这 30 天内被下载 16,758 次,日均约 559 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hatiolab/figure-model 还在维护吗?

最新版本 0.12.15 发布于 2026/11/16(1 天前);至今共发布 164 个版本,其中过去 12 个月发布了 164 个;首次发布于 2026/09/04。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。