@nesso-how/plugin 0.3.1 → 0.5.0

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.
package/README.md CHANGED
@@ -2,6 +2,16 @@
2
2
 
3
3
  Build Nesso plugins with TypeScript: **actions** read and edit graphs, **vocabularies** define relation types, and **themes** customize appearance.
4
4
 
5
+ ## Install
6
+
7
+ With Node.js and npm installed, add the SDK to your TypeScript project:
8
+
9
+ ```sh
10
+ npm install --save-dev @nesso-how/plugin
11
+ ```
12
+
13
+ This installs the development SDK, not a plugin in Nesso. If you are starting a new plugin, use the example below for TypeScript and bundler configuration, including React UI support. To install and try your built plugin in the desktop app, follow the [local testing instructions](example/README.md#test-an-unpublished-build).
14
+
5
15
  ## Create a plugin
6
16
 
7
17
  Copy the [standalone action example](example/) into a separate project. It includes the SDK, TypeScript configuration, and bundler setup:
@@ -15,14 +25,13 @@ Choose your own package name and action ID, then edit `src/index.ts`:
15
25
 
16
26
  ```ts
17
27
  import type { ActionContribution, NessoOperation } from '@nesso-how/plugin'
18
- import source from '../package.json' with { type: 'json' }
19
28
 
20
29
  export const create = (): readonly ActionContribution[] => {
21
30
  const action: ActionContribution = {
22
31
  id: 'uppercase-labels',
23
- label: source.i18n.metadata.name,
24
- run: async ({ store }) => {
25
- const state = store.getState()
32
+ label: { en: 'Uppercase labels' },
33
+ run: async ({ document }) => {
34
+ const state = document.getState()
26
35
 
27
36
  const operations: readonly NessoOperation[] = state.viewGraph.concepts.map(({ id, label }) => ({
28
37
  kind: 'concept.label',
@@ -30,7 +39,7 @@ export const create = (): readonly ActionContribution[] => {
30
39
  value: label.toUpperCase(),
31
40
  }))
32
41
 
33
- await store.applyOperations(operations)
42
+ await document.applyOperations(operations)
34
43
  },
35
44
  }
36
45
 
@@ -64,7 +73,7 @@ Keep the example's build configuration and set these fields in `package.json`:
64
73
  },
65
74
  "i18n": {
66
75
  "metadata": {
67
- "name": { "en": "Uppercase labels" },
76
+ "name": { "en": "Label tools" },
68
77
  "description": { "en": "Uppercase concept labels in a view." },
69
78
  "documentation": { "en": "Updates labels in one undoable batch." }
70
79
  }
@@ -72,29 +81,59 @@ Keep the example's build configuration and set these fields in `package.json`:
72
81
  }
73
82
  ```
74
83
 
75
- Declare the operations your action uses in `writes` and file/notification access in `capabilities`. All fields shown under `nesso` and `i18n.metadata` are required. Add the `nesso-plugin` keyword for discovery in Settings → Plugins.
84
+ Declare the operations your action uses in `writes`. The optional permissions listed in `capabilities` are `files`, `notifications`, `storage`, and `ui`. The first three authorize their APIs; `ui` authorizes interactive UI contributions. All fields shown under `nesso` and `i18n.metadata` are required. Add the `nesso-plugin` keyword for discovery in Settings → Plugins.
76
85
 
77
- Labels and metadata use `{ en: string, it?: string, 'zh-CN'?: string }`, with English required as the fallback.
86
+ `i18n.metadata.name` names the plugin in Settings. Each action defines its own `label` for menus, independently of the plugin name. Labels and metadata use `{ en: string, it?: string, 'zh-CN'?: string }`, with English required as the fallback.
78
87
 
79
88
  ### Build and test
80
89
 
81
90
  Run `npm run build`, then follow the example's [local testing instructions](example/README.md#test-an-unpublished-build).
82
91
 
83
- Actions must ship one self-contained browser ES module with dependencies bundled; the example's build handles this. Test and install external plugins in the desktop app.
92
+ Actions ship one browser ES module with dependencies bundled except React and React DOM, which Nesso supplies inside the sandbox. Keep `react`, `react/*`, `react-dom`, and `react-dom/*` external in your bundler; the example's build handles this. The runtime supports React 19. Test and install external plugins in the desktop app.
84
93
 
85
94
  ## Action API
86
95
 
87
- Nesso passes `{ store, files, notifications, signal, viewId }` to `run` as `ActionContext`.
96
+ Nesso passes `{ document, storage, files, notifications, signal, viewId }` to `run` as `ActionContext`. `document` exposes the shared graph, view membership, and transient selection; `storage` holds the plugin's private data for that document.
88
97
 
89
- `create()` receives no arguments and returns an array of actions with unique lowercase kebab-case IDs, localized labels, optional icons, and `run(context)` handlers. Use `ActionIconName` for supported icons.
98
+ `create()` receives no arguments and returns an array of actions with unique lowercase kebab-case IDs, localized labels, optional icons, and either a `run(context)` handler or a React component in `ui`. The two forms are mutually exclusive. Use `ActionIconName` for supported icons.
90
99
 
91
100
  Keep graph reads and effects inside `run`. **Await every write, file dialog, and notification** before returning; the action ends when `run` finishes. Use `signal` to detect cancellation.
92
101
 
102
+ ### Action UI
103
+
104
+ Declare the `ui` capability and set the action's `ui` property to a React component instead of a `run` handler. Nesso mounts it in an isolated central panel and unmounts it when the session ends.
105
+
106
+ ```tsx
107
+ import { useSyncExternalStore } from 'react'
108
+ import type { ActionContext, ActionContribution } from '@nesso-how/plugin'
109
+
110
+ function Browse({ document }: ActionContext) {
111
+ const state = useSyncExternalStore(document.subscribe, document.getState)
112
+ return <ul>{state.viewGraph.concepts.map(({ id, label }) => <li key={id}>{label}</li>)}</ul>
113
+ }
114
+
115
+ export const create = (): readonly ActionContribution[] => [
116
+ { id: 'browse', label: { en: 'Browse concepts' }, ui: Browse },
117
+ ]
118
+ ```
119
+
120
+ #### Context
121
+
122
+ Components receive `ActionContext` directly as props, with the same APIs and permissions as `run`. `viewId` and the supplied `viewGraph` refer to the invoked view. Subscribe with `useSyncExternalStore` when rendering snapshot data. Discovery runs `create()` in a Worker, so keep DOM access and effects inside components or `run`, not at module scope or in `create()`. The panel can access its own DOM, but not the host DOM, native bridge, network, or direct persistent storage; use the injected APIs for files and storage.
123
+
124
+ #### Styling
125
+
126
+ Nesso supplies React, the `@nesso-how/ui` component stylesheet, and theme CSS variables such as `var(--background)` and `var(--foreground)`. Import your own CSS normally; the [standalone example](example/) bundles and injects it. Bundle dependencies other than React/React DOM and inline assets; remote or separate assets are not supported. The host does not compile plugin Tailwind classes. Read `locale` from `document.getState()` for translated content. Label inputs and preserve Tab/Shift+Tab navigation.
127
+
128
+ #### Lifecycle
129
+
130
+ Use React effects to clean up subscriptions and resources. Panels have no action execution timeout, but initialization and API requests have deadlines. Uncaught errors or rejected promises fail the session; handle expected errors in your UI. Nesso provides the title, close control, and loading/failure screens. Closing or replacing a panel discards its React state: save progress through `storage` during use, not during cleanup, which is best effort.
131
+
93
132
  ### Read the invoked view
94
133
 
95
- - `store.getState()` returns the latest readonly local snapshot synchronously and makes it the basis for subsequent writes.
96
- - `await store.refresh()` fetches and reads a fresh snapshot. Use it after deferred work, such as a file dialog, before computing edits.
97
- - `store.subscribe(listener)` notifies you of snapshot changes and returns an unsubscribe function. Read the new state with `getState()`.
134
+ - `document.getState()` returns the latest readonly local snapshot synchronously and makes it the basis for subsequent writes.
135
+ - `await document.refresh()` fetches and reads a fresh snapshot. Use it after deferred work, such as a file dialog, before computing edits.
136
+ - `document.subscribe(listener)` notifies you of snapshot changes and returns an unsubscribe function. Read the new state with `getState()`.
98
137
 
99
138
  The graph snapshot provides:
100
139
 
@@ -107,7 +146,7 @@ Concept and relation-type IDs are absolute IRIs. Relations are `{ source, predic
107
146
 
108
147
  ### Write the graph
109
148
 
110
- Call helpers on `store` and declare their operation kinds in `nesso.writes`:
149
+ Call helpers on `document` and declare their operation kinds in `nesso.writes`:
111
150
 
112
151
  | Helper | Required `writes` entry |
113
152
  | --- | --- |
@@ -130,7 +169,7 @@ Call helpers on `store` and declare their operation kinds in `nesso.writes`:
130
169
 
131
170
  `addConcept` returns the new IRI. New concepts join the active saved view and link to the single selected concept, if any. These links and `connect` use the vocabulary's default relation type. `createRelationType` creates and assigns a type to the given relation.
132
171
 
133
- For related edits, use `store.applyOperations(operations)` as in the quickstart. The entire batch succeeds or changes nothing. Separate calls are separate transactions. Raw `concept.add` operations require an explicit new absolute IRI.
172
+ For related edits, use `document.applyOperations(operations)` as in the quickstart. The entire batch succeeds or changes nothing. Separate calls are separate transactions. Raw `concept.add` operations require an explicit new absolute IRI.
134
173
 
135
174
  Every write checks against the last snapshot you read, or the initial snapshot if you haven't read one. Successful writes advance that baseline, so awaited sequential writes work normally. Incoming updates alone do not advance it. A conflict rejects with `stale-state`; let the failure propagate so Nesso can ask the user to run the action again. Never retry mutations automatically or read a new snapshot just to submit edits calculated from old data.
136
175
 
@@ -140,14 +179,64 @@ The invoked view is **not a write sandbox**: permitted writes can affect the who
140
179
 
141
180
  | API | Required capability | Result |
142
181
  | --- | --- | --- |
143
- | `files.open({ extensions: ['json'], mimeTypes: ['application/json'] })` | `files.open` | `{ name, mediaType, text }`, or `null` on cancellation. Extensions omit the dot. |
144
- | `files.save({ name: 'graph.json', mediaType: 'application/json', text })` | `files.save` | `{ saved: boolean }`; cancellation returns `false`. |
145
- | `notifications.notify({ tone: 'info', title: { en: 'Done' }, description: { en: 'Labels updated' } })` | `notifications.notify` | A notification ID. Tone is `info` or `warning`; description is optional. |
182
+ | `files.open({ extensions: ['json'], mimeTypes: ['application/json'] })` | `files` | `{ name, mediaType, text }`, or `null` on cancellation. Extensions omit the dot. |
183
+ | `files.save({ name: 'graph.json', mediaType: 'application/json', text })` | `files` | `{ saved: boolean }`; cancellation returns `false`. |
184
+ | `notifications.notify({ tone: 'info', title: { en: 'Done' }, description: { en: 'Labels updated' } })` | `notifications` | A notification ID. Tone is `info` or `warning`; description is optional. |
146
185
 
147
- Files use UTF-8 text. Plugins have no Node, host DOM, direct filesystem, clipboard, or network access.
186
+ Files use UTF-8 text and host-managed dialogs or browser downloads; `files` grants no unrestricted filesystem access. Plugins have no Node, host DOM, direct filesystem, clipboard, or network access.
148
187
 
149
188
  Failures throw `PluginError` with `code` and `{ path, message }[]` issues. Let them propagate instead of reporting success. Files and notifications cannot be rolled back with graph edits.
150
189
 
190
+ ### Private persistent storage
191
+
192
+ Declare `storage` to read, write, or delete your plugin's private data. Nesso derives the namespace from the authorized npm package name and current document, never from plugin-provided identity fields. Different versions and action instances of the same package share data; different packages and documents do not.
193
+
194
+ ```ts
195
+ const records = await storage.list()
196
+
197
+ await storage.set('progress', { attempts: 1, answers: ['good'] }, concept.id)
198
+ await storage.set('settings', { enabled: true })
199
+ await storage.delete('progress', concept.id)
200
+ ```
201
+
202
+ `storage.list()` returns all records as an array. Each record has a `key`, a JSON `value`, and optionally a `conceptId`:
203
+
204
+ - Without `conceptId`, the record belongs to the document, for example plugin configuration.
205
+ - With `conceptId`, it belongs to that concept in the document. The same key can be used for different concepts and for document-level data.
206
+ - Views do not create storage namespaces. A concept's data is shared across all views containing it.
207
+ - Payloads belong to the plugin: the host does not interpret their fields or implement domain logic.
208
+
209
+ `storage.set(key, value, conceptId?)` saves one record and `storage.delete(key, conceptId?)` removes one. Each call is a single transaction returning `true` when storage changed and `false` for valid net-no-op writes, such as saving an identical value or deleting a missing record. Failed writes throw instead of returning `false`.
210
+
211
+ The SDK tracks storage revisions internally. Every mutation checks against the last listed snapshot or the preceding successful mutation. If you haven't listed storage, the first mutation reads its baseline automatically. Concurrent changes reject stale writes with `stale-state`, without refreshing the baseline or retrying automatically. List storage again before recomputing edits; never refresh just to resubmit edits calculated from old data. Document reads do not refresh the storage baseline, and storage writes do not invalidate the document snapshot. Document edits and private storage calls are separate transactions.
212
+
213
+ Await all storage calls before the action returns. Success means the validated change was committed in memory, not that a disk write has finished. Nesso autosaves through its shared persistence API, reports failures in its persistence banner, and waits for saving before desktop close, update installation, and data-folder transfers. Unreadable records are protected until explicit recovery; in-memory editing can continue but may remain unsaved.
214
+
215
+ #### Data lifecycle
216
+
217
+ - A document has a persistent identity outside graph JSON-LD. Resetting it creates a new identity and empty plugin storage; a mismatched saved identity is reported and protected, never silently attached to another document.
218
+ - Removing a view or changing membership does not delete concept data.
219
+ - Deleting a concept retains its records during the current app session so document Undo/Redo can recover it. Private storage changes themselves do not enter graph history.
220
+ - On startup, after the document and plugin storage restore successfully, Nesso removes records whose explicit `conceptId` is absent from the graph. Graph history does not survive restart. Cleanup is skipped after failed restoration and does not execute plugin code.
221
+ - Put data that should be cleaned with a concept, including its logs, inside concept-associated records. IDs embedded in arbitrary payloads are opaque and cannot be cleaned by the host.
222
+ - Disabling, uninstalling, replacing, or crashing a plugin does not delete its stored data. Startup reference cleanup still applies even when the plugin is absent.
223
+
224
+ #### Limits
225
+
226
+ Storage accepts finite JSON primitives, dense arrays, and plain objects, including `null`; not `undefined`, dates, maps, functions, cyclic data, or custom prototypes. Returned snapshots and stored payloads are independent copies.
227
+
228
+ | Budget | Limit |
229
+ | --- | --- |
230
+ | Record, encoded as UTF-8 JSON | 256 KiB |
231
+ | Namespace snapshot | 8 MiB |
232
+ | Total plugin storage per document | 64 MiB |
233
+ | Records per plugin | 10,000 |
234
+ | Plugin namespaces per document | 128 |
235
+ | Record nesting | 24 levels |
236
+ | Record key | 1–128 characters |
237
+
238
+ Concept IDs must be absolute IRIs and refer to an existing document concept when writing. Deletes may remove retained orphan records. Keys are logical identifiers, not paths. Normal action channel request, deadline, rate, and cancellation limits also apply.
239
+
151
240
  ## Vocabularies
152
241
 
153
242
  Set `nesso.kind` to `"vocab"`, `entry` to a package-local JSON file such as `"dist/definition.json"`, and both `writes` and `capabilities` to `[]`. Keep the same package metadata structure. The entry contains a `VocabDefinition`:
package/dist/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- import { A as NessoState, B as Viewport, C as createWriteCommands, E as LocalizedText, F as PanelSizes, H as WorkspaceState, I as Preferences, L as SavedView, M as Notification, N as NotificationAction, O as GraphSnapshot, P as Notifications, R as SectionId, V as VocabDefinition, W as ThemeDefinition, a as ActionState, c as actionIconNames, i as ActionIconName, j as NessoStore, k as NessoOperation, n as ActionContribution, o as PluginI18n, r as ActionDescriptor, s as PluginManifest, t as ActionContext, w as PluginError, z as Selection } from "./runtime-NJhqaq_J.js";
2
- export { type ActionContext, type ActionContribution, type ActionDescriptor, type ActionIconName, type ActionState, type GraphSnapshot, type LocalizedText, type NessoOperation, type NessoState, type NessoStore, type Notification, type NotificationAction, type Notifications, type PanelSizes, PluginError, type PluginI18n, type PluginManifest, type Preferences, type SavedView, type SectionId, type Selection, type ThemeDefinition, type Viewport, type VocabDefinition, type WorkspaceState, actionIconNames, createWriteCommands };
1
+ import { A as createWriteCommands, B as NotificationAction, F as GraphSnapshot, G as SectionId, H as PanelSizes, I as NessoOperation, J as VocabDefinition, K as Selection, L as NessoState, N as LocalizedText, R as NessoStore, U as Preferences, V as Notifications, W as SavedView, Y as WorkspaceState, Z as ThemeDefinition, a as ActionState, b as PluginStorageRecord, c as actionIconNames, i as ActionIconName, j as PluginError, n as ActionContribution, o as PluginI18n, q as Viewport, r as ActionDescriptor, s as PluginManifest, t as ActionContext, v as PluginStorage, y as PluginStorageKey, z as Notification } from "./runtime-D4jO7tbm.js";
2
+ export { type ActionContext, type ActionContribution, type ActionDescriptor, type ActionIconName, type ActionState, type GraphSnapshot, type LocalizedText, type NessoOperation, type NessoState, type NessoStore, type Notification, type NotificationAction, type Notifications, type PanelSizes, PluginError, type PluginI18n, type PluginManifest, type PluginStorage, type PluginStorageKey, type PluginStorageRecord, type Preferences, type SavedView, type SectionId, type Selection, type ThemeDefinition, type Viewport, type VocabDefinition, type WorkspaceState, actionIconNames, createWriteCommands };
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- export { _ as PluginError, t as actionIconNames, g as createWriteCommands } from "./runtime-Dl8Rcuy8.js";
1
+ export { x as PluginError, t as actionIconNames, b as createWriteCommands } from "./runtime-CJPU4o4h.js";
package/dist/package.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { o as PluginI18n, s as PluginManifest } from "./runtime-NJhqaq_J.js";
1
+ import { o as PluginI18n, s as PluginManifest } from "./runtime-D4jO7tbm.js";
2
2
  //#region src/package.d.ts
3
3
  export declare const packageLimits: {
4
4
  readonly entry: number;
package/dist/package.js CHANGED
@@ -1,4 +1,4 @@
1
- import { _ as PluginError, a as parsePluginI18n, l as sha256Hex, m as parseDefinition, n as checkMessageSize, o as parsePluginManifest, v as parseOrThrow } from "./runtime-Dl8Rcuy8.js";
1
+ import { S as parseOrThrow, a as parsePluginManifest, c as sha256Hex, i as parsePluginI18n, m as checkMessageSize, v as parseDefinition, x as PluginError } from "./runtime-CJPU4o4h.js";
2
2
  import { z } from "zod";
3
3
  import parseVersion from "semver/functions/parse.js";
4
4
  import validateName from "validate-npm-package-name";
@@ -402,6 +402,90 @@ const localizedText = (limit) => z.strictObject({
402
402
  });
403
403
  const resolvePluginText = (value, locale) => value[locale] ?? value.en;
404
404
  //#endregion
405
+ //#region src/data.ts
406
+ function checkMessageSize(value, limit, maximumDepth = 32) {
407
+ const visit = (value, depth) => {
408
+ if (depth > maximumDepth) throw new PluginError("invalid-input", [{
409
+ path: "message",
410
+ message: "Nesting limit exceeded"
411
+ }]);
412
+ if (value === null) return;
413
+ if (typeof value === "object") {
414
+ if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype) throw new PluginError("invalid-input", [{
415
+ path: "message",
416
+ message: "Expected plain data"
417
+ }]);
418
+ for (const item of Object.values(value)) visit(item, depth + 1);
419
+ } else if (![
420
+ "string",
421
+ "number",
422
+ "boolean",
423
+ "undefined"
424
+ ].includes(typeof value) || typeof value === "number" && !Number.isFinite(value)) throw new PluginError("invalid-input", [{
425
+ path: "message",
426
+ message: "Expected serializable data"
427
+ }]);
428
+ };
429
+ visit(value, 0);
430
+ if (new TextEncoder().encode(JSON.stringify(value)).byteLength > limit) throw new PluginError("invalid-input", [{
431
+ path: "message",
432
+ message: "Message limit exceeded"
433
+ }]);
434
+ }
435
+ //#endregion
436
+ //#region src/storage.ts
437
+ const pluginStorageLimits = {
438
+ record: 262144,
439
+ namespace: 8388608,
440
+ total: 67108864,
441
+ records: 1e4,
442
+ namespaces: 128,
443
+ depth: 24
444
+ };
445
+ const isJsonValue = (value, depth = 0) => {
446
+ if (depth > pluginStorageLimits.depth) return false;
447
+ if (value === null || typeof value === "string" || typeof value === "boolean") return true;
448
+ if (typeof value === "number") return Number.isFinite(value);
449
+ if (typeof value !== "object") return false;
450
+ if (Array.isArray(value)) return Reflect.ownKeys(value).length === value.length + 1 && Array.from(value).every((item) => isJsonValue(item, depth + 1));
451
+ return Object.getPrototypeOf(value) === Object.prototype && Reflect.ownKeys(value).length === Object.keys(value).length && Object.values(value).every((item) => isJsonValue(item, depth + 1));
452
+ };
453
+ const fields = {
454
+ key: z.string().min(1).max(128),
455
+ conceptId: z.string().max(2048).optional()
456
+ };
457
+ const pluginStorageKey = z.strictObject(fields);
458
+ const pluginStorageRecord = z.strictObject({
459
+ ...fields,
460
+ value: z.custom((value) => isJsonValue(value), "Expected a bounded JSON value").transform((value) => structuredClone(value))
461
+ }).superRefine((value, context) => {
462
+ try {
463
+ checkMessageSize(value, pluginStorageLimits.record, pluginStorageLimits.depth);
464
+ } catch (error) {
465
+ context.addIssue({
466
+ code: "custom",
467
+ message: error instanceof PluginError ? error.message : "Invalid storage record"
468
+ });
469
+ }
470
+ });
471
+ const pluginStorageRevision = z.number().int().nonnegative();
472
+ const pluginStorageSnapshot = z.strictObject({
473
+ revision: pluginStorageRevision,
474
+ records: z.array(pluginStorageRecord).max(pluginStorageLimits.records)
475
+ });
476
+ function parsePluginStorageSnapshot(value) {
477
+ checkMessageSize(value, pluginStorageLimits.namespace);
478
+ return parseOrThrow(pluginStorageSnapshot, value);
479
+ }
480
+ function parsePluginStorageRecord(value) {
481
+ checkMessageSize(value, pluginStorageLimits.record, pluginStorageLimits.depth);
482
+ return parseOrThrow(pluginStorageRecord, value);
483
+ }
484
+ function parsePluginStorageKey(value) {
485
+ checkMessageSize(value, 4096);
486
+ return parseOrThrow(pluginStorageKey, value);
487
+ }
488
+ //#endregion
405
489
  //#region src/runtime.ts
406
490
  const runtimeLimits = {
407
491
  request: 33554432,
@@ -410,7 +494,8 @@ const runtimeLimits = {
410
494
  deadline: 3e4,
411
495
  interaction: 3e5,
412
496
  initialization: 1e4,
413
- action: 12e4
497
+ action: 12e4,
498
+ heartbeat: 15e3
414
499
  };
415
500
  const themeTokens = [
416
501
  ...themeColors,
@@ -619,9 +704,10 @@ const manifest = z.discriminatedUnion("kind", [z.strictObject({
619
704
  entry: jsEntry,
620
705
  writes: operationDeclarations,
621
706
  capabilities: z.array(z.enum([
622
- "files.open",
623
- "files.save",
624
- "notifications.notify"
707
+ "files",
708
+ "notifications",
709
+ "storage",
710
+ "ui"
625
711
  ]))
626
712
  }), ...["theme", "vocab"].map((kind) => z.strictObject({
627
713
  ...manifestFields,
@@ -642,7 +728,7 @@ const envelope = {
642
728
  const request = z.discriminatedUnion("method", [
643
729
  z.strictObject({
644
730
  ...envelope,
645
- method: z.literal("store.applyOperations"),
731
+ method: z.literal("document.applyOperations"),
646
732
  params: z.strictObject({
647
733
  operations: z.array(operation).max(5e4),
648
734
  revision: z.number().int().nonnegative(),
@@ -651,9 +737,24 @@ const request = z.discriminatedUnion("method", [
651
737
  }),
652
738
  z.strictObject({
653
739
  ...envelope,
654
- method: z.literal("store.refresh"),
740
+ method: z.literal("document.refresh"),
655
741
  params: z.strictObject({})
656
742
  }),
743
+ z.strictObject({
744
+ ...envelope,
745
+ method: z.literal("storage.list"),
746
+ params: z.strictObject({})
747
+ }),
748
+ z.strictObject({
749
+ ...envelope,
750
+ method: z.literal("storage.set"),
751
+ params: pluginStorageRecord.extend({ revision: pluginStorageRevision })
752
+ }),
753
+ z.strictObject({
754
+ ...envelope,
755
+ method: z.literal("storage.delete"),
756
+ params: pluginStorageKey.extend({ revision: pluginStorageRevision })
757
+ }),
657
758
  z.strictObject({
658
759
  ...envelope,
659
760
  method: z.literal("notifications.notify"),
@@ -694,6 +795,11 @@ const wireError = z.strictObject({
694
795
  });
695
796
  const message = z.union([
696
797
  request,
798
+ z.strictObject({ type: z.literal("panel-ready") }),
799
+ z.strictObject({
800
+ type: z.literal("pong"),
801
+ id: z.number().int().positive()
802
+ }),
697
803
  z.strictObject({
698
804
  type: z.literal("contribution"),
699
805
  value: z.unknown()
@@ -715,7 +821,8 @@ const message = z.union([
715
821
  const actionDescriptor = z.strictObject({
716
822
  id: z.string().max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
717
823
  label: localizedText(128),
718
- icon: z.string().min(1).max(32).regex(/^[a-z]+(?:-[a-z]+)*$/).optional()
824
+ icon: z.string().min(1).max(32).regex(/^[a-z]+(?:-[a-z]+)*$/).optional(),
825
+ ui: z.literal(true).optional()
719
826
  });
720
827
  const actionIconNames = [
721
828
  "arrow-right",
@@ -790,6 +897,10 @@ const actionStateSchema = z.strictObject({
790
897
  })
791
898
  });
792
899
  const reply = z.union([
900
+ z.strictObject({
901
+ type: z.literal("ping"),
902
+ id: z.number().int().positive()
903
+ }),
793
904
  z.strictObject({
794
905
  type: z.literal("state"),
795
906
  state: actionStateSchema
@@ -812,11 +923,20 @@ const reply = z.union([
812
923
  })
813
924
  ]);
814
925
  const results = {
815
- "store.applyOperations": z.strictObject({
926
+ "document.applyOperations": z.strictObject({
816
927
  revision: z.number().int().nonnegative(),
817
928
  changed: z.boolean()
818
929
  }),
819
- "store.refresh": z.null(),
930
+ "document.refresh": z.null(),
931
+ "storage.list": pluginStorageSnapshot,
932
+ "storage.set": z.strictObject({
933
+ revision: pluginStorageRevision,
934
+ changed: z.boolean()
935
+ }),
936
+ "storage.delete": z.strictObject({
937
+ revision: pluginStorageRevision,
938
+ changed: z.boolean()
939
+ }),
820
940
  "notifications.notify": id,
821
941
  "files.open": fileOpenResult,
822
942
  "files.save": z.strictObject({ saved: z.boolean() })
@@ -829,38 +949,10 @@ async function sha256Hex(bytes) {
829
949
  const digest = await crypto.subtle.digest("SHA-256", new Uint8Array(bytes));
830
950
  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
831
951
  }
832
- function checkMessageSize(value, limit) {
833
- const visit = (value, depth) => {
834
- if (depth > 32) throw new PluginError("invalid-input", [{
835
- path: "message",
836
- message: "Nesting limit exceeded"
837
- }]);
838
- if (value === null) return;
839
- if (typeof value === "object") {
840
- if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype) throw new PluginError("invalid-input", [{
841
- path: "message",
842
- message: "Expected plain data"
843
- }]);
844
- for (const item of Object.values(value)) visit(item, depth + 1);
845
- } else if (![
846
- "string",
847
- "number",
848
- "boolean",
849
- "undefined"
850
- ].includes(typeof value)) throw new PluginError("invalid-input", [{
851
- path: "message",
852
- message: "Expected serializable data"
853
- }]);
854
- };
855
- visit(value, 0);
856
- if (new TextEncoder().encode(JSON.stringify(value)).byteLength > limit) throw new PluginError("invalid-input", [{
857
- path: "message",
858
- message: "Message limit exceeded"
859
- }]);
860
- }
861
952
  function createPluginClient(port, initial) {
862
953
  let state = parseOrThrow(actionStateSchema, initial);
863
954
  let readRevision = state.revision;
955
+ let storageRevision;
864
956
  let sequence = 0;
865
957
  const listeners = /* @__PURE__ */ new Set();
866
958
  const controller = new AbortController();
@@ -928,6 +1020,13 @@ function createPluginClient(port, initial) {
928
1020
  return;
929
1021
  }
930
1022
  const data = parsed.data;
1023
+ if (data.type === "ping") {
1024
+ port.postMessage({
1025
+ type: "pong",
1026
+ id: data.id
1027
+ });
1028
+ return;
1029
+ }
931
1030
  if (data.type === "close") {
932
1031
  close();
933
1032
  return;
@@ -962,7 +1061,7 @@ function createPluginClient(port, initial) {
962
1061
  return state;
963
1062
  };
964
1063
  const applyOperations = async (operations, options) => {
965
- const result = await call("store.applyOperations", {
1064
+ const result = await call("document.applyOperations", {
966
1065
  operations,
967
1066
  revision: readRevision,
968
1067
  ...options ? { options } : {}
@@ -976,10 +1075,24 @@ function createPluginClient(port, initial) {
976
1075
  await committed;
977
1076
  return id;
978
1077
  });
1078
+ const listStorage = async () => {
1079
+ const snapshot = await call("storage.list", {});
1080
+ storageRevision = Math.max(storageRevision ?? 0, snapshot.revision);
1081
+ return snapshot.records;
1082
+ };
1083
+ const mutateStorage = async (method, params) => {
1084
+ if (storageRevision === void 0) await listStorage();
1085
+ const result = await call(method, {
1086
+ ...params,
1087
+ revision: storageRevision
1088
+ });
1089
+ storageRevision = Math.max(storageRevision ?? 0, result.revision);
1090
+ return result.changed;
1091
+ };
979
1092
  return {
980
1093
  context: {
981
1094
  viewId: state.targetViewId,
982
- store: {
1095
+ document: {
983
1096
  ...writes,
984
1097
  getState,
985
1098
  subscribe: (listener) => {
@@ -987,7 +1100,7 @@ function createPluginClient(port, initial) {
987
1100
  return () => listeners.delete(listener);
988
1101
  },
989
1102
  refresh: async () => {
990
- await call("store.refresh", {});
1103
+ await call("document.refresh", {});
991
1104
  return getState();
992
1105
  },
993
1106
  applyOperations
@@ -997,10 +1110,29 @@ function createPluginClient(port, initial) {
997
1110
  open: (options) => call("files.open", options),
998
1111
  save: (options) => call("files.save", options)
999
1112
  },
1113
+ storage: {
1114
+ list: listStorage,
1115
+ set: (key, value, conceptId) => mutateStorage("storage.set", conceptId === void 0 ? {
1116
+ key,
1117
+ value
1118
+ } : {
1119
+ key,
1120
+ value,
1121
+ conceptId
1122
+ }),
1123
+ delete: (key, conceptId) => mutateStorage("storage.delete", conceptId === void 0 ? { key } : {
1124
+ key,
1125
+ conceptId
1126
+ })
1127
+ },
1000
1128
  signal: controller.signal
1001
1129
  },
1002
- close
1130
+ close,
1131
+ getPresentation: () => ({
1132
+ theme: state.theme,
1133
+ locale: state.locale
1134
+ })
1003
1135
  };
1004
1136
  }
1005
1137
  //#endregion
1006
- export { PluginError as _, parsePluginI18n as a, runtimeLimits as c, resolvePluginText as d, fileTextLimit as f, createWriteCommands as g, themeColors as h, parseContribution as i, sha256Hex as l, parseDefinition as m, checkMessageSize as n, parsePluginManifest as o, parseFileOptions as p, createPluginClient as r, parsePluginMessage as s, actionIconNames as t, themeTokens as u, parseOrThrow as v };
1138
+ export { parseOrThrow as S, parseFileOptions as _, parsePluginManifest as a, createWriteCommands as b, sha256Hex as c, parsePluginStorageRecord as d, parsePluginStorageSnapshot as f, fileTextLimit as g, resolvePluginText as h, parsePluginI18n as i, themeTokens as l, checkMessageSize as m, createPluginClient as n, parsePluginMessage as o, pluginStorageLimits as p, parseContribution as r, runtimeLimits as s, actionIconNames as t, parsePluginStorageKey as u, parseDefinition as v, PluginError as x, themeColors as y };
@@ -1,4 +1,5 @@
1
1
  import { ZodType, z } from "zod";
2
+ import { ComponentType } from "react";
2
3
  //#region ../errors/src/index.d.ts
3
4
  type ErrorIssue = {
4
5
  path: string;
@@ -376,6 +377,53 @@ type FileSaveOptions = z.infer<typeof fileSaveOptions>;
376
377
  type FileOpenResult = z.infer<typeof fileOpenResult>;
377
378
  declare function parseFileOptions<K extends 'open' | 'save'>(kind: K, value: unknown): K extends 'open' ? FileOpenOptions : FileSaveOptions;
378
379
  //#endregion
380
+ //#region src/storage.d.ts
381
+ declare const pluginStorageLimits: {
382
+ readonly record: number;
383
+ readonly namespace: number;
384
+ readonly total: number;
385
+ readonly records: 10000;
386
+ readonly namespaces: 128;
387
+ readonly depth: 24;
388
+ };
389
+ type JsonValue = null | string | number | boolean | readonly JsonValue[] | {
390
+ readonly [key: string]: JsonValue;
391
+ };
392
+ declare const pluginStorageKey: z.ZodObject<{
393
+ key: z.ZodString;
394
+ conceptId: z.ZodOptional<z.ZodString>;
395
+ }, z.core.$strict>;
396
+ declare const pluginStorageRecord: z.ZodObject<{
397
+ key: z.ZodString;
398
+ conceptId: z.ZodOptional<z.ZodString>;
399
+ value: z.ZodPipe<z.ZodCustom<JsonValue, JsonValue>, z.ZodTransform<string | number | boolean | readonly JsonValue[] | {
400
+ readonly [key: string]: JsonValue;
401
+ } | null, JsonValue>>;
402
+ }, z.core.$strict>;
403
+ declare const pluginStorageSnapshot: z.ZodObject<{
404
+ revision: z.ZodNumber;
405
+ records: z.ZodArray<z.ZodObject<{
406
+ key: z.ZodString;
407
+ conceptId: z.ZodOptional<z.ZodString>;
408
+ value: z.ZodPipe<z.ZodCustom<JsonValue, JsonValue>, z.ZodTransform<string | number | boolean | readonly JsonValue[] | {
409
+ readonly [key: string]: JsonValue;
410
+ } | null, JsonValue>>;
411
+ }, z.core.$strict>>;
412
+ }, z.core.$strict>;
413
+ type PluginStorageRecord = DeepReadonly<z.infer<typeof pluginStorageRecord>>;
414
+ type PluginStorageKey = DeepReadonly<z.infer<typeof pluginStorageKey>>;
415
+ type PluginStorage = {
416
+ readonly list: () => Promise<readonly PluginStorageRecord[]>;
417
+ readonly set: (key: string, value: PluginStorageRecord['value'], conceptId?: string) => Promise<boolean>;
418
+ readonly delete: (key: string, conceptId?: string) => Promise<boolean>;
419
+ };
420
+ declare function parsePluginStorageSnapshot(value: unknown): DeepReadonly<z.infer<typeof pluginStorageSnapshot>>;
421
+ declare function parsePluginStorageRecord(value: unknown): PluginStorageRecord;
422
+ declare function parsePluginStorageKey(value: unknown): PluginStorageKey;
423
+ //#endregion
424
+ //#region src/data.d.ts
425
+ declare function checkMessageSize(value: unknown, limit: number, maximumDepth?: number): void;
426
+ //#endregion
379
427
  //#region src/runtime.d.ts
380
428
  declare const runtimeLimits: {
381
429
  readonly request: number;
@@ -385,6 +433,7 @@ declare const runtimeLimits: {
385
433
  readonly interaction: 300000;
386
434
  readonly initialization: 10000;
387
435
  readonly action: 120000;
436
+ readonly heartbeat: 15000;
388
437
  };
389
438
  declare const themeTokens: readonly ["background", "foreground", "canvas", "sidebar", "primary", "primary-hover", "primary-foreground", "muted", "muted-foreground", "hover", "pressed", "border", "ring", "selection-halo", "node-border", "edge", "handle", "font-sans", "font-mono", "radius-control", "radius-object", "duration-state"];
390
439
  declare const metadata: z.ZodObject<{
@@ -432,9 +481,10 @@ declare const manifest: z.ZodDiscriminatedUnion<[z.ZodObject<{
432
481
  "view.membership": "view.membership";
433
482
  }>>;
434
483
  capabilities: z.ZodArray<z.ZodEnum<{
435
- "files.open": "files.open";
436
- "files.save": "files.save";
437
- "notifications.notify": "notifications.notify";
484
+ files: "files";
485
+ notifications: "notifications";
486
+ storage: "storage";
487
+ ui: "ui";
438
488
  }>>;
439
489
  }, z.core.$strict>, ...z.ZodObject<{
440
490
  apiVersion: z.ZodLiteral<1>;
@@ -449,7 +499,7 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
449
499
  type: z.ZodLiteral<"request">;
450
500
  id: z.ZodNumber;
451
501
  contextId: z.ZodString;
452
- method: z.ZodLiteral<"store.applyOperations">;
502
+ method: z.ZodLiteral<"document.applyOperations">;
453
503
  params: z.ZodObject<{
454
504
  operations: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
455
505
  kind: z.ZodLiteral<"concept.label">;
@@ -600,8 +650,131 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
600
650
  type: z.ZodLiteral<"request">;
601
651
  id: z.ZodNumber;
602
652
  contextId: z.ZodString;
603
- method: z.ZodLiteral<"store.refresh">;
653
+ method: z.ZodLiteral<"document.refresh">;
604
654
  params: z.ZodObject<{}, z.core.$strict>;
655
+ }, z.core.$strict>, z.ZodObject<{
656
+ type: z.ZodLiteral<"request">;
657
+ id: z.ZodNumber;
658
+ contextId: z.ZodString;
659
+ method: z.ZodLiteral<"storage.list">;
660
+ params: z.ZodObject<{}, z.core.$strict>;
661
+ }, z.core.$strict>, z.ZodObject<{
662
+ type: z.ZodLiteral<"request">;
663
+ id: z.ZodNumber;
664
+ contextId: z.ZodString;
665
+ method: z.ZodLiteral<"storage.set">;
666
+ params: z.ZodObject<{
667
+ key: z.ZodString;
668
+ conceptId: z.ZodOptional<z.ZodString>;
669
+ value: z.ZodPipe<z.ZodCustom<string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | /*elided*/ any | {
670
+ readonly [key: string]: string | number | boolean | /*elided*/ any | /*elided*/ any | null;
671
+ } | null)[] | {
672
+ readonly [key: string]: string | number | boolean | any | any | null;
673
+ } | null)[] | {
674
+ readonly [key: string]: string | number | boolean | any | any | null;
675
+ } | null)[] | {
676
+ readonly [key: string]: string | number | boolean | any | any | null;
677
+ } | null)[] | {
678
+ readonly [key: string]: string | number | boolean | any | any | null;
679
+ } | null)[] | {
680
+ readonly [key: string]: string | number | boolean | any | any | null;
681
+ } | null)[] | {
682
+ readonly [key: string]: string | number | boolean | any | any | null;
683
+ } | null)[] | {
684
+ readonly [key: string]: string | number | boolean | any | any | null;
685
+ } | null)[] | {
686
+ readonly [key: string]: string | number | boolean | any | any | null;
687
+ } | null)[] | {
688
+ readonly [key: string]: string | number | boolean | any | any | null;
689
+ } | null)[] | {
690
+ readonly [key: string]: string | number | boolean | any | any | null;
691
+ } | null)[] | {
692
+ readonly [key: string]: string | number | boolean | any | any | null;
693
+ } | null, string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | any | {
694
+ readonly [key: string]: string | number | boolean | any | any | null;
695
+ } | null)[] | {
696
+ readonly [key: string]: string | number | boolean | any | any | null;
697
+ } | null)[] | {
698
+ readonly [key: string]: string | number | boolean | any | any | null;
699
+ } | null)[] | {
700
+ readonly [key: string]: string | number | boolean | any | any | null;
701
+ } | null)[] | {
702
+ readonly [key: string]: string | number | boolean | any | any | null;
703
+ } | null)[] | {
704
+ readonly [key: string]: string | number | boolean | any | any | null;
705
+ } | null)[] | {
706
+ readonly [key: string]: string | number | boolean | any | any | null;
707
+ } | null)[] | {
708
+ readonly [key: string]: string | number | boolean | any | any | null;
709
+ } | null)[] | {
710
+ readonly [key: string]: string | number | boolean | any | any | null;
711
+ } | null)[] | {
712
+ readonly [key: string]: string | number | boolean | any | any | null;
713
+ } | null)[] | {
714
+ readonly [key: string]: string | number | boolean | any | any | null;
715
+ } | null)[] | {
716
+ readonly [key: string]: string | number | boolean | any | any | null;
717
+ } | null>, z.ZodTransform<string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | any | {
718
+ readonly [key: string]: string | number | boolean | any | any | null;
719
+ } | null)[] | {
720
+ readonly [key: string]: string | number | boolean | any | any | null;
721
+ } | null)[] | {
722
+ readonly [key: string]: string | number | boolean | any | any | null;
723
+ } | null)[] | {
724
+ readonly [key: string]: string | number | boolean | any | any | null;
725
+ } | null)[] | {
726
+ readonly [key: string]: string | number | boolean | any | any | null;
727
+ } | null)[] | {
728
+ readonly [key: string]: string | number | boolean | any | any | null;
729
+ } | null)[] | {
730
+ readonly [key: string]: string | number | boolean | any | any | null;
731
+ } | null)[] | {
732
+ readonly [key: string]: string | number | boolean | any | any | null;
733
+ } | null)[] | {
734
+ readonly [key: string]: string | number | boolean | any | any | null;
735
+ } | null)[] | {
736
+ readonly [key: string]: string | number | boolean | any | any | null;
737
+ } | null)[] | {
738
+ readonly [key: string]: string | number | boolean | any | any | null;
739
+ } | null)[] | {
740
+ readonly [key: string]: string | number | boolean | any | any | null;
741
+ } | null, string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | any | {
742
+ readonly [key: string]: string | number | boolean | any | any | null;
743
+ } | null)[] | {
744
+ readonly [key: string]: string | number | boolean | any | any | null;
745
+ } | null)[] | {
746
+ readonly [key: string]: string | number | boolean | any | any | null;
747
+ } | null)[] | {
748
+ readonly [key: string]: string | number | boolean | any | any | null;
749
+ } | null)[] | {
750
+ readonly [key: string]: string | number | boolean | any | any | null;
751
+ } | null)[] | {
752
+ readonly [key: string]: string | number | boolean | any | any | null;
753
+ } | null)[] | {
754
+ readonly [key: string]: string | number | boolean | any | any | null;
755
+ } | null)[] | {
756
+ readonly [key: string]: string | number | boolean | any | any | null;
757
+ } | null)[] | {
758
+ readonly [key: string]: string | number | boolean | any | any | null;
759
+ } | null)[] | {
760
+ readonly [key: string]: string | number | boolean | any | any | null;
761
+ } | null)[] | {
762
+ readonly [key: string]: string | number | boolean | any | any | null;
763
+ } | null)[] | {
764
+ readonly [key: string]: string | number | boolean | any | any | null;
765
+ } | null>>;
766
+ revision: z.ZodNumber;
767
+ }, z.core.$strict>;
768
+ }, z.core.$strict>, z.ZodObject<{
769
+ type: z.ZodLiteral<"request">;
770
+ id: z.ZodNumber;
771
+ contextId: z.ZodString;
772
+ method: z.ZodLiteral<"storage.delete">;
773
+ params: z.ZodObject<{
774
+ key: z.ZodString;
775
+ conceptId: z.ZodOptional<z.ZodString>;
776
+ revision: z.ZodNumber;
777
+ }, z.core.$strict>;
605
778
  }, z.core.$strict>, z.ZodObject<{
606
779
  type: z.ZodLiteral<"request">;
607
780
  id: z.ZodNumber;
@@ -643,6 +816,11 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
643
816
  text: z.ZodString;
644
817
  }, z.core.$strict>;
645
818
  }, z.core.$strict>], "method">, z.ZodObject<{
819
+ type: z.ZodLiteral<"panel-ready">;
820
+ }, z.core.$strict>, z.ZodObject<{
821
+ type: z.ZodLiteral<"pong">;
822
+ id: z.ZodNumber;
823
+ }, z.core.$strict>, z.ZodObject<{
646
824
  type: z.ZodLiteral<"contribution">;
647
825
  value: z.ZodUnknown;
648
826
  }, z.core.$strict>, z.ZodObject<{
@@ -685,13 +863,18 @@ declare const actionDescriptor: z.ZodObject<{
685
863
  'zh-CN': z.ZodOptional<z.ZodString>;
686
864
  }, z.core.$strict>;
687
865
  icon: z.ZodOptional<z.ZodString>;
866
+ ui: z.ZodOptional<z.ZodLiteral<true>>;
688
867
  }, z.core.$strict>;
689
868
  declare const actionIconNames: readonly ['arrow-right', 'book-open', 'clipboard-paste', 'copy', 'download', 'file-down', 'file-up', 'folder', 'globe', 'layers', 'pencil', 'play', 'plus', 'refresh', 'scissors', 'search', 'share', 'sparkles', 'upload', 'zap'];
690
869
  type ActionIconName = typeof actionIconNames[number];
691
870
  type ActionDescriptor = DeepReadonly<z.infer<typeof actionDescriptor>>;
692
- type ActionContribution = ActionDescriptor & {
871
+ type ActionContribution = Omit<ActionDescriptor, 'ui'> & ({
872
+ readonly ui: ComponentType<ActionContext>;
873
+ readonly run?: never;
874
+ } | {
875
+ readonly ui?: never;
693
876
  readonly run: (context: ActionContext) => void | Promise<void>;
694
- };
877
+ });
695
878
  declare function parseContribution(kind: 'theme' | 'vocab', value: unknown): Definition;
696
879
  declare function parseContribution(kind: 'actions', value: unknown): readonly ActionDescriptor[];
697
880
  type ActionState = {
@@ -722,7 +905,7 @@ type WriteOptions = {
722
905
  type PluginWrites = Omit<ReturnType<typeof createWriteCommands<Promise<void>, Promise<string>>>, 'undo' | 'redo' | 'setView' | 'setActiveVocab' | 'setActiveTheme' | 'setLocale' | 'setPanelSizes' | 'setSectionOpen' | 'createView' | 'renameView' | 'setViewPinned' | 'deleteView'>;
723
906
  type ActionContext = {
724
907
  readonly viewId: string | null;
725
- readonly store: PluginWrites & {
908
+ readonly document: PluginWrites & {
726
909
  readonly getState: () => ActionState;
727
910
  readonly subscribe: (listener: () => void) => () => void;
728
911
  readonly refresh: () => Promise<ActionState>;
@@ -744,14 +927,15 @@ type ActionContext = {
744
927
  readonly saved: boolean;
745
928
  }>;
746
929
  };
930
+ readonly storage: PluginStorage;
747
931
  readonly signal: AbortSignal;
748
932
  };
749
933
  declare function parsePluginMessage(value: unknown): z.infer<typeof message>;
750
934
  declare function sha256Hex(bytes: Uint8Array): Promise<string>;
751
- declare function checkMessageSize(value: unknown, limit: number): void;
752
935
  declare function createPluginClient(port: MessagePort, initial: unknown): {
753
936
  context: ActionContext;
754
937
  close: () => void;
938
+ getPresentation: () => Pick<ActionState, 'theme' | 'locale'>;
755
939
  };
756
940
  //#endregion
757
- export { NessoState as A, Viewport as B, createWriteCommands as C, resolvePluginText as D, LocalizedText as E, PanelSizes as F, parseDefinition as G, WorkspaceState as H, Preferences as I, themeColors as K, SavedView as L, Notification as M, NotificationAction as N, GraphSnapshot as O, Notifications as P, SectionId as R, parseFileOptions as S, parseOrThrow as T, Definition as U, VocabDefinition as V, ThemeDefinition as W, themeTokens as _, ActionState as a, FileSaveOptions as b, actionIconNames as c, parseContribution as d, parsePluginI18n as f, sha256Hex as g, runtimeLimits as h, ActionIconName as i, NessoStore as j, NessoOperation as k, checkMessageSize as l, parsePluginMessage as m, ActionContribution as n, PluginI18n as o, parsePluginManifest as p, ActionDescriptor as r, PluginManifest as s, ActionContext as t, createPluginClient as u, FileOpenOptions as v, PluginError as w, fileTextLimit as x, FileOpenResult as y, Selection as z };
941
+ export { themeColors as $, createWriteCommands as A, NotificationAction as B, parsePluginStorageSnapshot as C, FileSaveOptions as D, FileOpenResult as E, GraphSnapshot as F, SectionId as G, PanelSizes as H, NessoOperation as I, VocabDefinition as J, Selection as K, NessoState as L, parseOrThrow as M, LocalizedText as N, fileTextLimit as O, resolvePluginText as P, parseDefinition as Q, NessoStore as R, parsePluginStorageRecord as S, FileOpenOptions as T, Preferences as U, Notifications as V, SavedView as W, Definition as X, WorkspaceState as Y, ThemeDefinition as Z, checkMessageSize as _, ActionState as a, PluginStorageRecord as b, actionIconNames as c, parsePluginI18n as d, parsePluginManifest as f, themeTokens as g, sha256Hex as h, ActionIconName as i, PluginError as j, parseFileOptions as k, createPluginClient as l, runtimeLimits as m, ActionContribution as n, PluginI18n as o, parsePluginMessage as p, Viewport as q, ActionDescriptor as r, PluginManifest as s, ActionContext as t, parseContribution as u, PluginStorage as v, pluginStorageLimits as w, parsePluginStorageKey as x, PluginStorageKey as y, Notification as z };
package/dist/runtime.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- import { D as resolvePluginText, E as LocalizedText, G as parseDefinition, K as themeColors, S as parseFileOptions, T as parseOrThrow, U as Definition, _ as themeTokens, a as ActionState, b as FileSaveOptions, c as actionIconNames, d as parseContribution, f as parsePluginI18n, g as sha256Hex, h as runtimeLimits, i as ActionIconName, l as checkMessageSize, m as parsePluginMessage, n as ActionContribution, o as PluginI18n, p as parsePluginManifest, r as ActionDescriptor, s as PluginManifest, t as ActionContext, u as createPluginClient, v as FileOpenOptions, w as PluginError, x as fileTextLimit, y as FileOpenResult } from "./runtime-NJhqaq_J.js";
2
- export { ActionContext, ActionContribution, ActionDescriptor, ActionIconName, ActionState, type Definition, type FileOpenOptions, type FileOpenResult, type FileSaveOptions, type LocalizedText, PluginError, PluginI18n, PluginManifest, actionIconNames, checkMessageSize, createPluginClient, fileTextLimit, parseContribution, parseDefinition, parseFileOptions, parseOrThrow, parsePluginI18n, parsePluginManifest, parsePluginMessage, resolvePluginText, runtimeLimits, sha256Hex, themeColors, themeTokens };
1
+ import { $ as themeColors, C as parsePluginStorageSnapshot, D as FileSaveOptions, E as FileOpenResult, M as parseOrThrow, N as LocalizedText, O as fileTextLimit, P as resolvePluginText, Q as parseDefinition, S as parsePluginStorageRecord, T as FileOpenOptions, X as Definition, _ as checkMessageSize, a as ActionState, c as actionIconNames, d as parsePluginI18n, f as parsePluginManifest, g as themeTokens, h as sha256Hex, i as ActionIconName, j as PluginError, k as parseFileOptions, l as createPluginClient, m as runtimeLimits, n as ActionContribution, o as PluginI18n, p as parsePluginMessage, r as ActionDescriptor, s as PluginManifest, t as ActionContext, u as parseContribution, w as pluginStorageLimits, x as parsePluginStorageKey } from "./runtime-D4jO7tbm.js";
2
+ export { ActionContext, ActionContribution, ActionDescriptor, ActionIconName, ActionState, type Definition, type FileOpenOptions, type FileOpenResult, type FileSaveOptions, type LocalizedText, PluginError, PluginI18n, PluginManifest, actionIconNames, checkMessageSize, createPluginClient, fileTextLimit, parseContribution, parseDefinition, parseFileOptions, parseOrThrow, parsePluginI18n, parsePluginManifest, parsePluginMessage, parsePluginStorageKey, parsePluginStorageRecord, parsePluginStorageSnapshot, pluginStorageLimits, resolvePluginText, runtimeLimits, sha256Hex, themeColors, themeTokens };
package/dist/runtime.js CHANGED
@@ -1 +1 @@
1
- export { _ as PluginError, t as actionIconNames, n as checkMessageSize, r as createPluginClient, f as fileTextLimit, i as parseContribution, m as parseDefinition, p as parseFileOptions, v as parseOrThrow, a as parsePluginI18n, o as parsePluginManifest, s as parsePluginMessage, d as resolvePluginText, c as runtimeLimits, l as sha256Hex, h as themeColors, u as themeTokens } from "./runtime-Dl8Rcuy8.js";
1
+ export { x as PluginError, t as actionIconNames, m as checkMessageSize, n as createPluginClient, g as fileTextLimit, r as parseContribution, v as parseDefinition, _ as parseFileOptions, S as parseOrThrow, i as parsePluginI18n, a as parsePluginManifest, o as parsePluginMessage, u as parsePluginStorageKey, d as parsePluginStorageRecord, f as parsePluginStorageSnapshot, p as pluginStorageLimits, h as resolvePluginText, s as runtimeLimits, c as sha256Hex, y as themeColors, l as themeTokens } from "./runtime-CJPU4o4h.js";
package/example/README.md CHANGED
@@ -1,12 +1,12 @@
1
- # Uppercase labels
1
+ # Plugin Example
2
2
 
3
- The official Nesso action plugin example, published as [`@nesso-how/plugin-example`](https://www.npmjs.com/package/@nesso-how/plugin-example). It uppercases labels in the invoked view with one undoable batch. Shared concepts change in every view containing them.
3
+ The official Nesso plugin example: an **Uppercase labels** action and a React **Concept Quiz** with persistent progress. See [`src/index.ts`](src/index.ts) and [`src/Quiz.tsx`](src/Quiz.tsx).
4
4
 
5
5
  ## Install and try
6
6
 
7
- In the desktop app, open Settings → Plugins, search for `@nesso-how/plugin-example`, and install it. Approve its declared access to concept labels.
7
+ In the desktop app, open Settings → Plugins, search for `@nesso-how/plugin-example`, and install it. Approve its declared access to concept labels, interactive panels, and private storage. The panel example requires the SDK and app versions containing central-panel support; build from this checkout until that SDK release is published.
8
8
 
9
- Run **Uppercase labels** from a view's context menu in the Explorer, or from the view's actions in the Inspector with no concepts or relations selected. Use Undo to restore the original labels.
9
+ Run either action from a view's context menu in the Explorer, or from its actions in the Inspector with nothing selected.
10
10
 
11
11
  ## Build your own
12
12
 
@@ -17,9 +17,9 @@ npm install
17
17
  npm run build
18
18
  ```
19
19
 
20
- The build typechecks `src/index.ts` and bundles it with the package metadata into a self-contained `dist/index.js`.
20
+ The Vite configuration bundles code and imported CSS into `dist/index.js`, leaving React and React DOM to Nesso. See the [UI contract](../README.md#action-ui) for runtime requirements.
21
21
 
22
- Choose your own package name and action ID before publishing a derived plugin.
22
+ Choose your own package name, plugin metadata, and action IDs and labels before publishing.
23
23
 
24
24
  ## Test an unpublished build
25
25
 
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@nesso-how/plugin-example",
3
- "version": "0.3.1",
4
- "description": "Uppercase concept labels in the invoked Nesso view",
3
+ "version": "0.5.0",
4
+ "description": "Official example showing how to build Nesso plugins with the SDK and plugin APIs",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",
@@ -10,33 +10,41 @@
10
10
  },
11
11
  "type": "module",
12
12
  "keywords": ["nesso-plugin"],
13
- "files": ["dist", "src", "tsconfig.json"],
13
+ "files": ["dist", "src", "tsconfig.json", "vite.config.ts"],
14
14
  "scripts": {
15
15
  "check": "tsc",
16
- "build": "npm run check && esbuild src/index.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/index.js",
16
+ "build": "npm run check && vite build",
17
17
  "prepack": "npm run build"
18
18
  },
19
19
  "publishConfig": {
20
20
  "access": "public",
21
21
  "registry": "https://registry.npmjs.org/"
22
22
  },
23
+ "dependencies": {
24
+ "@nesso-how/ui": "1.0.0-alpha.31",
25
+ "react": "^19.2.8",
26
+ "react-dom": "^19.2.8"
27
+ },
23
28
  "devDependencies": {
24
- "@nesso-how/plugin": "0.3.1",
25
- "esbuild": "^0.28.2",
26
- "typescript": "~7.0.2"
29
+ "@nesso-how/plugin": "0.5.0",
30
+ "@types/react": "^19.2.18",
31
+ "@types/react-dom": "^19.2.7",
32
+ "typescript": "~7.0.2",
33
+ "vite": "^8.3.0",
34
+ "vite-plugin-css-injected-by-js": "^5.0.3"
27
35
  },
28
36
  "nesso": {
29
37
  "apiVersion": 1,
30
38
  "kind": "actions",
31
39
  "entry": "dist/index.js",
32
40
  "writes": ["concept.label"],
33
- "capabilities": []
41
+ "capabilities": ["ui", "storage"]
34
42
  },
35
43
  "i18n": {
36
44
  "metadata": {
37
- "name": { "en": "Uppercase labels" },
38
- "description": { "en": "Uppercase concept labels in the invoked view." },
39
- "documentation": { "en": "Changes the labels of concepts in the invoked view in one undoable transaction. Concepts shared with other views change there too." }
45
+ "name": { "en": "Plugin Example" },
46
+ "description": { "en": "Learn how to build Nesso plugins with the SDK and plugin APIs." },
47
+ "documentation": { "en": "A reference plugin for developers, with practical examples of using Nesso's SDK and plugin APIs to define actions, interact with graph data, and build custom interfaces." }
40
48
  }
41
49
  }
42
50
  }
@@ -0,0 +1,8 @@
1
+ .quiz { display: grid; min-height: 100dvh; place-items: center; padding: 24px; color: var(--foreground); font: 13px/1.5 var(--font-sans), system-ui, sans-serif; }
2
+ .quiz-card { width: 100%; max-width: 560px; overflow-wrap: anywhere; text-align: center; }
3
+ .quiz h1 { margin: 0 0 4px; font-size: 20px; font-weight: 500; }
4
+ .quiz [data-step] { margin: 0 0 16px; color: var(--muted-foreground); }
5
+ .quiz [data-question] { margin: 0; color: var(--muted-foreground); }
6
+ .quiz [data-answer] { min-height: 1.5em; margin: 16px 0; font-size: 18px; }
7
+ .quiz [data-result] { width: fit-content; margin: 8px auto 24px; padding: 16px 24px; border: 1px solid var(--border); border-radius: 12px; background: var(--muted); font-size: 18px; font-weight: 500; }
8
+ .quiz footer { display: flex; justify-content: center; gap: 8px; }
@@ -0,0 +1,49 @@
1
+ import { useEffect, useState } from 'react'
2
+ import { Button } from '@nesso-how/ui'
3
+ import type { ActionContext } from '@nesso-how/plugin'
4
+ import './Quiz.css'
5
+
6
+ export function Quiz({ document, storage, viewId }: ActionContext) {
7
+ const [step, setStep] = useState<number | null>(null)
8
+ const [revealed, setRevealed] = useState(false)
9
+ const key = `quiz:${viewId ?? 'all'}`
10
+
11
+ useEffect(() => {
12
+ void storage.list().then((records) => {
13
+ const value = records.find((record) => record.key === key && record.conceptId === undefined)?.value
14
+ setStep(typeof value === 'number' ? value : 0)
15
+ })
16
+ }, [storage, key])
17
+
18
+ async function saveStep(next: number) {
19
+ setStep(null)
20
+ await storage.set(key, next)
21
+ setRevealed(false)
22
+ setStep(next)
23
+ }
24
+
25
+ if (step === null) return null
26
+
27
+ const { concepts, relations, relationTypes } = document.getState().viewGraph
28
+ const relation = relations[step]
29
+ const relationType = relationTypes.find(({ id }) => id === relation?.predicate)
30
+ const conceptLabel = (id: string) => concepts.find((item) => item.id === id)?.label || id
31
+ const buttonLabel = !relation ? 'Completed' : revealed ? 'Next' : 'Show concept'
32
+
33
+ return (
34
+ <section className="quiz">
35
+ <div className="quiz-card">
36
+ <h1>Concept Quiz</h1>
37
+ <p data-step>Step {Math.min(step + 1, relations.length)} / {relations.length}</p>
38
+ {relation ? <>
39
+ <p data-question>{conceptLabel(relation.source)} — {relationType?.label || relation.predicate} → ?</p>
40
+ <p data-answer role="status">{revealed ? conceptLabel(relation.target) : ''}</p>
41
+ </> : <p data-result role="status">{relations.length ? 'Quiz complete!' : 'This view has no relations.'}</p>}
42
+ <footer>
43
+ <Button variant="outline" onClick={() => void saveStep(0)}>Reset</Button>
44
+ <Button disabled={!relation} onClick={() => revealed ? void saveStep(step + 1) : setRevealed(true)}>{buttonLabel}</Button>
45
+ </footer>
46
+ </div>
47
+ </section>
48
+ )
49
+ }
@@ -1,12 +1,12 @@
1
1
  import type { ActionContribution, NessoOperation } from '@nesso-how/plugin'
2
- import source from '../package.json' with { type: 'json' }
2
+ import { Quiz } from './Quiz.js'
3
3
 
4
4
  export const create = (): readonly ActionContribution[] => {
5
- const action: ActionContribution = {
5
+ const uppercase: ActionContribution = {
6
6
  id: 'uppercase-labels',
7
- label: source.i18n.metadata.name,
8
- run: async ({ store }) => {
9
- const state = store.getState()
7
+ label: { en: 'Uppercase labels' },
8
+ run: async ({ document }) => {
9
+ const state = document.getState()
10
10
 
11
11
  const operations: readonly NessoOperation[] = state.viewGraph.concepts.map(({ id, label }) => ({
12
12
  kind: 'concept.label',
@@ -14,9 +14,16 @@ export const create = (): readonly ActionContribution[] => {
14
14
  value: label.toUpperCase(),
15
15
  }))
16
16
 
17
- await store.applyOperations(operations)
17
+ await document.applyOperations(operations)
18
18
  },
19
19
  }
20
20
 
21
- return [action]
21
+ const quiz: ActionContribution = {
22
+ id: 'concept-quiz',
23
+ label: { en: 'Concept Quiz' },
24
+ ui: Quiz,
25
+ icon: 'play',
26
+ }
27
+
28
+ return [uppercase, quiz]
22
29
  }
@@ -1,14 +1,16 @@
1
1
  {
2
2
  "compilerOptions": {
3
3
  "target": "ES2022",
4
- "lib": ["ES2022", "WebWorker"],
5
- "module": "NodeNext",
6
- "moduleResolution": "NodeNext",
4
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
5
+ "module": "ESNext",
6
+ "moduleResolution": "Bundler",
7
+ "jsx": "react-jsx",
7
8
  "resolveJsonModule": true,
9
+ "allowImportingTsExtensions": true,
8
10
  "strict": true,
9
11
  "verbatimModuleSyntax": true,
10
12
  "noEmit": true,
11
- "types": []
13
+ "types": ["vite/client"]
12
14
  },
13
15
  "include": ["src"]
14
16
  }
@@ -0,0 +1,14 @@
1
+ import { defineConfig } from 'vite'
2
+ import cssInjectedByJs from 'vite-plugin-css-injected-by-js'
3
+
4
+ export default defineConfig({
5
+ root: import.meta.dirname,
6
+ publicDir: false,
7
+ plugins: [cssInjectedByJs()],
8
+ define: { 'process.env.NODE_ENV': '"production"' },
9
+ build: {
10
+ target: 'es2022',
11
+ lib: { entry: 'src/index.ts', formats: ['es'], fileName: () => 'index.js' },
12
+ rolldownOptions: { external: /^react(?:-dom)?(?:\/|$)/ },
13
+ },
14
+ })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nesso-how/plugin",
3
- "version": "0.3.1",
3
+ "version": "0.5.0",
4
4
  "description": "Types, validation, and asynchronous clients for isolated Nesso plugins",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -32,6 +32,7 @@
32
32
  "access": "public"
33
33
  },
34
34
  "dependencies": {
35
+ "@types/react": "^19.3.0",
35
36
  "semver": "^7.8.5",
36
37
  "validate-npm-package-name": "^8.0.0",
37
38
  "zod": "^4.6.5"
@@ -40,8 +41,12 @@
40
41
  "@nesso-how/errors": "0.0.0",
41
42
  "@nesso-how/i18n": "0.0.0",
42
43
  "@nesso-how/schema": "0.0.0",
44
+ "@types/react-dom": "^19.3.0",
43
45
  "@types/semver": "^7.8.0",
44
46
  "@types/validate-npm-package-name": "^4.0.2",
47
+ "es-module-lexer": "^3.0.4",
48
+ "react": "^19.3.0",
49
+ "react-dom": "^19.3.0",
45
50
  "tsdown": "^0.23.1"
46
51
  },
47
52
  "scripts": {