@fleetx_io/ai-ui-dsl 1.0.0 → 1.0.1

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 (6) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/README.md +2 -13
  3. package/dist/blocks.d.ts +10 -0
  4. package/dist/blocks.d.ts.map +1 -1
  5. package/dist/blocks.js.map +1 -1
  6. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ### Added
10
+
11
+ - **`BaseBlock.streamKey`** (optional string): logical stream identity **authored by the UI Composer Agent**; the **streaming engine** assigns **`id`** and may use matching `streamKey` values to continue one logical block across events. The bundled `messageReducer` does not interpret `streamKey`.
12
+
9
13
  ## [1.0.0] - 2026-03-27
10
14
 
11
15
  ### Added
package/README.md CHANGED
@@ -15,12 +15,13 @@ npm install @fleetx_io/ai-ui-dsl
15
15
  1. **Block composition** — One message = a flat list of blocks; blocks are not nested.
16
16
  2. **Incremental streaming** — Each block follows `block_start → block_delta (0..N) → block_end` (or `block_error`).
17
17
  3. **Immutable reducers** — Feed `StreamEvent`s into `messageReducer`; render the resulting `Message`.
18
+ 4. **IDs and logical streams** — **`id`** is assigned by the **streaming engine** for each block (and used in deltas / end / error events). Optional **`streamKey`** is set by the **UI Composer Agent** so the engine can treat a later `block_start` with the same key as continuing one logical stream instead of a new list entry. The bundled `messageReducer` ignores `streamKey` and always appends on `block_start`.
18
19
 
19
20
  ### Server → client flow
20
21
 
21
22
  ```
22
23
  message_start → create / bind Message
23
- block_start → append Block (status streaming)
24
+ block_start → append Block (status streaming); or engine coalesces by streamKey
24
25
  block_delta → applyDelta → re-render
25
26
  block_end → mark Block completed
26
27
  …
@@ -94,18 +95,6 @@ Functions: `messageReducer`, `applyDelta`, `createEmptyMessage`, `setByPath`, an
94
95
 
95
96
  A **UI Composer Agent** is an LLM layer that does **not** call tools: it takes tool results plus context and returns **`{ blocks: Block[] }`** in this DSL. An **orchestrator** then turns those blocks into an SSE stream (`block_start`, deltas, `block_end`) for the client. Composition heuristics (e.g. open with a short text block, use charts or maps instead of raw JSON in prose, end with suggested actions) are up to your server-side prompt and validation schema.
96
97
 
97
- ## Playground
98
-
99
- Requires **Node 20+**. From the repository root:
100
-
101
- ```bash
102
- npm install
103
- npm run build
104
- npm run playground
105
- ```
106
-
107
- Starts a **Vite** dev server that steps through a canned `StreamEvent` script and shows the reduced `Message` state.
108
-
109
98
  ## License
110
99
 
111
100
  ISC.
package/dist/blocks.d.ts CHANGED
@@ -1,7 +1,17 @@
1
1
  export type BlockStatus = 'streaming' | 'completed' | 'error';
2
2
  export type BaseBlock = {
3
+ /**
4
+ * Per-block identifier in the `Message.blocks` list, used in `block_delta` / `block_end` / `block_error`.
5
+ * Assigned by the **streaming engine** when emitting `block_start` (not by the UI Composer Agent).
6
+ */
3
7
  id: string;
4
8
  type: string;
9
+ /**
10
+ * Logical stream identity, set by the **UI Composer Agent** when composing `{ blocks: [...] }`.
11
+ * The streaming engine uses it (together with engine-generated `id`s) to decide whether a new
12
+ * `block_start` continues an earlier logical stream. Omit when each block is independent.
13
+ */
14
+ streamKey?: string;
5
15
  status?: BlockStatus;
6
16
  priority?: number;
7
17
  createdAt?: number;
package/dist/blocks.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"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"}
package/dist/blocks.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"blocks.js","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AAAA,gFAAgF;AA0MhF,gFAAgF;AAEhF,MAAM,UAAU,WAAW,CAAsB,KAAY,EAAE,IAAO;IAClE,OAAO,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AAC/B,CAAC"}
1
+ {"version":3,"file":"blocks.js","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAoNhF,gFAAgF;AAEhF,MAAM,UAAU,WAAW,CAAsB,KAAY,EAAE,IAAO;IAClE,OAAO,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AAC/B,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fleetx_io/ai-ui-dsl",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "A Domain Specific Language for describing rich, streaming AI chat interfaces via composable Blocks.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",