ic10r-node 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Change Log
+
+## 2026/08/12
+
+- [1.0.0]: publish version 1.0.0

package/README.md

@@ -0,0 +1,400 @@
+# ic10r-node
+
+[![npm version](https://badge.fury.io/js/ic10r_node.svg)](https://badge.fury.io/js/ic10r_node)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen)](https://nodejs.org/)
+[![C++23](https://img.shields.io/badge/C%2B%2B-23-blue)](https://isocpp.org/)
+[![License: CC BY-NC-SA](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+
+[中文](./README.zh.md)
+
+## Overview
+
+`ic10r-node` is the Node.js native binding module for the **IC10 Runtime**, providing a complete execution engine for IC10 programs.
+
+IC10 is an assembly-style programming language used in the game [Stationeers](https://store.steampowered.com/app/544550/Stationeers/) to control computers and devices in the game. This module takes the compiled AST and symbol table (produced by [`ic10c-node`](https://www.npmjs.com/package/ic10c-node)) and executes the program tick-by-tick, simulating the IC10 processor's behavior.
+
+## Features
+
+- **Execution Engine** – runs IC10 programs tick-by-tick (`runTick`) or to completion (`runFull`)
+- **Register File & Stack** – full 16-register file (`r0`–`r15`) and stack memory (`push`/`pop`/`peek`/`poke`)
+- **Device Manager** – register external devices and the chip device, query by type/name hash
+- **Device I/O** – read/write logic properties, device stacks, slots, and reagent modes
+- **Execution Control** – `halt`/`sleep` support, instruction limit, tick duration configuration
+- **Cross‑Platform** – builds on Linux (GCC/Clang) and Windows (MSVC)
+
+## Installation
+
+### Prerequisites
+
+- Node.js >= 16.0.0 (Node.js 26.x recommended)
+- C++ compiler (GCC 13+ / Clang 16+ / MSVC 2022)
+- CMake >= 3.28.1
+- [`ic10c-node`](https://www.npmjs.com/package/ic10c-node) (peer dependency for compilation)
+
+### Install from npm
+
+```bash
+npm install ic10r-node ic10c-node
+```
+
+### Build from Source
+
+```bash
+# Clone repository
+git clone https://github.com/edoCsItahW/Stationeers.git
+cd Stationeers/code/IC10/backend/runtime
+
+# Install dependencies
+npm install
+
+# Download Node.js headers
+npx node-gyp install
+
+# Build native module
+npm run build
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import * as ic10c from 'ic10c-node';
+import * as ic10r from 'ic10r-node';
+
+// IC10 source code
+const source = `
+    main:
+        move r0 42
+        add r1 r0 10
+        hcf
+`;
+
+// 1. Compile (using ic10c-node)
+const tokens = ic10c.Lexer.tokenize(source);
+const program = new ic10c.Parser(tokens).parse();
+const analyser = new ic10c.Analyser();
+await analyser.visit(program);
+
+// 2. Create engine (using ic10r-node)
+const engine = new ic10r.Engine(program, analyser.symbolTable);
+
+// 3. Execute
+engine.runFull();
+
+// 4. Inspect results
+const r0 = engine.context.memory.getReg('r0');  // 42
+const r1 = engine.context.memory.getReg('r1');  // 52
+console.log(`r0 = ${r0}, r1 = ${r1}`);
+```
+
+### Tick-by-Tick Execution
+
+```typescript
+import * as ic10c from 'ic10c-node';
+import * as ic10r from 'ic10r-node';
+
+const source = `
+    loop:
+        move r0 1
+        yield
+        jal loop
+`;
+
+const tokens = ic10c.Lexer.tokenize(source);
+const program = new ic10c.Parser(tokens).parse();
+const analyser = new ic10c.Analyser();
+await analyser.visit(program);
+
+const engine = new ic10r.Engine(program, analyser.symbolTable);
+
+// Run one tick at a time
+engine.runTick();  // executes one tick
+engine.runTick();  // executes next tick
+```
+
+### Device Interaction
+
+```typescript
+import * as ic10c from 'ic10c-node';
+import * as ic10r from 'ic10r-node';
+
+const source = `
+    alias led d0
+    main:
+        s led Setting 1
+        hcf
+`;
+
+const tokens = ic10c.Lexer.tokenize(source);
+const program = new ic10c.Parser(tokens).parse();
+const analyser = new ic10c.Analyser();
+await analyser.visit(program);
+
+const engine = new ic10r.Engine(program, analyser.symbolTable);
+
+// Register an external device
+const device = engine.context.manager.getDevice('d0');
+engine.context.manager.setExternalDevice('d0', device);
+
+engine.runFull();
+
+// Read device logic after execution
+console.log(device.readLogic('Setting'));  // 1
+```
+
+## API Reference
+
+### Classes
+
+| Class | Description |
+|:------|:------------|
+| `Engine` | IC10 program execution engine |
+| `Context` | Execution context (PC, memory, manager) |
+| `Memory` | Register file and stack memory |
+| `Manager` | Device manager |
+| `Device` | Device I/O interface (logic, slots, reagents) |
+
+### Config
+
+```typescript
+import type { Config } from 'ic10r-node';
+
+const config: Config = {
+    tickDuration: 0.5,       // seconds per tick
+    maxInstructions: 128,     // max instructions per tick
+    maxStackSize: 512         // max stack size
+};
+```
+
+### Engine
+
+```typescript
+import { Engine } from 'ic10r-node';
+import type { Program, SymbolTable } from 'ic10c-node';
+
+// Create engine with optional config
+const engine = new Engine(program, symbolTable, {
+    tickDuration: 0.5,
+    maxInstructions: 128
+});
+
+// Execute
+engine.runTick();  // one tick
+engine.runFull();  // until halt
+
+// Access context
+const ctx = engine.context;
+console.log(ctx.pc);            // program counter
+console.log(ctx.halted);         // halted flag
+```
+
+### Context
+
+```typescript
+const ctx = engine.context;
+
+// Program counter
+ctx.pc = 0;
+
+// Memory access
+const memory = ctx.memory;
+
+// Device manager
+const manager = ctx.manager;
+
+// Execution control
+ctx.halt();           // halt execution
+ctx.sleep(1.0);       // sleep for 1 second
+console.log(ctx.isSleeping);
+```
+
+### Memory
+
+```typescript
+const mem = engine.context.memory;
+
+// Register access
+mem.setReg('r0', 42);
+const r0 = mem.getReg('r0');  // 42
+
+// Stack operations
+mem.push(100);
+mem.push(200);
+const top = mem.peek();  // 200
+const val = mem.pop();  // 200
+
+// Direct stack access
+mem.setStack(0, 999);
+const s0 = mem.getStack(0);  // 999
+
+// Serialize
+const json = mem.toJSON();
+```
+
+### Manager
+
+```typescript
+const mgr = engine.context.manager;
+
+// Device registration
+mgr.setExternalDevice('d0', device);
+mgr.setChipDevice(chipDevice);
+
+// Device lookup
+const dev = mgr.getDevice('d0');
+const found = mgr.findDeviceByType(typeHash);
+const all = mgr.findDevicesByType(typeHash);
+```
+
+### Device
+
+```typescript
+const dev = mgr.getDevice('d0');
+
+// Logic properties
+dev.writeLogic('Setting', 1);
+const val = dev.readLogic('Setting');
+
+// Device stack
+dev.writeStack(0, 42);
+const s0 = dev.readStack(0);
+
+// Slots
+dev.writeSlot(0, 'Occupied', 1);
+const occ = dev.readSlot(0, 'Occupied');
+
+// Reagents
+const mode = dev.readReagent(0);
+const amount = dev.queryReagentAmount(reagentHash);
+
+// Metadata
+const typeHash = dev.getTypeHash();
+const nameHash = dev.getNameHash();
+
+// Lifecycle
+dev.tick();
+dev.clearStack();
+```
+
+## IC10 Instruction Examples
+
+### Arithmetic
+
+```ic10
+move r0 10
+move r1 20
+add r2 r0 r1    # r2 = 30
+sub r3 r2 5     # r3 = 25
+mul r4 r3 2     # r4 = 50
+div r5 r4 5     # r5 = 10
+```
+
+### Control Flow
+
+```ic10
+loop:
+    move r0 1
+    yield
+    jal loop
+```
+
+### Device I/O
+
+```ic10
+alias led d0
+s led Setting 1
+r r0 led Setting
+```
+
+## TypeScript
+
+This module includes complete TypeScript type definitions.
+
+```typescript
+import { Engine, Context, Memory, Manager, Device } from 'ic10r-node';
+import type { Config } from 'ic10r-node';
+
+const config: Config = {
+    tickDuration: 0.5,
+    maxInstructions: 128,
+    maxStackSize: 512
+};
+```
+
+## Build Instructions
+
+### Requirements
+
+- **Node.js**: 16.0.0+
+- **CMake**: 3.28.1+
+- **C++ Compiler**:
+  - Linux: GCC 13+ or Clang 16+
+  - Windows: MSVC 2022
+
+### Build Steps
+
+```bash
+# 1. Install Node.js dependencies
+npm install
+
+# 2. Download Node.js headers
+npx node-gyp install
+
+# 3. Configure CMake
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
+
+# 4. Build
+cmake --build build --parallel 4
+
+# 5. Copy generated .node file
+cp build/ic10r-node.node src/
+```
+
+## Project Structure
+
+```
+ic10r-node/
+├── src/
+│   └── ic10r-node.node   # Native module (built)
+├── types/
+│   ├── index.d.ts         # TypeScript type definitions (entry)
+│   ├── config.d.ts         # Config interface
+│   ├── context.d.ts        # Context class
+│   ├── device.d.ts         # Device class
+│   ├── engine.d.ts         # Engine class
+│   ├── manager.d.ts        # Manager class
+│   └── memory.d.ts         # Memory class
+├── tsconfig.json
+├── package.json
+└── README.md
+```
+
+## License
+
+This project is licensed under **CC BY-NC-SA 4.0** (Creative Commons Attribution-NonCommercial-ShareAlike 4.0).
+
+[![License: CC BY-NC-SA](https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Contact
+
+- **Author**: edocsitahw
+- **Email**: edocsitahw@qq.com
+- **Repository**: [https://github.com/edoCsItahW/Stationeers](https://github.com/edoCsItahW/Stationeers)
+
+## Related Links
+
+- [ic10c-node – IC10 Compiler Node.js Bindings](https://www.npmjs.com/package/ic10c-node)
+- [Stationeers Official Website](https://store.steampowered.com/app/544550/Stationeers/)
+- [Node.js N-API Documentation](https://nodejs.org/api/n-api.html)
+- [node-addon-api Documentation](https://github.com/nodejs/node-addon-api)

package/README.zh.md

@@ -0,0 +1,400 @@
+# ic10r_node
+
+[![npm 版本](https://badge.fury.io/js/ic10r-node.svg)](https://badge.fury.io/js/ic10r_node)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen)](https://nodejs.org/)
+[![C++23](https://img.shields.io/badge/C%2B%2B-23-blue)](https://isocpp.org/)
+[![许可证: CC BY-NC-SA](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+
+[English](README.md)
+
+## 简介
+
+`ic10r-node` 是 **IC10 运行时** 的 Node.js 原生绑定模块，提供了完整的 IC10 程序执行引擎。
+
+IC10 是一种用于 [Stationeers](https://store.steampowered.com/app/544550/Stationeers/) 游戏的汇编式编程语言，用于控制游戏中的计算机和设备。本模块接收编译后的 AST 和符号表（由 [`ic10c-node`](https://www.npmjs.com/package/ic10c-node) 生成），逐 tick 执行程序，模拟 IC10 处理器的行为。
+
+## 特性
+
+- **执行引擎 (Engine)** - 逐 tick 执行（`runTick`）或一次性执行到结束（`runFull`）
+- **寄存器文件和栈** - 完整的 16 寄存器文件（`r0`–`r15`）和栈内存（`push`/`pop`/`peek`/`poke`）
+- **设备管理器 (Manager)** - 注册外部设备和芯片设备，按类型/名称哈希查询
+- **设备 I/O** - 读写逻辑属性、设备栈、插槽和试剂模式
+- **执行控制** - 支持 `halt`/`sleep`，可配置指令上限和 tick 时长
+- **跨平台** - 支持 Linux (GCC/Clang) 和 Windows (MSVC)
+
+## 安装
+
+### 前提条件
+
+- Node.js >= 16.0.0（推荐 Node.js 26.x）
+- C++ 编译器 (GCC 13+ / Clang 16+ / MSVC 2022)
+- CMake >= 3.28.1
+- [`ic10c-node`](https://www.npmjs.com/package/ic10c-node)（编译阶段的依赖）
+
+### 从 npm 安装
+
+```bash
+npm install ic10r-node ic10c-node
+```
+
+### 从源码构建
+
+```bash
+# 克隆仓库
+git clone https://github.com/edoCsItahW/Stationeers.git
+cd Stationeers/code/IC10/backend/runtime
+
+# 安装依赖
+npm install
+
+# 下载 Node.js 头文件
+npx node-gyp install
+
+# 构建原生模块
+npm run build
+```
+
+## 快速开始
+
+### 基本用法
+
+```typescript
+import * as ic10c from 'ic10c-node';
+import * as ic10r from 'ic10r-node';
+
+// IC10 源代码
+const source = `
+    main:
+        move r0 42
+        add r1 r0 10
+        hcf
+`;
+
+// 1. 编译（使用 ic10c-node）
+const tokens = ic10c.Lexer.tokenize(source);
+const program = new ic10c.Parser(tokens).parse();
+const analyser = new ic10c.Analyser();
+await analyser.visit(program);
+
+// 2. 创建引擎（使用 ic10r-node）
+const engine = new ic10r.Engine(program, analyser.symbolTable);
+
+// 3. 执行
+engine.runFull();
+
+// 4. 查看结果
+const r0 = engine.context.memory.getReg('r0');  // 42
+const r1 = engine.context.memory.getReg('r1');  // 52
+console.log(`r0 = ${r0}, r1 = ${r1}`);
+```
+
+### 逐 Tick 执行
+
+```typescript
+import * as ic10c from 'ic10c-node';
+import * as ic10r from 'ic10r-node';
+
+const source = `
+    loop:
+        move r0 1
+        yield
+        jal loop
+`;
+
+const tokens = ic10c.Lexer.tokenize(source);
+const program = new ic10c.Parser(tokens).parse();
+const analyser = new ic10c.Analyser();
+await analyser.visit(program);
+
+const engine = new ic10r.Engine(program, analyser.symbolTable);
+
+// 逐 tick 执行
+engine.runTick();  // 执行一个 tick
+engine.runTick();  // 执行下一个 tick
+```
+
+### 设备交互
+
+```typescript
+import * as ic10c from 'ic10c-node';
+import * as ic10r from 'ic10r-node';
+
+const source = `
+    alias led d0
+    main:
+        s led Setting 1
+        hcf
+`;
+
+const tokens = ic10c.Lexer.tokenize(source);
+const program = new ic10c.Parser(tokens).parse();
+const analyser = new ic10c.Analyser();
+await analyser.visit(program);
+
+const engine = new ic10r.Engine(program, analyser.symbolTable);
+
+// 注册外部设备
+const device = engine.context.manager.getDevice('d0');
+engine.context.manager.setExternalDevice('d0', device);
+
+engine.runFull();
+
+// 执行后读取设备逻辑
+console.log(device.readLogic('Setting'));  // 1
+```
+
+## API 文档
+
+### 类
+
+| 类 | 说明 |
+|:---|:---|
+| `Engine` | IC10 程序执行引擎 |
+| `Context` | 执行上下文（PC、内存、管理器） |
+| `Memory` | 寄存器文件和栈内存 |
+| `Manager` | 设备管理器 |
+| `Device` | 设备 I/O 接口（逻辑、插槽、试剂） |
+
+### Config
+
+```typescript
+import type { Config } from 'ic10r-node';
+
+const config: Config = {
+    tickDuration: 0.5,       // 每 tick 秒数
+    maxInstructions: 128,     // 每 tick 最大指令数
+    maxStackSize: 512         // 最大栈大小
+};
+```
+
+### Engine
+
+```typescript
+import { Engine } from 'ic10r-node';
+import type { Program, SymbolTable } from 'ic10c-node';
+
+// 创建引擎，可选配置
+const engine = new Engine(program, symbolTable, {
+    tickDuration: 0.5,
+    maxInstructions: 128
+});
+
+// 执行
+engine.runTick();  // 一个 tick
+engine.runFull();  // 执行到 halt
+
+// 访问上下文
+const ctx = engine.context;
+console.log(ctx.pc);            // 程序计数器
+console.log(ctx.halted);         // 停机标志
+```
+
+### Context
+
+```typescript
+const ctx = engine.context;
+
+// 程序计数器
+ctx.pc = 0;
+
+// 内存访问
+const memory = ctx.memory;
+
+// 设备管理器
+const manager = ctx.manager;
+
+// 执行控制
+ctx.halt();           // 停止执行
+ctx.sleep(1.0);       // 休眠 1 秒
+console.log(ctx.isSleeping);
+```
+
+### Memory
+
+```typescript
+const mem = engine.context.memory;
+
+// 寄存器访问
+mem.setReg('r0', 42);
+const r0 = mem.getReg('r0');  // 42
+
+// 栈操作
+mem.push(100);
+mem.push(200);
+const top = mem.peek();  // 200
+const val = mem.pop();  // 200
+
+// 直接栈访问
+mem.setStack(0, 999);
+const s0 = mem.getStack(0);  // 999
+
+// 序列化
+const json = mem.toJSON();
+```
+
+### Manager
+
+```typescript
+const mgr = engine.context.manager;
+
+// 设备注册
+mgr.setExternalDevice('d0', device);
+mgr.setChipDevice(chipDevice);
+
+// 设备查找
+const dev = mgr.getDevice('d0');
+const found = mgr.findDeviceByType(typeHash);
+const all = mgr.findDevicesByType(typeHash);
+```
+
+### Device
+
+```typescript
+const dev = mgr.getDevice('d0');
+
+// 逻辑属性
+dev.writeLogic('Setting', 1);
+const val = dev.readLogic('Setting');
+
+// 设备栈
+dev.writeStack(0, 42);
+const s0 = dev.readStack(0);
+
+// 插槽
+dev.writeSlot(0, 'Occupied', 1);
+const occ = dev.readSlot(0, 'Occupied');
+
+// 试剂
+const mode = dev.readReagent(0);
+const amount = dev.queryReagentAmount(reagentHash);
+
+// 元数据
+const typeHash = dev.getTypeHash();
+const nameHash = dev.getNameHash();
+
+// 生命周期
+dev.tick();
+dev.clearStack();
+```
+
+## IC10 指令示例
+
+### 算术运算
+
+```ic10
+move r0 10
+move r1 20
+add r2 r0 r1    # r2 = 30
+sub r3 r2 5     # r3 = 25
+mul r4 r3 2     # r4 = 50
+div r5 r4 5     # r5 = 10
+```
+
+### 控制流
+
+```ic10
+loop:
+    move r0 1
+    yield
+    jal loop
+```
+
+### 设备 I/O
+
+```ic10
+alias led d0
+s led Setting 1
+r r0 led Setting
+```
+
+## TypeScript
+
+本模块附带完整的 TypeScript 类型定义，无需额外安装 `@types` 包。
+
+```typescript
+import { Engine, Context, Memory, Manager, Device } from 'ic10r-node';
+import type { Config } from 'ic10r-node';
+
+const config: Config = {
+    tickDuration: 0.5,
+    maxInstructions: 128,
+    maxStackSize: 512
+};
+```
+
+## 构建说明
+
+### 环境要求
+
+- **Node.js**: 16.0.0+
+- **CMake**: 3.28.1+
+- **C++ 编译器**:
+  - Linux: GCC 13+ 或 Clang 16+
+  - Windows: MSVC 2022
+
+### 构建步骤
+
+```bash
+# 1. 安装 Node.js 依赖
+npm install
+
+# 2. 下载 Node.js 头文件
+npx node-gyp install
+
+# 3. 配置 CMake
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
+
+# 4. 编译
+cmake --build build --parallel 4
+
+# 5. 复制生成的 .node 文件
+cp build/ic10r-node.node src/
+```
+
+## 项目结构
+
+```
+ic10r-node/
+├── src/
+│   └── ic10r-node.node   # 原生模块（编译生成）
+├── types/
+│   ├── index.d.ts         # TypeScript 类型定义（入口）
+│   ├── config.d.ts         # Config 接口
+│   ├── context.d.ts        # Context 类
+│   ├── device.d.ts         # Device 类
+│   ├── engine.d.ts         # Engine 类
+│   ├── manager.d.ts        # Manager 类
+│   └── memory.d.ts         # Memory 类
+├── tsconfig.json
+├── package.json
+└── README.md
+```
+
+## 许可证
+
+本项目采用 **CC BY-NC-SA 4.0** (Creative Commons Attribution-NonCommercial-ShareAlike 4.0) 许可证。
+
+[![License: CC BY-NC-SA](https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'Add amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 创建 Pull Request
+
+## 联系方式
+
+- **作者**: edocsitahw
+- **邮箱**: edocsitahw@qq.com
+- **仓库**: [https://github.com/edoCsItahW/Stationeers](https://github.com/edoCsItahW/Stationeers)
+
+## 相关链接
+
+- [ic10c-node – IC10 编译器 Node.js 绑定](https://www.npmjs.com/package/ic10c-node)
+- [Stationeers 官方网站](https://store.steampowered.com/app/544550/Stationeers/)
+- [Node.js N-API 文档](https://nodejs.org/api/n-api.html)
+- [node-addon-api 文档](https://github.com/nodejs/node-addon-api)

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "ic10r-node",
+    "version": "1.0.0",
+    "description": "IC10 Runtime Node.js Native Bindings - IC10 program execution engine | IC10 运行时 Node.js 原生绑定 - IC10 程序执行引擎",
+    "main": "src/ic10r-node.node",
+    "types": "types/index.d.ts",
+    "files": [
+        "src/",
+        "types/",
+        "tsconfig.json",
+        "CHANGELOG.md"
+    ],
+    "engines": {
+        "node": ">=16.0.0"
+    },
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "ic10",
+        "stationeers",
+        "runtime",
+        "engine",
+        "executor",
+        "native-addon",
+        "node-addon-api",
+        "n-api"
+    ],
+    "author": "edocsitahw <edocsitahw@qq.com>",
+    "contributors": [
+        "edocsitahw"
+    ],
+    "license": "CC BY-NC-SA",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/edoCsItahW/Stationeers.git",
+        "directory": "code/IC10/backend/runtime/publish/node"
+    },
+    "homepage": "https://github.com/edoCsItahW/Stationeers/blob/main/README.md",
+    "bugs": {
+        "url": "https://github.com/edoCsItahW/Stationeers/issues",
+        "email": "2257699870@qq.com"
+    },
+    "devDependencies": {
+        "@types/node": "^26.1.1"
+    }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+    "compilerOptions": {
+        "target": "es2020",
+        "lib": ["es2020"],
+        "module": "nodenext",
+        "moduleResolution": "nodenext",
+        "sourceMap": true,
+        "strict": true,
+        "outDir": "out",
+        "rootDir": "src",
+        "esModuleInterop": true,
+        "skipLibCheck": true
+    },
+    "include": ["src"],
+    "exclude": ["node_modules", ".vscode-test"]
+}

package/types/config.d.ts

@@ -0,0 +1,20 @@
+// Copyright (c) 2026. All rights reserved.
+// This source code is licensed under the CC BY-NC-SA
+// (Creative Commons Attribution-NonCommercial-NoDerivatives) License, By Xiao Songtao.
+// This software is protected by copyright law. Reproduction, distribution, or use for commercial
+// purposes is prohibited without the author's permission. If you have any questions or require
+// permission, please contact the author: edocsitahw@qq.com
+
+/**
+ * @file config.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/08/12 14:02
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+export interface Config {
+    tickDuration: number;
+    maxInstructions: number;
+    maxStackSize: number;
+}

package/types/context.d.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2026. All rights reserved.
+// This source code is licensed under the CC BY-NC-SA
+// (Creative Commons Attribution-NonCommercial-NoDerivatives) License, By Xiao Songtao.
+// This software is protected by copyright law. Reproduction, distribution, or use for commercial
+// purposes is prohibited without the author's permission. If you have any questions or require
+// permission, please contact the author: edocsitahw@qq.com
+
+/**
+ * @file context.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/08/12 14:49
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+import { Manager } from "./manager";
+import { Config } from "./config";
+import { Memory } from "./memory";
+
+
+export class Context {
+
+    constructor(program: Program, symbols: SymbolTable, public config: Config);
+
+    pc: number;
+
+    get memory(): Memory;
+
+    get manager(): Manager;
+
+    halt(): void;
+
+    get halted(): boolean;
+
+    sleep(seconds: number): void;
+
+    get isSleeping(): boolean;
+
+}

package/types/device.d.ts

@@ -0,0 +1,44 @@
+// Copyright (c) 2026. All rights reserved.
+// This source code is licensed under the CC BY-NC-SA
+// (Creative Commons Attribution-NonCommercial-NoDerivatives) License, By Xiao Songtao.
+// This software is protected by copyright law. Reproduction, distribution, or use for commercial
+// purposes is prohibited without the author's permission. If you have any questions or require
+// permission, please contact the author: edocsitahw@qq.com
+
+/**
+ * @file device.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/08/12 14:06
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+export class Device{
+    readLogic(prop: string): number;
+
+    writeLogic(prop: string, value: number): void;
+
+    canReadLogic(prop: string): boolean;
+
+    canWriteLogic(prop: string): boolean;
+
+    readStack(index: number): number;
+
+    writeStack(index: number, value: number): void;
+
+    readSlot(index: number, slot: string): number;
+
+    writeSlot(index: number, slot: string, value: number): void;
+
+    readReagent(mode: number): number;
+
+    queryReagentAmount(reagentHash: number): number;
+
+    getTypeHash(): number;
+
+    getNameHash(): number;
+
+    clearStack(): void;
+
+    tick(): void;
+}

package/types/engine.d.ts

@@ -0,0 +1,30 @@
+// Copyright (c) 2026. All rights reserved.
+// This source code is licensed under the CC BY-NC-SA
+// (Creative Commons Attribution-NonCommercial-NoDerivatives) License, By Xiao Songtao.
+// This software is protected by copyright law. Reproduction, distribution, or use for commercial
+// purposes is prohibited without the author's permission. If you have any questions or require
+// permission, please contact the author: edocsitahw@qq.com
+
+/**
+ * @file engine.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/08/12 14:46
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+import { Context } from "./context";
+import { Config } from "./config";
+
+
+export class Engine {
+
+    constructor(program: Program, symbols: SymbolTable, config?: Partial<Config>);
+
+    runTick(): void;
+
+    runFull(): void;
+
+    get context(): Context;
+
+}

package/types/index.d.ts

@@ -0,0 +1,21 @@
+// Copyright (c) 2026. All rights reserved.
+// This source code is licensed under the CC BY-NC-SA
+// (Creative Commons Attribution-NonCommercial-NoDerivatives) License, By Xiao Songtao.
+// This software is protected by copyright law. Reproduction, distribution, or use for commercial
+// purposes is prohibited without the author's permission. If you have any questions or require
+// permission, please contact the author: edocsitahw@qq.com
+
+/**
+ * @file index.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/08/12 14:46
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+export * from "./config";
+export * from "./context";
+export * from "./device";
+export * from "./engine";
+export * from "./manager";
+export * from "./memory";

package/types/manager.d.ts

@@ -0,0 +1,36 @@
+// Copyright (c) 2026. All rights reserved.
+// This source code is licensed under the CC BY-NC-SA
+// (Creative Commons Attribution-NonCommercial-NoDerivatives) License, By Xiao Songtao.
+// This software is protected by copyright law. Reproduction, distribution, or use for commercial
+// purposes is prohibited without the author's permission. If you have any questions or require
+// permission, please contact the author: edocsitahw@qq.com
+
+/**
+ * @file manager.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/08/12 14:40
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+import { Device } from "./device";
+
+export class Manager {
+
+    getDevice(name: string): Device;
+
+    setExternalDevice(name: string, device: Device): void;
+
+    setChipDevice(device: Device): void;
+
+    findDeviceByType(typeHash: number): Device;
+
+    findDeviceByTypeAndName(typeHash: number, nameHash: number): Device;
+
+    findDevicesByType(typeHash: number): Device[];
+
+    findDevicesByTypeAndName(typeHash: number, nameHash: number): Device[];
+
+    tick(): void;
+
+}

package/types/memory.d.ts

@@ -0,0 +1,49 @@
+// Copyright (c) 2026. All rights reserved.
+// This source code is licensed under the CC BY-NC-SA
+// (Creative Commons Attribution-NonCommercial-NoDerivatives) License, By Xiao Songtao.
+// This software is protected by copyright law. Reproduction, distribution, or use for commercial
+// purposes is prohibited without the author's permission. If you have any questions or require
+// permission, please contact the author: edocsitahw@qq.com
+
+/**
+ * @file memory.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/08/12 14:51
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+import { Config } from "./config";
+
+
+export class Memory {
+
+    public sp: number;
+
+    constructor(public config: Config);
+
+    toJSON(): string;
+
+    getReg(name: string): number;
+
+    setReg(name: string, value: number): void;
+
+    getStack(index: number): number;
+
+    setStack(index: number, value: number): void;
+
+    push(value: number): void;
+
+    pop(): number;
+
+    peek(): number;
+
+    poke(index: number, value: number): number;
+
+}
+
+export interface MemoryInfo {
+    registers: { [K in `r${0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15}`]: number; };
+    stack: number[];
+    sp: number;
+}