@flux-lang/core 0.1.13 → 0.1.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +28 -106
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,128 +1,50 @@
1
1
  # @flux-lang/core
2
2
 
3
- Core library for the **Flux** evolving document language: AST types, parser, Render IR, and the legacy v0.1 runtime kernel.
3
+ 1) **What this package is**
4
+ Core AST, parser, Render IR, and runtime kernel for the Flux score language.
4
5
 
5
- Flux is a small, declarative language for **deterministically evolving documents**. The `@flux-lang/core` package is the reference implementation of:
6
+ 2) **When you use it**
7
+ Use it when you need to parse `.flux` sources, render deterministic IR, or execute the runtime kernel.
6
8
 
7
- - The **Flux v0.2 grammar** (with v0.1 compatibility).
8
- - The **FluxDocument AST IR** (parse output).
9
- - The **RenderDocument IR** (resolved render output).
10
- - A minimal **v0.1 runtime kernel** with `docstep` rules and `neighbors.*` semantics.
11
-
12
- ---
13
-
14
- ## Installation
9
+ 3) **Install**
15
10
 
16
11
  ```bash
17
- npm install @flux-lang/core
18
- # or
19
12
  pnpm add @flux-lang/core
20
- # or
21
- yarn add @flux-lang/core
22
- ````
23
-
24
- ---
25
-
26
- ## Basic usage
13
+ ```
27
14
 
28
- ### Parse source → AST IR
15
+ 4) **Basic usage**
29
16
 
30
17
  ```ts
31
- import { parseDocument } from "@flux-lang/core";
18
+ import { parseDocument, renderDocument } from "@flux-lang/core";
32
19
 
33
20
  const source = `
34
- document {
35
- meta {
36
- version = "0.1.0";
37
- title = "Example";
21
+ document {
22
+ meta { version = "0.2.0"; }
23
+ body { page p1 { text t1 { content = "Hello"; } } }
38
24
  }
39
-
40
- state {
41
- param tempo : float [40, 72] @ 60;
42
- }
43
- }
44
25
  `;
45
26
 
46
27
  const doc = parseDocument(source);
47
- // doc is a FluxDocument (AST IR)
48
- ```
49
-
50
- ### Render IR (v0.2)
51
-
52
- ```ts
53
- import { parseDocument, renderDocument } from "@flux-lang/core";
54
-
55
- const doc = parseDocument(source);
56
- const ir = renderDocument(doc, { seed: 123, time: 10, docstep: 2 });
57
- // ir is a RenderDocument (resolved, deterministic Render IR)
58
- ```
59
-
60
- ### Runtime kernel: docstep + neighbors (legacy v0.1)
61
-
62
- ```ts
63
- import {
64
- parseDocument,
65
- initRuntimeState,
66
- runDocstepOnce,
67
- } from "@flux-lang/core";
68
-
69
- const doc = parseDocument(source);
70
-
71
- // Build initial RuntimeState from the document
72
- const state0 = initRuntimeState(doc);
73
-
74
- // Advance one docstep (applies all mode=docstep rules)
75
- const state1 = runDocstepOnce(doc, state0);
28
+ const ir = renderDocument(doc, { seed: 42, docstep: 0, time: 0 });
76
29
  ```
77
30
 
78
- ---
79
-
80
- ## Static checks
81
-
82
- `@flux-lang/core` also exposes a small static checker used by the CLI and VS Code extension:
83
-
84
- ```ts
85
- import { parseDocument, checkDocument } from "@flux-lang/core";
86
-
87
- const doc = parseDocument(source);
88
- const errors = checkDocument("example.flux", doc);
89
-
90
- if (errors.length > 0) {
91
- for (const line of errors) {
92
- console.error(line);
93
- }
94
- }
95
- ```
96
-
97
- Typical diagnostics include:
98
-
99
- * Unknown grid references in `rule ... (grid = main)`.
100
- * Unsupported `neighbors.*` methods.
101
- * Obvious runtime timer issues (e.g. non-positive `timer(...)` amounts).
102
-
103
- ---
104
-
105
- ## Flux IR contract
106
-
107
- The canonical IR is the `FluxDocument` type exported from `@flux-lang/core`. It is:
108
-
109
- * Produced by `parseDocument(source)`.
110
- * Safe to serialize as JSON and pass across process boundaries.
111
- * Used by the CLI (`flux parse`) and editor tooling.
112
-
113
- See the Flux IR spec in the main repo for the full shape and semantics:
114
-
115
- * GitHub: `https://github.com/cbassuarez/flux` (IR docs live under `packages/core/docs/`)
116
-
117
- ---
118
-
119
- ## Related tooling
31
+ 5) **Reference**
32
+ - **Parse**: `parseDocument`
33
+ - **Render**: `renderDocument`, `renderDocumentIR`, `createDocumentRuntime`, `createDocumentRuntimeIR`
34
+ - **Runtime kernel**: `initRuntimeState`, `runDocstepOnce`, `handleEvent`
35
+ - **Static checks**: `checkDocument`
36
+ - **Layout**: `computeGridLayout`
120
37
 
121
- * **CLI:** `@flux-lang/cli` — `flux parse` / `flux check` built on top of this package.
122
- * **VS Code:** `@flux-lang/vscode-flux` — syntax highlighting + diagnostics using `@flux-lang/core`.
38
+ 6) **How it relates to IR/runtime**
39
+ This package defines the AST IR (`FluxDocument`) and the Render IR (`RenderDocument`/`RenderDocumentIR`), and implements the runtime stepping semantics that drive docsteps and time.
123
40
 
124
- ---
41
+ 7) **Gotchas & troubleshooting**
42
+ - `renderDocumentIR` returns stable node IDs for patching and viewer workflows; use it when you need deterministic diffing.
125
43
 
126
- ## License
44
+ 8) **Versioning / compatibility notes**
45
+ - Flux uses semantic versioning in `meta.version`, and `0.x` releases are considered unstable.
127
46
 
128
- MIT – see the LICENSE file in the repo root.
47
+ 9) **Links**
48
+ - Root Flux manual: [`../../README.md`](../../README.md)
49
+ - Render IR spec: [`docs/flux-ir-v0.2.md`](docs/flux-ir-v0.2.md)
50
+ - Source: [`src/`](src/)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@flux-lang/core",
3
- "version": "0.1.13",
3
+ "version": "0.1.14",
4
4
  "description": "Core AST, parser, and evaluator for the Flux score language.",
5
5
  "license": "MIT",
6
6
  "author": "Sebastian Suarez-Solis",