@ixo/editor 6.1.0 → 6.1.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 (15) hide show
  1. package/README.md +208 -328
  2. package/dist/{chunk-RJOVPEAW.js → chunk-KEGZJCNU.js} +2 -2
  3. package/dist/chunk-KEGZJCNU.js.map +1 -0
  4. package/dist/{chunk-JDHRY2V4.js → chunk-LKYQK7IC.js} +2 -2
  5. package/dist/{chunk-F46UTXLR.js → chunk-SQBAOQH2.js} +33 -7
  6. package/dist/{chunk-F46UTXLR.js.map → chunk-SQBAOQH2.js.map} +1 -1
  7. package/dist/core/index.d.ts +3 -3
  8. package/dist/core/index.js +2 -2
  9. package/dist/index.d.ts +1 -1
  10. package/dist/index.js +3 -3
  11. package/dist/mantine/index.js +2 -2
  12. package/dist/{store-CevMFCuS.d.ts → store-DYnbzpF-.d.ts} +5 -5
  13. package/package.json +1 -1
  14. package/dist/chunk-RJOVPEAW.js.map +0 -1
  15. /package/dist/{chunk-JDHRY2V4.js.map → chunk-LKYQK7IC.js.map} +0 -0
package/README.md CHANGED
@@ -1,433 +1,313 @@
1
- # IXO Editor
1
+ # @ixo/editor
2
2
 
3
- A custom BlockNote editor wrapper built specifically for the IXO team's needs. This package provides a highly customized rich text editing experience built on top of [BlockNote](https://www.blocknotejs.org/) with support for both **Shadcn UI** and **Mantine UI**.
3
+ A collaborative, **workflow** editor for the IXO ecosystem, built on [BlockNote](https://www.blocknotejs.org/). Beyond rich text, `@ixo/editor` turns a document into a runnable flow: blocks carry configuration, conditional logic, and executable **actions**, execution is gated by a **flow engine** and authorized with **UCAN** capabilities, and every change is synchronized in real time across collaborators over the Matrix protocol via Yjs CRDTs.
4
4
 
5
- > **Note**: This package is designed for internal IXO team use and is not intended for public consumption, though it is hosted publicly.
5
+ > **Internal package.** Maintained for IXO products (primarily [impacts-x-web](https://github.com/ixoworld)). It is published publicly but is not intended as a general-purpose editor. The public API changes with product needs.
6
+
7
+ ---
8
+
9
+ ## What it is
10
+
11
+ The editor operates in two modes, selected by a document's `docType`:
12
+
13
+ - **Template mode** (`docType: 'template'`) — design time. Authors configure reusable workflow blocks: properties, conditional logic, dependencies, and which actor may execute what.
14
+ - **Flow mode** (`docType: 'flow'`, the default) — run time. Participants execute the configured workflow. Conditions are evaluated live, blocks show/hide/enable accordingly, actions run through the flow engine, and per-block runtime state syncs to every collaborator.
15
+
16
+ Under the hood it combines:
17
+
18
+ - **BlockNote 0.29** + a custom IXO block schema (checkbox, form, list, proposal, claim, bid, action, notify, domain, …).
19
+ - **Yjs CRDTs over Matrix** (`@ixo/matrix-crdt`) for conflict-free, multi-user, persistent state — no separate database required.
20
+ - A **flow engine** that runs blocks through an activation → authorization → invocation → action → storage pipeline.
21
+ - An **action registry** of pluggable action types (`qi/<namespace>.<verb>`) that the generic `action` block dispatches to.
22
+ - **UCAN** delegations and invocations for cryptographic, per-block execution authorization.
23
+ - A **flow compiler** that reads/writes a portable "Base UCAN" flow representation, and a **flow agent** runtime for automated flow progression.
24
+
25
+ For the full picture, start with [`docs/architecture/architecture-overview.md`](docs/architecture/architecture-overview.md) and the plain-language [`docs/authorization/flows-actions-ucans-explained.md`](docs/authorization/flows-actions-ucans-explained.md).
6
26
 
7
27
  ## Features
8
28
 
9
- - 🎨 **Multi-UI Support**: Choose between Shadcn UI or Mantine UI components.
10
- - 🔧 **Simplified API**: Wrapped BlockNote functionality with sensible defaults
11
- - 📝 **Rich Text Editing**: Full support for headings, lists, code blocks, tables, and more
12
- - 🔗 **Custom Blocks**: Built-in custom blocks including dynamic List block for DID data
13
- - 🖼️ **Media Support**: Image and file upload handling
14
- - 🎯 **TypeScript**: Full TypeScript support with exported types
15
- - 🤝 **Collaboration Ready**: Built-in Matrix-based collaborative editing with real-time synchronization
16
- - 📱 **Responsive**: Mobile-friendly editor experience
17
- - 💎 **Complete CSS Bundles**: Self-contained CSS with all dependencies included
29
+ - 🧩 **Workflow blocks** — checkboxes, forms, lists, proposals, claims, bids, API requests, notifications, domain/entity actions, and a generic `action` block.
30
+ - 🔀 **Template vs flow modes** — design reusable workflows, then execute them.
31
+ - 🤝 **Real-time collaboration** — Matrix + Yjs CRDTs; state is collaborative and persistent by default.
32
+ - ⚙️ **Flow engine** — declarative activation conditions, actor authorization, and per-block runtime state.
33
+ - 🔐 **UCAN authorization** — flow owners delegate execution capabilities; invocations provide an auditable trail.
34
+ - 🧠 **Action registry** — add new action types declaratively; the host app supplies the side-effecting handlers.
35
+ - 🖥️ **Server-friendly core** — `@ixo/editor/core` exposes the flow engine, action registry, UCAN, and flow agent with no React/Mantine/BlockNote UI dependencies.
36
+ - 🎨 **Mantine UI** — themable light/dark, self-contained CSS bundles.
37
+ - 🎯 **TypeScript-first** — augmented editor types and exported prop schemas.
18
38
 
19
- ## Installations
39
+ ## Installation
20
40
 
21
41
  ```bash
22
- npm install @ixo/editor
23
- # or
24
- yarn add @ixo/editor
25
- # or
26
42
  pnpm add @ixo/editor
43
+ # or: npm install @ixo/editor / yarn add @ixo/editor
27
44
  ```
28
45
 
29
- ## Quick Start
46
+ ### Peer dependencies
30
47
 
31
- ### Shadcn UI Version (Default)
48
+ | Package | Version | Needed for |
49
+ | --------------------------------------------------- | ---------- | ------------------------------ |
50
+ | `react`, `react-dom` | `^18.0.0` | Everything |
51
+ | `@mantine/core`, `@mantine/hooks`, `@mantine/dates` | `^7.11.2` | The editor UI |
52
+ | `@ixo/matrix-crdt` | `*` | Collaborative editing |
53
+ | `@ixo/surveys` | `^0.1.0` | Form / survey blocks |
54
+ | `matrix-js-sdk` | `>=37.5.0` | Collaborative editing (Matrix) |
32
55
 
33
- ```tsx
34
- import React from 'react';
35
- import { useCreateIxoEditor, IxoEditor } from '@ixo/editor/shadcn';
36
- import '@ixo/editor/style-shadcn.css'; // Complete CSS bundle - no other imports needed!
56
+ > **v6 is Mantine-only.** The Shadcn UI variant that shipped in v2 has been removed. See [Migration](#migration).
37
57
 
38
- function MyEditor() {
39
- const editor = useCreateIxoEditor({
40
- theme: 'light',
41
- initialContent: [
42
- {
43
- type: 'heading',
44
- content: 'Welcome to IXO Editor',
45
- props: { level: 1 },
46
- },
47
- {
48
- type: 'paragraph',
49
- content: 'Start typing to create amazing content!',
50
- },
51
- ],
52
- });
58
+ ## Package entry points
53
59
 
54
- return <IxoEditor editor={editor} onChange={() => console.log('Content changed')} />;
55
- }
56
- ```
60
+ | Import | Contents |
61
+ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
62
+ | `@ixo/editor` | Default entry — the Mantine editor plus the full public API (hooks, components, flow engine, UCAN, flow compiler, flow agent). |
63
+ | `@ixo/editor/mantine` | Explicit Mantine entry (same UI surface). |
64
+ | `@ixo/editor/core` | **UI-free** flow engine, action registry, UCAN, flow compiler, and flow agent. Safe for Node/server consumers (e.g. oracles). |
65
+
66
+ ### CSS bundles
57
67
 
58
- ### Mantine UI Version
68
+ | Stylesheet | Contents |
69
+ | ------------------------------- | -------------------------------------------------------------- |
70
+ | `@ixo/editor/style.css` | Complete bundle: Inter fonts + Mantine + IXO styles (default). |
71
+ | `@ixo/editor/style-mantine.css` | Same as `style.css`. |
72
+ | `@ixo/editor/style-scoped.css` | Scoped variant to reduce global bleed. |
73
+ | `@ixo/editor/style-core.css` | IXO custom styles only (advanced/bring-your-own base). |
74
+
75
+ ## Quick start (standalone)
76
+
77
+ A non-collaborative, single-user editor:
59
78
 
60
79
  ```tsx
61
- import React from 'react';
62
80
  import { MantineProvider } from '@mantine/core';
63
- import { useCreateIxoEditor, IxoEditor } from '@ixo/editor/mantine';
64
- import '@ixo/editor/style-mantine.css'; // Complete CSS bundle - no other imports needed!
81
+ import { useCreateIxoEditor, IxoEditor } from '@ixo/editor';
82
+ import '@ixo/editor/style.css';
65
83
 
66
84
  function MyEditor() {
67
85
  const editor = useCreateIxoEditor({
68
86
  theme: 'light',
69
87
  initialContent: [
70
- {
71
- type: 'heading',
72
- content: 'Welcome to IXO Editor',
73
- props: { level: 1 },
74
- },
88
+ { type: 'heading', content: 'Welcome to the IXO Editor', props: { level: 1 } },
89
+ { type: 'paragraph', content: 'Type “/” to insert a block.' },
75
90
  ],
76
91
  });
77
92
 
78
93
  return (
79
94
  <MantineProvider>
80
- <IxoEditor editor={editor} onChange={() => console.log('Content changed')} />
95
+ <IxoEditor editor={editor} onChange={() => console.log('changed')} />
81
96
  </MantineProvider>
82
97
  );
83
98
  }
84
99
  ```
85
100
 
86
- ## Import Options
87
-
88
- The package provides flexible import patterns to suit your needs:
89
-
90
- ### Option 1: UI-Specific Imports (Recommended)
91
-
92
- ```tsx
93
- // Shadcn version with complete CSS bundle
94
- import { IxoEditor, useCreateIxoEditor } from '@ixo/editor/shadcn';
95
- import '@ixo/editor/style-shadcn.css';
96
-
97
- // Mantine version with complete CSS bundle
98
- import { IxoEditor, useCreateIxoEditor } from '@ixo/editor/mantine';
99
- import '@ixo/editor/style-mantine.css';
100
- ```
101
+ ## Collaborative editing
101
102
 
102
- ### Option 2: Default Import (Shadcn)
103
+ Real-time, multi-user editing backed by a Matrix room. `useCreateCollaborativeIxoEditor` builds the Y.Doc, wires the `MatrixProvider`, and returns the editor alongside the live CRDT handles.
103
104
 
104
105
  ```tsx
105
- // Uses Shadcn version by default for backward compatibility
106
- import { IxoEditor, useCreateIxoEditor } from '@ixo/editor';
106
+ import { MantineProvider } from '@mantine/core';
107
+ import { useCreateCollaborativeIxoEditor, IxoEditor } from '@ixo/editor';
107
108
  import '@ixo/editor/style.css';
108
- ```
109
-
110
- ### CSS Bundle Options
111
-
112
- - `@ixo/editor/style-shadcn.css` - Complete bundle: Inter fonts + Shadcn + IXO styles
113
- - `@ixo/editor/style-mantine.css` - Complete bundle: Inter fonts + Mantine + IXO styles
114
- - `@ixo/editor/style.css` - Default bundle (same as shadcn)
115
- - `@ixo/editor/style-core.css` - Only IXO custom styles (for advanced users)
116
-
117
- ## API Reference
118
-
119
- ### `useCreateIxoEditor`
120
-
121
- The main hook for creating an IXO editor instance. Available in both UI versions.
122
-
123
- ```tsx
124
- const editor = useCreateIxoEditor(options?: IxoEditorOptions);
125
- ```
126
-
127
- #### Options
128
-
129
- | Option | Type | Default | Description |
130
- | ------------------- | --------------------------------- | ------------------ | ----------------------------------------- |
131
- | `theme` | `'light' \| 'dark'` | `'light'` | Editor color theme |
132
- | `uploadFile` | `(file: File) => Promise<string>` | Data URL converter | File upload handler |
133
- | `initialContent` | `PartialBlock[]` | `undefined` | Initial editor content |
134
- | `editable` | `boolean` | `true` | Whether editor is editable |
135
- | `sideMenu` | `boolean` | `true` | Show side menu (drag handle, plus button) |
136
- | `slashMenu` | `boolean` | `true` | Enable slash commands menu |
137
- | `formattingToolbar` | `boolean` | `true` | Show formatting toolbar |
138
- | `linkToolbar` | `boolean` | `true` | Show link toolbar |
139
- | `filePanel` | `boolean` | `true` | Show file panel |
140
- | `tableHandles` | `boolean` | `true` | Show table manipulation handles |
141
-
142
- ### `IxoEditor` Component
143
-
144
- The main editor component. Available in both UI versions with identical APIs.
145
-
146
- ```tsx
147
- <IxoEditor editor={editor} className="my-custom-class" onChange={() => {}} onSelectionChange={() => {}} />
148
- ```
149
-
150
- #### Props
151
-
152
- | Prop | Type | Description |
153
- | ------------------- | ------------------------------ | ----------------------------------------- |
154
- | `editor` | `BlockNoteEditor \| undefined` | Editor instance from `useCreateIxoEditor` |
155
- | `className` | `string` | Additional CSS classes |
156
- | `onChange` | `() => void` | Callback when content changes |
157
- | `onSelectionChange` | `() => void` | Callback when selection changes |
158
- | `children` | `React.ReactNode` | Custom child components |
159
-
160
- ## Advanced Usage
161
-
162
- ### Custom File Upload
163
-
164
- ```tsx
165
- const editor = useCreateIxoEditor({
166
- uploadFile: async (file: File) => {
167
- const formData = new FormData();
168
- formData.append('file', file);
169
-
170
- const response = await fetch('/api/upload', {
171
- method: 'POST',
172
- body: formData,
173
- });
174
-
175
- const { url } = await response.json();
176
- return url;
177
- },
178
- });
179
- ```
180
-
181
- ### Collaborative Editing
182
-
183
- For real-time collaborative editing, use the `useCreateCollaborativeIxoEditor` hook with Matrix protocol:
184
109
 
185
- ```tsx
186
- import { useCreateCollaborativeIxoEditor, IxoEditor } from '@ixo/editor/shadcn';
187
-
188
- function CollaborativeEditor() {
189
- const { editor, connectionStatus } = useCreateCollaborativeIxoEditor({
110
+ function CollaborativeEditor({ matrixClient }) {
111
+ const { editor, connectionStatus, connectedUsers, awarenessInstance } = useCreateCollaborativeIxoEditor({
190
112
  theme: 'light',
113
+ roomId: '!roomId:matrix.org',
114
+ matrixClient,
115
+ permissions: { write: true },
191
116
  user: {
192
- id: 'user-123',
193
- name: 'John Doe',
117
+ id: '@did-ixo-ixo1abc:server', // Matrix user ID
118
+ name: 'Jane Doe',
194
119
  color: '#FF5733',
195
- accessToken: 'your-matrix-access-token',
196
- address: 'your-user-address',
120
+ accessToken: 'matrix-access-token',
121
+ address: 'ixo1abc…', // bech32 address
122
+ did: 'did:ixo:ixo1abc…', // full DID, required for UCAN signing
197
123
  },
198
- matrixClient: matrixClient,
199
- roomId: '!roomId:matrix.org',
200
124
  });
201
125
 
202
126
  return (
203
- <div>
127
+ <MantineProvider>
204
128
  <div>Connection: {connectionStatus}</div>
205
- <IxoEditor editor={editor} />
206
- </div>
129
+ <IxoEditor editor={editor} connectedUsers={connectedUsers} awarenessInstance={awarenessInstance} />
130
+ </MantineProvider>
207
131
  );
208
132
  }
209
133
  ```
210
134
 
211
- ### Dark Theme
135
+ The hook returns `{ editor, connectionStatus, title, yDoc, root, flowArray, connectedUsers, awarenessInstance }`. `permissions.write` defaults to `false` (read-only). See [`docs/architecture/architecture-overview.md`](docs/architecture/architecture-overview.md) for the Y.Doc structure and [`docs/authorization/matrix-permissions.md`](docs/authorization/matrix-permissions.md) for the access model.
212
136
 
213
- ```tsx
214
- const editor = useCreateIxoEditor({
215
- theme: 'dark',
216
- });
217
- ```
137
+ ## Providing handlers
218
138
 
219
- ### Read-Only Mode
139
+ The editor is **domain-agnostic**: it never imports blockchain, DAO, or API code. The host app injects that behavior as `handlers` (and optional `blockRequirements`) on `<IxoEditor>`. Blocks and action types call into these to fetch data and perform side effects.
220
140
 
221
141
  ```tsx
222
- const editor = useCreateIxoEditor({
223
- editable: false,
224
- sideMenu: false,
225
- slashMenu: false,
226
- formattingToolbar: false,
227
- });
142
+ <IxoEditor
143
+ editor={editor}
144
+ handlers={{
145
+ getCurrentUser: () => ({ address: wallet.address, name: wallet.name }),
146
+ submitClaim: async (params) => cosmos.submitClaim(params),
147
+ sendNotification: async (params) => api.notify(params),
148
+ // …implement the handlers your blocks/action types require
149
+ }}
150
+ blockRequirements={{ proposal: { coreAddress: dao.coreAddress } }}
151
+ />
228
152
  ```
229
153
 
230
- ## Custom Blocks
154
+ The full `BlocknoteHandlers` surface (proposals, claims, bids, lists, notifications, domain creation, UCAN signing, user search, …) is exported and documented in [`docs/architecture/architecture-overview.md`](docs/architecture/architecture-overview.md#handlers-external-integration-layer). For action types specifically, handlers are adapted into `ctx.services` via `buildServicesFromHandlers` — see the [action registry](#action-registry) section and [`docs/guides/action-block-pattern.md`](docs/guides/action-block-pattern.md).
231
155
 
232
- The IXO Editor includes custom blocks for working with IXO ecosystem data, available in both UI versions:
156
+ ## `useCreateIxoEditor` options
233
157
 
234
- ### List Block
158
+ | Option | Type | Default | Description |
159
+ | ------------------- | --------------------------------- | ------------------ | -------------------------------------------- |
160
+ | `theme` | `'light' \| 'dark'` | `'light'` | Editor color theme |
161
+ | `docType` | `'template' \| 'flow'` | `'flow'` | Design vs execution mode (local, not synced) |
162
+ | `initialContent` | `PartialBlock[]` | `undefined` | Initial editor content |
163
+ | `uploadFile` | `(file: File) => Promise<string>` | Data-URL converter | File upload handler |
164
+ | `editable` | `boolean` | `true` | Whether the editor is editable |
165
+ | `sideMenu` | `boolean` | `true` | Show side menu (drag handle, plus button) |
166
+ | `slashMenu` | `boolean` | `true` | Enable slash command menu |
167
+ | `formattingToolbar` | `boolean` | `true` | Show formatting toolbar |
168
+ | `linkToolbar` | `boolean` | `true` | Show link toolbar |
169
+ | `filePanel` | `boolean` | `true` | Show file panel |
170
+ | `tableHandles` | `boolean` | `true` | Show table manipulation handles |
235
171
 
236
- The List block displays dynamic data from DID and fragment identifiers, perfect for displaying data from your GraphQL API.
172
+ `useCreateCollaborativeIxoEditor` extends these with `roomId`, `matrixClient`, `user`, `permissions`, and optional `docId` / `title` / `sourceTemplateId` (`IxoCollaborativeEditorOptions`).
237
173
 
238
- ### Overview Block
174
+ ## `<IxoEditor>` props (selected)
239
175
 
240
- The Overview block provides a comprehensive view of entity data from DID identifiers.
176
+ | Prop | Type | Description |
177
+ | --------------------------------------------------- | ---------------------------- | --------------------------------------------- |
178
+ | `editor` | `IxoEditorType \| undefined` | Instance from a create hook |
179
+ | `handlers` | `BlocknoteHandlers` | Host integration callbacks for blocks/actions |
180
+ | `blockRequirements` | `BlockRequirements` | Runtime context data for specific blocks |
181
+ | `translate` | `Translate` | i18n function (`t`) from the host app |
182
+ | `mantineTheme` | `MantineTheme` | Theme object to apply to the editor subtree |
183
+ | `onChange` | `() => void` | Fired on content change |
184
+ | `onSelectionChange` | `() => void` | Fired on selection change |
185
+ | `connectedUsers` / `awarenessInstance` | see collaborative hook | Enable per-block presence indicators |
186
+ | `className`, `children`, `coverImageUrl`, `logoUrl` | — | Layout/customization slots |
241
187
 
242
- #### Usage
188
+ See `IxoEditorProps` in the exported types for the complete list.
243
189
 
244
- Both blocks can be inserted using the slash menu:
190
+ ## Core concepts
245
191
 
246
- **List Block:**
192
+ ### Flow engine
247
193
 
248
- 1. Type `/list` in the editor
249
- 2. Or type `/` and search for "List", "data", or "dynamic"
250
- 3. Configure the DID and fragment identifier in the settings
194
+ `@ixo/editor/core` (`src/core/lib/flowEngine/`) runs a block through a four-stage pipeline:
251
195
 
252
- **Overview Block:**
196
+ 1. **Activation** — are upstream dependency conditions satisfied?
197
+ 2. **Authorization** — is the current actor permitted (whitelist or UCAN delegation chain)?
198
+ 3. **Execution** — `executeNode(...)` orchestrates invocation → action → storage.
199
+ 4. **Runtime** — a Y.Map-backed `FlowRuntimeStateManager` tracks per-block state (`idle`/`running`/`completed`/`failed`) and syncs it via CRDT.
253
200
 
254
- 1. Type `/overview` in the editor
255
- 2. Or type `/` and search for "Overview", "overview-block", or "data-overview"
256
- 3. Configure the DID in the settings
201
+ Runtime state is the source of truth for a block's result — never mirror it into local React state. This rule is spelled out in [`CLAUDE.md`](CLAUDE.md) and [`docs/architecture/block-runtime-state.md`](docs/architecture/block-runtime-state.md).
257
202
 
258
- #### Programmatic Usage
203
+ ### Action registry
259
204
 
260
- ```tsx
261
- // Insert a list block programmatically
262
- editor.insertBlocks(
263
- [
264
- {
265
- type: 'list',
266
- props: {
267
- title: 'My Data List',
268
- did: 'did:ixo:entity123',
269
- fragmentIdentifier: 'claims-data',
270
- },
271
- },
272
- ],
273
- editor.getTextCursorPosition().block,
274
- 'after'
275
- );
276
-
277
- // Insert an overview block programmatically
278
- editor.insertBlocks(
279
- [
280
- {
281
- type: 'overview',
282
- props: {
283
- did: 'did:ixo:entity123',
284
- },
285
- },
286
- ],
287
- editor.getTextCursorPosition().block,
288
- 'after'
289
- );
290
- ```
291
-
292
- ## UI Library Comparison
205
+ The generic `action` block dispatches to a registered action type keyed by a `can` string (`qi/<namespace>.<verb>`). Each action type declares its inputs, output schema, and a `run()` that calls into `ctx.services`. The host app implements the underlying handlers; `buildServicesFromHandlers` wires them in. To add one, follow [`docs/guides/action-block-pattern.md`](docs/guides/action-block-pattern.md) and, for signed actions, [`docs/guides/slide-to-sign-and-diff-guide.md`](docs/guides/slide-to-sign-and-diff-guide.md).
293
206
 
294
- | Feature | Shadcn UI | Mantine UI |
295
- | ----------------- | -------------------- | --------------------- |
296
- | **Bundle Size** | ~46KB CSS | ~173KB CSS |
297
- | **Custom Blocks** | Full-featured | Minimal (expandable) |
298
- | **Theming** | Tailwind-based | CSS-in-JS |
299
- | **Dependencies** | Radix UI primitives | Mantine ecosystem |
300
- | **Customization** | High (CSS variables) | High (theme provider) |
207
+ ### UCAN authorization
301
208
 
302
- ### When to Choose Shadcn UI
209
+ Flow owners (`flowOwnerDid`) issue **delegations** granting specific actors permission to execute specific blocks; **invocations** record proof of execution. Both live in dedicated Y.Doc maps and sync with the document. See [`docs/authorization/ucan-technical.md`](docs/authorization/ucan-technical.md) and [`docs/authorization/ucan-flow-authorization.md`](docs/authorization/ucan-flow-authorization.md).
303
210
 
304
- - ✅ You're already using Tailwind CSS
305
- - ✅ You prefer smaller bundle sizes
306
- - ✅ You want the full-featured custom blocks
307
- - ✅ You like CSS variable-based theming
211
+ ### Flow compiler & flow agent
308
212
 
309
- ### When to Choose Mantine UI
213
+ The **flow compiler** (`src/core/lib/flowCompiler/`) converts between a portable "Base UCAN" flow description and the live Y.Doc (`setupFlowFromBaseUcan`, `readFlowAsBaseUcan`, `compileBaseUcanFlow`, …), enabling flows to be authored, cloned, and merged. The **flow agent** runtime (`src/core/lib/flowAgent/`) drives automated progression of a flow (leases, command queue, policy evaluation, ledger) — see [`docs/flow-engine/`](docs/flow-engine/).
310
214
 
311
- - ✅ You're already using Mantine in your app
312
- - ✅ You prefer component-based theming
313
- - ✅ You want consistent Mantine design language
314
- - ✅ You plan to enhance the minimal blocks with Mantine components
215
+ ## Custom blocks
315
216
 
316
- ## Development
217
+ The IXO block schema is registered automatically by the create hooks. Blocks can be inserted from the slash menu (`/`) or programmatically:
317
218
 
318
- ### Project Structure
319
-
320
- ```
321
- ixo-editor/
322
- ├── src/
323
- │ ├── core/ # Shared infrastructure
324
- │ │ ├── types.ts # Shared types
325
- │ │ ├── hooks/ # Matrix provider
326
- │ │ └── lib/ # GraphQL client & utilities
327
- │ ├── shadcn/ # Shadcn UI implementation
328
- │ │ ├── IxoEditor.tsx
329
- │ │ ├── blocks/ # Full-featured custom blocks
330
- │ │ ├── components/ # Shadcn UI components
331
- │ │ ├── hooks/ # Editor hooks
332
- │ │ └── index.ts # Shadcn exports
333
- │ ├── mantine/ # Mantine UI implementation
334
- │ │ ├── IxoEditor.tsx
335
- │ │ ├── blocks/ # Minimal custom blocks
336
- │ │ ├── hooks/ # Editor hooks
337
- │ │ └── index.ts # Mantine exports
338
- │ ├── styles/ # Source CSS
339
- │ │ └── ixo-editor.css
340
- │ └── index.ts # Main entry (defaults to shadcn)
341
- ├── fonts/ # Inter font files
342
- ├── dist/ # Built JavaScript
343
- │ ├── index.js # Main bundle
344
- │ ├── shadcn/ # Shadcn bundle
345
- │ └── mantine/ # Mantine bundle
346
- ├── style*.css # CSS bundles
347
- └── package.json
219
+ ```tsx
220
+ editor.insertBlocks([{ type: 'list', props: { title: 'Members', did: 'did:ixo:entity123', fragmentIdentifier: 'members' } }], editor.getTextCursorPosition().block, 'after');
348
221
  ```
349
222
 
350
- ### Building the Package
223
+ The full block catalog, prop schemas, and conditional-logic system are documented in [`docs/architecture/architecture-overview.md`](docs/architecture/architecture-overview.md) and [`docs/architecture/editor-type-map.md`](docs/architecture/editor-type-map.md).
351
224
 
352
- ```bash
353
- # Install dependencies
354
- pnpm install
355
-
356
- # Build the package (creates all bundles)
357
- pnpm build
225
+ ## Server-side usage
358
226
 
359
- # Watch for changes during development
360
- pnpm run dev
227
+ Consumers that only need flow logic (e.g. an oracle validating or advancing a flow) can import the UI-free core:
361
228
 
362
- # Type checking
363
- pnpm run type-check
229
+ ```ts
230
+ import { executeNode, isAuthorized, createUcanService, compileBaseUcanFlow, tickFlowAgent } from '@ixo/editor/core';
364
231
  ```
365
232
 
366
- ## Requirements
367
-
368
- - React 18.0.0 or higher
369
- - React DOM 18.0.0 or higher
370
- - Modern browser with ES2020 support
371
- - For collaborative editing: Matrix server access
372
-
373
- ### Additional Requirements by UI Library
374
-
375
- **For Mantine version:**
233
+ This entry point pulls in **no** React, Mantine, or BlockNote code.
376
234
 
377
- - `@mantine/core` ^8.0.0 (peer dependency)
378
- - `@mantine/hooks` ^8.0.0 (peer dependency)
235
+ ## Documentation
379
236
 
380
- **For Shadcn version:**
237
+ All documentation lives in [`docs/`](docs/) and is indexed by [`docs/README.md`](docs/README.md). Highlights:
381
238
 
382
- - Works with existing Tailwind CSS setup
383
- - No additional peer dependencies
239
+ - [`docs/architecture/architecture-overview.md`](docs/architecture/architecture-overview.md) — the definitive system reference.
240
+ - [`docs/authorization/flows-actions-ucans-explained.md`](docs/authorization/flows-actions-ucans-explained.md) — flows, actions & UCANs from zero.
241
+ - [`docs/guides/`](docs/guides/) — building action blocks, slide-to-sign + diff views, styling.
242
+ - [`docs/authorization/`](docs/authorization/) — UCANs, signing, Matrix permissions.
243
+ - [`docs/flow-engine/`](docs/flow-engine/) — engine design rationale and roadmap.
244
+ - [`docs/integrations/`](docs/integrations/) — third-party integrations (Calendar, Xero via Composio).
245
+ - [`CLAUDE.md`](CLAUDE.md) — project rules and the condensed runtime-state canon.
246
+ - [`CONTEXT.md`](CONTEXT.md) — domain glossary (ubiquitous language).
384
247
 
385
- ## Migration Guide
386
-
387
- ### From v1.x to v2.x (Multi-UI)
388
-
389
- **Before (v1.x):**
248
+ ## Development
390
249
 
391
- ```tsx
392
- import { IxoEditor } from '@ixo/editor';
393
- import '@blocknote/shadcn/style.css';
394
- import '@ixo/editor/style.css';
250
+ ```bash
251
+ pnpm install # install dependencies
252
+ pnpm build # build all bundles (tsup → dist/, + CSS)
253
+ pnpm run dev # rebuild on change
254
+ pnpm run type-check # tsc --noEmit
255
+ pnpm test # vitest
256
+ pnpm run example:action-gallery # run the action-type gallery example app
395
257
  ```
396
258
 
397
- **After (v2.x) - Recommended:**
259
+ ### Project structure
398
260
 
399
- ```tsx
400
- // Explicit shadcn version with complete CSS bundle
401
- import { IxoEditor } from '@ixo/editor/shadcn';
402
- import '@ixo/editor/style-shadcn.css'; // Single import!
261
+ ```
262
+ editor/
263
+ ├── src/
264
+ │ ├── core/ # UI-free core (flow engine, action registry, UCAN,
265
+ │ │ │ # flow compiler, flow agent, types, GraphQL client)
266
+ │ │ └── index.ts # @ixo/editor/core entry
267
+ │ ├── mantine/ # Mantine editor: IxoEditor, hooks, blocks, components, context
268
+ │ │ └── index.ts # @ixo/editor/mantine entry
269
+ │ ├── styles/ # Source CSS
270
+ │ ├── data/ icons/ images/ # Static assets
271
+ │ ├── test-utils/ # Test helpers
272
+ │ └── index.ts # Default entry (Mantine + full public API)
273
+ ├── docs/ # Documentation (see docs/README.md)
274
+ ├── examples/ # Example apps & configs (action-type-gallery, …)
275
+ ├── plans/ # Implementation plans
276
+ ├── fonts/ # Inter font files
277
+ ├── dist/ # Build output (generated)
278
+ ├── style*.css # Published CSS bundles (generated)
279
+ └── package.json
403
280
  ```
404
281
 
405
- **After (v2.x) - Backward compatible:**
282
+ ## Requirements
406
283
 
407
- ```tsx
408
- // Still works! (defaults to shadcn)
409
- import { IxoEditor } from '@ixo/editor';
410
- import '@ixo/editor/style.css'; // Now includes all dependencies
411
- ```
284
+ - React 18+ and React DOM 18+
285
+ - Mantine 7 (`@mantine/core`, `@mantine/hooks`, `@mantine/dates`)
286
+ - A modern browser (ES2020+)
287
+ - For collaboration: a Matrix server, `matrix-js-sdk`, and `@ixo/matrix-crdt`
412
288
 
413
- ## License
289
+ ## Migration
414
290
 
415
- MIT © IXO Team
291
+ ### v2 (multi-UI) → v6 (Mantine-only)
416
292
 
417
- ---
293
+ The Shadcn UI variant and its `@ixo/editor/shadcn` / `style-shadcn.css` entry points have been **removed**. Use the default or `/mantine` entry:
418
294
 
419
- ## Internal Notes
295
+ ```tsx
296
+ // Before (v2)
297
+ import { IxoEditor } from '@ixo/editor/shadcn';
298
+ import '@ixo/editor/style-shadcn.css';
420
299
 
421
- This package is maintained by the IXO development team. For questions or issues, please contact the team directly through internal channels.
300
+ // Now (v6)
301
+ import { IxoEditor, useCreateIxoEditor } from '@ixo/editor';
302
+ import '@ixo/editor/style.css';
303
+ ```
422
304
 
423
- ### Version Management
305
+ The editor also evolved from a rich-text wrapper into a full workflow/flow engine — the flow engine, action registry, UCAN authorization, flow compiler, and flow agent are new since v2. See the [documentation](#documentation) to adopt them.
424
306
 
425
- Follow semantic versioning:
307
+ ## Contributing
426
308
 
427
- - Patch releases (0.0.x): Bug fixes and minor updates
428
- - Minor releases (0.x.0): New features that are backward compatible
429
- - Major releases (x.0.0): Breaking changes (like the multi-UI restructure)
309
+ Internal package. Use [Conventional Commits](https://www.conventionalcommits.org/) (enforced by commitlint; releases are automated via semantic-release). See [`CLAUDE.md`](CLAUDE.md) for project rules and commit format. Record structural repo/doc reorganizations in [`ORGANIZATION-LOG.md`](ORGANIZATION-LOG.md).
430
310
 
431
- ### Contributing
311
+ ## License
432
312
 
433
- This is an internal package. All contributions should go through the standard IXO development workflow and review process.
313
+ MIT © IXO Team