@nesso-how/plugin 0.6.0 → 0.7.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
@@ -67,7 +67,7 @@ Keep the example's build configuration and set these fields in `package.json`:
67
67
  "version": "1.0.0",
68
68
  "keywords": ["nesso-plugin"],
69
69
  "nesso": {
70
- "apiVersion": 1,
70
+ "apiVersion": 2,
71
71
  "kind": "actions",
72
72
  "entry": "dist/index.js",
73
73
  "writes": ["concept.label"],
@@ -85,6 +85,8 @@ Keep the example's build configuration and set these fields in `package.json`:
85
85
 
86
86
  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.
87
87
 
88
+ API version, npm SDK version, host storage envelope version, and private payload versions remain independent: bump only what your change affects.
89
+
88
90
  `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.
89
91
 
90
92
  ### Build and test
@@ -135,7 +137,7 @@ Nesso supplies React, the `@nesso-how/ui` component stylesheet, and theme CSS va
135
137
 
136
138
  #### Lifecycle
137
139
 
138
- 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. Changing the active view revokes the current panel instance and mounts the same action in a new instance for the selected view, including All. Closing or replacing a panel discards its React state: save progress through `storage` during use, not during cleanup, which is best effort.
140
+ 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. Changing the active view revokes the current channel and context and mounts a fresh React instance for the selected view, including All, while reusing the sandbox and loaded modules. Closing or replacing a panel discards its React state: save progress through `storage` during use, not during cleanup, which is best effort.
139
141
 
140
142
  ### Action badges
141
143
 
@@ -193,21 +195,25 @@ Call helpers on `document` and declare their operation kinds in `nesso.writes`:
193
195
 
194
196
  `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.
195
197
 
196
- 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.
198
+ For related edits, use `document.applyOperations(operations)` as in the quickstart. The entire batch succeeds or changes nothing. Editing, reconnecting, retyping, or removing an unknown concept or relation rejects the batch, as does reconnecting or retyping onto an existing relation; removing an item already removed earlier in the same batch, such as a relation of a removed concept, is allowed. Separate calls are separate transactions. Raw `concept.add` operations require an explicit new absolute IRI.
197
199
 
198
200
  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.
199
201
 
200
202
  The invoked view is **not a write sandbox**: permitted writes can affect the whole document. Only the operations listed above are available to plugins.
201
203
 
202
- ### Files, notifications, and failures
204
+ ### Files, images, notifications, and failures
203
205
 
204
206
  | API | Required capability | Result |
205
207
  | ------------------------------------------------------------------------------------------------------ | ------------------- | -------------------------------------------------------------------------------- |
206
208
  | `files.open({ extensions: ['json'], mimeTypes: ['application/json'] })` | `files` | `{ name, mediaType, text }`, or `null` on cancellation. Extensions omit the dot. |
207
209
  | `files.save({ name: 'graph.json', mediaType: 'application/json', text })` | `files` | `{ saved: boolean }`; cancellation returns `false`. |
210
+ | `files.save({ name: 'graph.png', mediaType: 'image/png', base64 })` | `files` | `{ saved: boolean }`; the host decodes canonical base64 before saving. |
211
+ | `images.renderView({ format: 'png', scale: 2 })` | `images` | `{ mediaType: 'image/png', base64 }` for the invoked view. |
208
212
  | `notifications.notify({ tone: 'info', title: { en: 'Done' }, description: { en: 'Labels updated' } })` | `notifications` | A notification ID. Tone is `info` or `warning`; description is optional. |
209
213
 
210
- 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.
214
+ File saves accept exactly one of UTF-8 `text` or canonical `base64` (without a data URL prefix), with a 16 MiB decoded byte limit. File opening remains UTF-8 text only. Host-managed dialogs or browser downloads grant no unrestricted filesystem access. Plugins have no Node, host DOM, direct filesystem, clipboard, or network access.
215
+
216
+ `images.renderView` captures the invoked view with the current theme and fonts, without selection or canvas controls. Scale defaults to `2`, or accepts `4`. Empty or oversized images fail rather than silently downscaling (8192 pixels per side, 16,777,216 pixels total, 16 MiB PNG). Save the result separately with `files.save({ name: 'view.png', ...image })`; this also requires `files`.
211
217
 
212
218
  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.
213
219
 
@@ -218,19 +224,26 @@ Declare `storage` to read, write, or delete your plugin's private data. Nesso de
218
224
  ```ts
219
225
  const records = await storage.list()
220
226
 
221
- await storage.set('progress', { attempts: 1, answers: ['good'] }, concept.id)
227
+ await storage.set(
228
+ 'progress',
229
+ { attempts: 1, answers: ['good'] },
230
+ { kind: 'concept', id: concept.id },
231
+ )
222
232
  await storage.set('settings', { enabled: true })
223
- await storage.delete('progress', concept.id)
233
+ if (viewId !== null)
234
+ await storage.set('notes', { text: 'Project ideas' }, { kind: 'view', id: viewId })
235
+ await storage.delete('progress', { kind: 'concept', id: concept.id })
224
236
  ```
225
237
 
226
- `storage.list()` returns all records as an array. Each record has a `key`, a JSON `value`, and optionally a `conceptId`:
238
+ `storage.list()` returns all records as an array, including records associated with deleted concepts or views. Each record has a `key`, a JSON `value`, and an optional `scope`:
227
239
 
228
- - Without `conceptId`, the record belongs to the document, for example plugin configuration.
229
- - With `conceptId`, it belongs to that concept in the document. The same key can be used for different concepts and for document-level data.
230
- - Views do not create storage namespaces. A concept's data is shared across all views containing it.
240
+ - Without `scope`, the record belongs to the document, for example plugin configuration or notes for Overview (`viewId === null`).
241
+ - With `{ kind: 'concept', id }`, it belongs to that concept. Its data is shared across all views containing the concept.
242
+ - With `{ kind: 'view', id }`, it belongs to that saved view, independently of its name or membership. Use a non-null `viewId`.
243
+ - Scopes identify records within the same plugin/document namespace; they do not create separate namespaces or revision baselines. The same key can be used at document scope and for different concepts and views, including a concept and view with the same ID.
231
244
  - Payloads belong to the plugin: the host does not interpret their fields or implement domain logic.
232
245
 
233
- `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`.
246
+ `storage.set(key, value, scope?)` saves one record and `storage.delete(key, scope?)` removes one. Set requires the referenced concept or saved view to exist. Concept IDs must be absolute IRIs; view IDs are opaque identifiers. Delete also accepts references to deleted entities so plugins can explicitly remove orphan records. 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`.
234
247
 
235
248
  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.
236
249
 
@@ -239,9 +252,9 @@ Await all storage calls before the action returns. Success means the validated c
239
252
  #### Data lifecycle
240
253
 
241
254
  - 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.
242
- - Removing a view or changing membership does not delete concept data.
243
- - Deleting a concept retains its records, including across restart and backup restoration. Document Undo/Redo can recover the concept during the current app session; private storage changes themselves do not enter graph history.
244
- - Use concept-associated records to identify a concept's data, including its logs. Plugins may explicitly delete records no longer needed; IDs embedded in arbitrary payloads remain opaque to the host.
255
+ - Renaming a view or changing membership does not affect scoped records. Removing a view does not delete concept data.
256
+ - Deleting a concept or saved view retains its records, including across restart and backup restoration. Document Undo/Redo can recover the entity during the current app session, reconnecting its records by the same ID; private storage changes themselves do not enter graph history. Creating a different entity with the same name does not reconnect old records.
257
+ - Use explicit scopes to identify concept or view data, including logs. Plugins own payload schemas and any explicit cleanup; the host does not automatically purge orphan records. IDs embedded in arbitrary keys or payloads remain opaque to the host.
245
258
  - Disabling, uninstalling, replacing, or crashing a plugin does not delete its stored data.
246
259
 
247
260
  #### Limits
package/dist/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- import { B as ThemeDefinition, C as PluginStorage, F as PluginError, G as SavedView, K as Selection, L as LocalizedText, T as PluginStorageRecord, U as GraphSnapshot, W as NessoOperation, a as ActionDescriptor, c as PluginI18n, i as ActionContribution, l as PluginManifest, n as ActionBadgeResult, o as ActionIconName, q as VocabDefinition, r as ActionContext, s as ActionState, t as ActionBadgeInput, u as actionIconNames, w as PluginStorageKey } from "./runtime-BxtTAcko.js";
2
- export { type ActionBadgeInput, type ActionBadgeResult, type ActionContext, type ActionContribution, type ActionDescriptor, type ActionIconName, type ActionState, type GraphSnapshot, type LocalizedText, type NessoOperation, PluginError, type PluginI18n, type PluginManifest, type PluginStorage, type PluginStorageKey, type PluginStorageRecord, type SavedView, type Selection, type ThemeDefinition, type VocabDefinition, actionIconNames };
1
+ import { B as LocalizedText, C as PluginStorage, E as PluginStorageScope, I as ImageRenderOptions, J as SavedView, K as GraphSnapshot, L as RenderedImage, R as PluginError, T as PluginStorageRecord, U as ThemeDefinition, X as VocabDefinition, Y as Selection, a as ActionDescriptor, c as PluginI18n, i as ActionContribution, l as PluginManifest, n as ActionBadgeResult, o as ActionIconName, q as NessoOperation, r as ActionContext, s as ActionState, t as ActionBadgeInput, u as actionIconNames, w as PluginStorageKey } from "./runtime-DGDBGkWs.js";
2
+ export { type ActionBadgeInput, type ActionBadgeResult, type ActionContext, type ActionContribution, type ActionDescriptor, type ActionIconName, type ActionState, type GraphSnapshot, type ImageRenderOptions, type LocalizedText, type NessoOperation, PluginError, type PluginI18n, type PluginManifest, type PluginStorage, type PluginStorageKey, type PluginStorageRecord, type PluginStorageScope, type RenderedImage, type SavedView, type Selection, type ThemeDefinition, type VocabDefinition, actionIconNames };
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- export { C as PluginError, t as actionIconNames } from "./runtime-BM45o1qi.js";
1
+ export { C as PluginError, t as actionIconNames } from "./runtime-D6GosMdU.js";
package/dist/node/data.js CHANGED
@@ -1,21 +1,32 @@
1
1
  import { PluginError } from './errors.js';
2
2
  export function checkMessageSize(value, limit, maximumDepth = 32) {
3
+ const exceeded = () => new PluginError('invalid-input', [{ path: 'message', message: 'Message limit exceeded' }]);
4
+ let size = 0;
3
5
  const visit = (value, depth) => {
4
6
  if (depth > maximumDepth)
5
7
  throw new PluginError('invalid-input', [
6
8
  { path: 'message', message: 'Nesting limit exceeded' },
7
9
  ]);
10
+ if (value === undefined)
11
+ return;
12
+ size += typeof value === 'string' ? value.length + 1 : 1;
13
+ if (size > limit)
14
+ throw exceeded();
8
15
  if (value === null)
9
16
  return;
10
17
  if (typeof value === 'object') {
11
- if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype)
18
+ const array = Array.isArray(value);
19
+ if (!array && Object.getPrototypeOf(value) !== Object.prototype)
12
20
  throw new PluginError('invalid-input', [
13
21
  { path: 'message', message: 'Expected plain data' },
14
22
  ]);
15
- for (const item of Object.values(value))
23
+ for (const [key, item] of Object.entries(value)) {
24
+ if (!array && item !== undefined)
25
+ size += key.length;
16
26
  visit(item, depth + 1);
27
+ }
17
28
  }
18
- else if (!['string', 'number', 'boolean', 'undefined'].includes(typeof value) ||
29
+ else if (!['string', 'number', 'boolean'].includes(typeof value) ||
19
30
  (typeof value === 'number' && !Number.isFinite(value))) {
20
31
  throw new PluginError('invalid-input', [
21
32
  { path: 'message', message: 'Expected serializable data' },
@@ -24,5 +35,5 @@ export function checkMessageSize(value, limit, maximumDepth = 32) {
24
35
  };
25
36
  visit(value, 0);
26
37
  if (new TextEncoder().encode(JSON.stringify(value)).byteLength > limit)
27
- throw new PluginError('invalid-input', [{ path: 'message', message: 'Message limit exceeded' }]);
38
+ throw exceeded();
28
39
  }
@@ -1,6 +1,8 @@
1
1
  import { NessoError, type ErrorIssue } from '@nesso-how/errors';
2
2
  import type { ZodType } from 'zod';
3
3
  import type { LocalizedText } from './i18n.ts';
4
+ export declare const pluginErrorCodes: readonly ['invalid-input', 'denied', 'stale-state', 'stale-context', 'unavailable', 'cancelled', 'timeout', 'closed', 'failed'];
5
+ export declare function pluginErrorCode(error: unknown): "cancelled" | "closed" | "denied" | "failed" | "invalid-input" | "stale-context" | "stale-state" | "timeout" | "unavailable";
4
6
  export declare class PluginError extends NessoError {
5
7
  name: string;
6
8
  readonly code: string;
@@ -11,6 +11,21 @@ const boundText = (text, limit) => {
11
11
  }
12
12
  return result;
13
13
  };
14
+ export const pluginErrorCodes = [
15
+ 'invalid-input',
16
+ 'denied',
17
+ 'stale-state',
18
+ 'stale-context',
19
+ 'unavailable',
20
+ 'cancelled',
21
+ 'timeout',
22
+ 'closed',
23
+ 'failed',
24
+ ];
25
+ export function pluginErrorCode(error) {
26
+ const code = error instanceof Error && 'code' in error ? error.code : undefined;
27
+ return pluginErrorCodes.find((known) => known === code) ?? 'failed';
28
+ }
14
29
  export class PluginError extends NessoError {
15
30
  name = 'PluginError';
16
31
  code;
@@ -4,11 +4,16 @@ export declare const fileOpenOptions: z.ZodObject<{
4
4
  extensions: z.ZodArray<z.ZodString>;
5
5
  mimeTypes: z.ZodArray<z.ZodString>;
6
6
  }, z.core.$strict>;
7
- export declare const fileSaveOptions: z.ZodObject<{
7
+ export declare const fileBase64: z.ZodString;
8
+ export declare const fileSaveOptions: z.ZodUnion<readonly [z.ZodObject<{
8
9
  name: z.ZodString;
9
10
  mediaType: z.ZodString;
10
11
  text: z.ZodString;
11
- }, z.core.$strict>;
12
+ }, z.core.$strict>, z.ZodObject<{
13
+ name: z.ZodString;
14
+ mediaType: z.ZodString;
15
+ base64: z.ZodString;
16
+ }, z.core.$strict>]>;
12
17
  export declare const fileOpenResult: z.ZodNullable<z.ZodObject<{
13
18
  name: z.ZodString;
14
19
  mediaType: z.ZodString;
@@ -12,7 +12,7 @@ export const fileOpenOptions = z.strictObject({
12
12
  .max(16),
13
13
  mimeTypes: z.array(mediaType).max(16),
14
14
  });
15
- export const fileSaveOptions = z.strictObject({
15
+ const fileFields = {
16
16
  name: z
17
17
  .string()
18
18
  .trim()
@@ -23,13 +23,30 @@ export const fileSaveOptions = z.strictObject({
23
23
  value !== '..' &&
24
24
  [...value].every((character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127)),
25
25
  mediaType,
26
- text: z
27
- .string()
28
- .max(fileTextLimit)
29
- .refine((value) => new TextEncoder().encode(value).byteLength <= fileTextLimit, 'File text byte limit exceeded'),
30
- });
26
+ };
27
+ const fileText = z
28
+ .string()
29
+ .max(fileTextLimit)
30
+ .refine((value) => new TextEncoder().encode(value).byteLength <= fileTextLimit, 'File text byte limit exceeded');
31
+ export const fileBase64 = z
32
+ .string()
33
+ .max(4 * Math.ceil(fileTextLimit / 3))
34
+ .regex(/^[A-Za-z0-9+/]*={0,2}$/)
35
+ .refine((value) => {
36
+ const size = (value.length / 4) * 3 - (value.endsWith('==') ? 2 : value.endsWith('=') ? 1 : 0);
37
+ try {
38
+ return value.length % 4 === 0 && size <= fileTextLimit && btoa(atob(value)) === value;
39
+ }
40
+ catch {
41
+ return false;
42
+ }
43
+ }, 'Invalid base64 or file byte limit exceeded');
44
+ export const fileSaveOptions = z.union([
45
+ z.strictObject({ ...fileFields, text: fileText }),
46
+ z.strictObject({ ...fileFields, base64: fileBase64 }),
47
+ ]);
31
48
  export const fileOpenResult = z
32
- .strictObject({ name: z.string().min(1).max(240), mediaType, text: fileSaveOptions.shape.text })
49
+ .strictObject({ name: z.string().min(1).max(240), mediaType, text: fileText })
33
50
  .nullable();
34
51
  export function parseFileOptions(kind, value) {
35
52
  return parseOrThrow(kind === 'open' ? fileOpenOptions : fileSaveOptions, value);
@@ -0,0 +1,11 @@
1
+ import { z } from 'zod';
2
+ export declare const imageRenderOptions: z.ZodObject<{
3
+ format: z.ZodLiteral<"png">;
4
+ scale: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<4>]>>;
5
+ }, z.core.$strict>;
6
+ export declare const renderedImage: z.ZodObject<{
7
+ mediaType: z.ZodLiteral<"image/png">;
8
+ base64: z.ZodString;
9
+ }, z.core.$strict>;
10
+ export type ImageRenderOptions = Readonly<z.infer<typeof imageRenderOptions>>;
11
+ export type RenderedImage = Readonly<z.infer<typeof renderedImage>>;
@@ -0,0 +1,10 @@
1
+ import { z } from 'zod';
2
+ import { fileBase64 } from './files.js';
3
+ export const imageRenderOptions = z.strictObject({
4
+ format: z.literal('png'),
5
+ scale: z.union([z.literal(2), z.literal(4)]).optional(),
6
+ });
7
+ export const renderedImage = z.strictObject({
8
+ mediaType: z.literal('image/png'),
9
+ base64: fileBase64,
10
+ });
@@ -3,4 +3,5 @@ export type { ThemeDefinition } from './definitions.ts';
3
3
  export { PluginError } from './errors.ts';
4
4
  export type { ActionContext, ActionBadgeInput, ActionBadgeResult, ActionContribution, ActionDescriptor, ActionIconName, ActionState, LocalizedText, PluginI18n, PluginManifest, } from './runtime.ts';
5
5
  export { actionIconNames } from './runtime.ts';
6
- export type { PluginStorage, PluginStorageKey, PluginStorageRecord } from './storage.ts';
6
+ export type { ImageRenderOptions, RenderedImage } from './images.ts';
7
+ export type { PluginStorage, PluginStorageKey, PluginStorageRecord, PluginStorageScope, } from './storage.ts';
@@ -1,4 +1,6 @@
1
1
  import { z } from 'zod';
2
+ import { type ImageRenderOptions, type RenderedImage } from './images.ts';
3
+ export type { ImageRenderOptions, RenderedImage } from './images.ts';
2
4
  import type { ComponentType } from 'react';
3
5
  import type { DeepReadonly, GraphSnapshot, NessoOperation, Selection, SavedView, VocabDefinition } from '@nesso-how/core';
4
6
  import type { Locale } from '@nesso-how/i18n';
@@ -66,7 +68,7 @@ export type PluginI18n = DeepReadonly<{
66
68
  }>;
67
69
  export declare function parsePluginI18n(value: unknown): PluginI18n;
68
70
  declare const manifest: z.ZodDiscriminatedUnion<[z.ZodObject<{
69
- apiVersion: z.ZodLiteral<1>;
71
+ apiVersion: z.ZodLiteral<2>;
70
72
  kind: z.ZodLiteral<"actions">;
71
73
  entry: z.ZodString;
72
74
  writes: z.ZodArray<z.ZodEnum<{
@@ -89,12 +91,13 @@ declare const manifest: z.ZodDiscriminatedUnion<[z.ZodObject<{
89
91
  }>>;
90
92
  capabilities: z.ZodArray<z.ZodEnum<{
91
93
  files: "files";
94
+ images: "images";
92
95
  notifications: "notifications";
93
96
  storage: "storage";
94
97
  ui: "ui";
95
98
  }>>;
96
99
  }, z.core.$strict>, ...z.ZodObject<{
97
- apiVersion: z.ZodLiteral<1>;
100
+ apiVersion: z.ZodLiteral<2>;
98
101
  kind: z.ZodLiteral<"theme" | "vocab">;
99
102
  entry: z.ZodString;
100
103
  writes: z.ZodTuple<[], null>;
@@ -272,7 +275,13 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
272
275
  method: z.ZodLiteral<"storage.set">;
273
276
  params: z.ZodObject<{
274
277
  key: z.ZodString;
275
- conceptId: z.ZodOptional<z.ZodString>;
278
+ scope: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
279
+ kind: z.ZodLiteral<"concept">;
280
+ id: z.ZodString;
281
+ }, z.core.$strict>, z.ZodObject<{
282
+ kind: z.ZodLiteral<"view">;
283
+ id: z.ZodString;
284
+ }, z.core.$strict>], "kind">>;
276
285
  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 | {
277
286
  readonly [key: string]: string | number | boolean | /*elided*/ any | /*elided*/ any | null;
278
287
  } | null)[] | {
@@ -379,7 +388,13 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
379
388
  method: z.ZodLiteral<"storage.delete">;
380
389
  params: z.ZodObject<{
381
390
  key: z.ZodString;
382
- conceptId: z.ZodOptional<z.ZodString>;
391
+ scope: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
392
+ kind: z.ZodLiteral<"concept">;
393
+ id: z.ZodString;
394
+ }, z.core.$strict>, z.ZodObject<{
395
+ kind: z.ZodLiteral<"view">;
396
+ id: z.ZodString;
397
+ }, z.core.$strict>], "kind">>;
383
398
  revision: z.ZodNumber;
384
399
  }, z.core.$strict>;
385
400
  }, z.core.$strict>, z.ZodObject<{
@@ -417,10 +432,23 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
417
432
  id: z.ZodNumber;
418
433
  contextId: z.ZodString;
419
434
  method: z.ZodLiteral<"files.save">;
420
- params: z.ZodObject<{
435
+ params: z.ZodUnion<readonly [z.ZodObject<{
421
436
  name: z.ZodString;
422
437
  mediaType: z.ZodString;
423
438
  text: z.ZodString;
439
+ }, z.core.$strict>, z.ZodObject<{
440
+ name: z.ZodString;
441
+ mediaType: z.ZodString;
442
+ base64: z.ZodString;
443
+ }, z.core.$strict>]>;
444
+ }, z.core.$strict>, z.ZodObject<{
445
+ type: z.ZodLiteral<"request">;
446
+ id: z.ZodNumber;
447
+ contextId: z.ZodString;
448
+ method: z.ZodLiteral<"images.renderView">;
449
+ params: z.ZodObject<{
450
+ format: z.ZodLiteral<"png">;
451
+ scale: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<4>]>>;
424
452
  }, z.core.$strict>;
425
453
  }, z.core.$strict>], "method">, z.ZodObject<{
426
454
  type: z.ZodLiteral<"panel-ready">;
@@ -544,6 +572,9 @@ export type ActionContext = {
544
572
  }>;
545
573
  };
546
574
  readonly storage: PluginStorage;
575
+ readonly images: {
576
+ readonly renderView: (options: ImageRenderOptions) => Promise<RenderedImage>;
577
+ };
547
578
  readonly signal: AbortSignal;
548
579
  };
549
580
  export declare function parsePluginMessage(value: unknown): z.infer<typeof message>;
@@ -1,6 +1,7 @@
1
1
  import { z } from 'zod';
2
+ import { imageRenderOptions, renderedImage, } from './images.js';
2
3
  import { graphSchema, positionSchema } from '@nesso-how/schema';
3
- import { parseOrThrow, PluginError } from './errors.js';
4
+ import { parseOrThrow, PluginError, pluginErrorCodes } from './errors.js';
4
5
  import { parseDefinition, themeColors, vocabRelationType } from './definitions.js';
5
6
  import { fileOpenOptions, fileOpenResult, fileSaveOptions, } from './files.js';
6
7
  import { createWriteCommands } from '@nesso-how/core';
@@ -118,7 +119,7 @@ export function parsePluginI18n(value) {
118
119
  return parseOrThrow(pluginI18n, value, 'i18n.');
119
120
  }
120
121
  const manifestFields = {
121
- apiVersion: z.literal(1),
122
+ apiVersion: z.literal(2),
122
123
  };
123
124
  const jsEntry = z
124
125
  .string()
@@ -154,7 +155,7 @@ const manifest = z
154
155
  kind: z.literal('actions'),
155
156
  entry: jsEntry,
156
157
  writes: operationDeclarations,
157
- capabilities: z.array(z.enum(['files', 'notifications', 'storage', 'ui'])),
158
+ capabilities: z.array(z.enum(['files', 'images', 'notifications', 'storage', 'ui'])),
158
159
  }),
159
160
  ...['theme', 'vocab'].map((kind) => z.strictObject({
160
161
  ...manifestFields,
@@ -208,19 +209,14 @@ const request = z.discriminatedUnion('method', [
208
209
  }),
209
210
  z.strictObject({ ...envelope, method: z.literal('files.open'), params: fileOpenOptions }),
210
211
  z.strictObject({ ...envelope, method: z.literal('files.save'), params: fileSaveOptions }),
212
+ z.strictObject({
213
+ ...envelope,
214
+ method: z.literal('images.renderView'),
215
+ params: imageRenderOptions,
216
+ }),
211
217
  ]);
212
218
  const wireError = z.strictObject({
213
- code: z.enum([
214
- 'invalid-input',
215
- 'denied',
216
- 'stale-state',
217
- 'stale-context',
218
- 'unavailable',
219
- 'cancelled',
220
- 'timeout',
221
- 'closed',
222
- 'failed',
223
- ]),
219
+ code: z.enum(pluginErrorCodes),
224
220
  issues: z
225
221
  .array(z.strictObject({ path: text(256), message: text(2048) }))
226
222
  .min(1)
@@ -340,6 +336,7 @@ const results = {
340
336
  'notifications.notify': id,
341
337
  'files.open': fileOpenResult,
342
338
  'files.save': z.strictObject({ saved: z.boolean() }),
339
+ 'images.renderView': renderedImage,
343
340
  };
344
341
  export function parsePluginMessage(value) {
345
342
  checkMessageSize(value, runtimeLimits.request);
@@ -491,14 +488,15 @@ export function createPluginClient(port, initial) {
491
488
  applyOperations,
492
489
  },
493
490
  notifications: { notify: (value) => call('notifications.notify', value) },
491
+ images: { renderView: (options) => call('images.renderView', options) },
494
492
  files: {
495
493
  open: (options) => call('files.open', options),
496
494
  save: (options) => call('files.save', options),
497
495
  },
498
496
  storage: {
499
497
  list: listStorage,
500
- set: (key, value, conceptId) => mutateStorage('storage.set', conceptId === undefined ? { key, value } : { key, value, conceptId }),
501
- delete: (key, conceptId) => mutateStorage('storage.delete', conceptId === undefined ? { key } : { key, conceptId }),
498
+ set: (key, value, scope) => mutateStorage('storage.set', scope === undefined ? { key, value } : { key, value, scope }),
499
+ delete: (key, scope) => mutateStorage('storage.delete', scope === undefined ? { key } : { key, scope }),
502
500
  },
503
501
  signal: controller.signal,
504
502
  };
@@ -11,13 +11,32 @@ export declare const pluginStorageLimits: {
11
11
  type JsonValue = null | string | number | boolean | readonly JsonValue[] | {
12
12
  readonly [key: string]: JsonValue;
13
13
  };
14
+ declare const pluginStorageScope: z.ZodDiscriminatedUnion<[z.ZodObject<{
15
+ kind: z.ZodLiteral<"concept">;
16
+ id: z.ZodString;
17
+ }, z.core.$strict>, z.ZodObject<{
18
+ kind: z.ZodLiteral<"view">;
19
+ id: z.ZodString;
20
+ }, z.core.$strict>], "kind">;
14
21
  export declare const pluginStorageKey: z.ZodObject<{
15
22
  key: z.ZodString;
16
- conceptId: z.ZodOptional<z.ZodString>;
23
+ scope: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
24
+ kind: z.ZodLiteral<"concept">;
25
+ id: z.ZodString;
26
+ }, z.core.$strict>, z.ZodObject<{
27
+ kind: z.ZodLiteral<"view">;
28
+ id: z.ZodString;
29
+ }, z.core.$strict>], "kind">>;
17
30
  }, z.core.$strict>;
18
31
  export declare const pluginStorageRecord: z.ZodObject<{
19
32
  key: z.ZodString;
20
- conceptId: z.ZodOptional<z.ZodString>;
33
+ scope: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
34
+ kind: z.ZodLiteral<"concept">;
35
+ id: z.ZodString;
36
+ }, z.core.$strict>, z.ZodObject<{
37
+ kind: z.ZodLiteral<"view">;
38
+ id: z.ZodString;
39
+ }, z.core.$strict>], "kind">>;
21
40
  value: z.ZodPipe<z.ZodCustom<JsonValue, JsonValue>, z.ZodTransform<string | number | boolean | readonly JsonValue[] | {
22
41
  readonly [key: string]: JsonValue;
23
42
  } | null, JsonValue>>;
@@ -27,7 +46,13 @@ export declare const pluginStorageSnapshot: z.ZodObject<{
27
46
  revision: z.ZodNumber;
28
47
  records: z.ZodArray<z.ZodObject<{
29
48
  key: z.ZodString;
30
- conceptId: z.ZodOptional<z.ZodString>;
49
+ scope: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
50
+ kind: z.ZodLiteral<"concept">;
51
+ id: z.ZodString;
52
+ }, z.core.$strict>, z.ZodObject<{
53
+ kind: z.ZodLiteral<"view">;
54
+ id: z.ZodString;
55
+ }, z.core.$strict>], "kind">>;
31
56
  value: z.ZodPipe<z.ZodCustom<JsonValue, JsonValue>, z.ZodTransform<string | number | boolean | readonly JsonValue[] | {
32
57
  readonly [key: string]: JsonValue;
33
58
  } | null, JsonValue>>;
@@ -35,10 +60,11 @@ export declare const pluginStorageSnapshot: z.ZodObject<{
35
60
  }, z.core.$strict>;
36
61
  export type PluginStorageRecord = DeepReadonly<z.infer<typeof pluginStorageRecord>>;
37
62
  export type PluginStorageKey = DeepReadonly<z.infer<typeof pluginStorageKey>>;
63
+ export type PluginStorageScope = DeepReadonly<z.infer<typeof pluginStorageScope>>;
38
64
  export type PluginStorage = {
39
65
  readonly list: () => Promise<readonly PluginStorageRecord[]>;
40
- readonly set: (key: string, value: PluginStorageRecord['value'], conceptId?: string) => Promise<boolean>;
41
- readonly delete: (key: string, conceptId?: string) => Promise<boolean>;
66
+ readonly set: (key: string, value: PluginStorageRecord['value'], scope?: PluginStorageScope) => Promise<boolean>;
67
+ readonly delete: (key: string, scope?: PluginStorageScope) => Promise<boolean>;
42
68
  };
43
69
  export declare function parsePluginStorageSnapshot(value: unknown): DeepReadonly<z.infer<typeof pluginStorageSnapshot>>;
44
70
  export declare function parsePluginStorageRecord(value: unknown): PluginStorageRecord;
@@ -25,9 +25,13 @@ const isJsonValue = (value, depth = 0) => {
25
25
  Reflect.ownKeys(value).length === Object.keys(value).length &&
26
26
  Object.values(value).every((item) => isJsonValue(item, depth + 1)));
27
27
  };
28
+ const pluginStorageScope = z.discriminatedUnion('kind', [
29
+ z.strictObject({ kind: z.literal('concept'), id: z.string().max(2048) }),
30
+ z.strictObject({ kind: z.literal('view'), id: z.string().max(2048) }),
31
+ ]);
28
32
  const fields = {
29
33
  key: z.string().min(1).max(128),
30
- conceptId: z.string().max(2048).optional(),
34
+ scope: pluginStorageScope.optional(),
31
35
  };
32
36
  export const pluginStorageKey = z.strictObject(fields);
33
37
  export const pluginStorageRecord = z
package/dist/package.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { c as PluginI18n, l as PluginManifest } from "./runtime-BxtTAcko.js";
1
+ import { c as PluginI18n, l as PluginManifest } from "./runtime-DGDBGkWs.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 { C as PluginError, _ as checkMessageSize, o as parsePluginI18n, s as parsePluginManifest, u as sha256Hex, w as parseOrThrow, x as parseDefinition } from "./runtime-BM45o1qi.js";
1
+ import { C as PluginError, _ as checkMessageSize, o as parsePluginI18n, s as parsePluginManifest, u as sha256Hex, w as parseOrThrow, y as parseDefinition } from "./runtime-D6GosMdU.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";
@@ -27,6 +27,17 @@ const boundText = (text, limit) => {
27
27
  }
28
28
  return result;
29
29
  };
30
+ const pluginErrorCodes = [
31
+ "invalid-input",
32
+ "denied",
33
+ "stale-state",
34
+ "stale-context",
35
+ "unavailable",
36
+ "cancelled",
37
+ "timeout",
38
+ "closed",
39
+ "failed"
40
+ ];
30
41
  var PluginError = class extends NessoError {
31
42
  name = "PluginError";
32
43
  code;
@@ -58,7 +69,62 @@ function parseOrThrow(schema, value, prefix = "") {
58
69
  return parsed.data;
59
70
  }
60
71
  //#endregion
72
+ //#region src/files.ts
73
+ const fileTextLimit = 16777216;
74
+ const mediaType = z.string().max(128).regex(/^[\w!#$&^.+-]+\/[\w!#$&^.+-]+$/);
75
+ const fileOpenOptions = z.strictObject({
76
+ extensions: z.array(z.string().regex(/^[a-zA-Z0-9]{1,16}$/)).min(1).max(16),
77
+ mimeTypes: z.array(mediaType).max(16)
78
+ });
79
+ const fileFields = {
80
+ name: z.string().trim().min(1).max(240).regex(/^[^/\\]+$/).refine((value) => value !== "." && value !== ".." && [...value].every((character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127)),
81
+ mediaType
82
+ };
83
+ const fileText = z.string().max(fileTextLimit).refine((value) => new TextEncoder().encode(value).byteLength <= fileTextLimit, "File text byte limit exceeded");
84
+ const fileBase64 = z.string().max(4 * Math.ceil(fileTextLimit / 3)).regex(/^[A-Za-z0-9+/]*={0,2}$/).refine((value) => {
85
+ const size = value.length / 4 * 3 - (value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0);
86
+ try {
87
+ return value.length % 4 === 0 && size <= 16777216 && btoa(atob(value)) === value;
88
+ } catch {
89
+ return false;
90
+ }
91
+ }, "Invalid base64 or file byte limit exceeded");
92
+ const fileSaveOptions = z.union([z.strictObject({
93
+ ...fileFields,
94
+ text: fileText
95
+ }), z.strictObject({
96
+ ...fileFields,
97
+ base64: fileBase64
98
+ })]);
99
+ const fileOpenResult = z.strictObject({
100
+ name: z.string().min(1).max(240),
101
+ mediaType,
102
+ text: fileText
103
+ }).nullable();
104
+ function parseFileOptions(kind, value) {
105
+ return parseOrThrow(kind === "open" ? fileOpenOptions : fileSaveOptions, value);
106
+ }
107
+ //#endregion
108
+ //#region src/images.ts
109
+ const imageRenderOptions = z.strictObject({
110
+ format: z.literal("png"),
111
+ scale: z.union([z.literal(2), z.literal(4)]).optional()
112
+ });
113
+ const renderedImage = z.strictObject({
114
+ mediaType: z.literal("image/png"),
115
+ base64: fileBase64
116
+ });
117
+ //#endregion
61
118
  //#region ../schema/dist/core.js
119
+ const conceptKeys = [
120
+ "@id",
121
+ "rdfs:label",
122
+ "rdfs:comment",
123
+ "position",
124
+ "color",
125
+ "bold",
126
+ "italic"
127
+ ];
62
128
  const newIri = () => `urn:uuid:${crypto.randomUUID()}`;
63
129
  const isAbsoluteIri = (value) => typeof value === "string" && /^[a-z][a-z0-9+.-]*:/i.test(value);
64
130
  const relationKey = ({ source, predicate, target }) => JSON.stringify([
@@ -83,7 +149,7 @@ const conceptSchema = z.strictObject({
83
149
  position: positionSchema
84
150
  });
85
151
  const relationTypeSchema = z.strictObject({
86
- id: iriSchema,
152
+ id: iriSchema.refine((id) => !conceptKeys.includes(id), "Reserved concept property IRI"),
87
153
  label: z.string()
88
154
  });
89
155
  const relationSchema = z.strictObject({
@@ -290,27 +356,6 @@ function parseDefinition(kind, value) {
290
356
  return parseOrThrow(kind === "theme" ? themeDefinition : vocabDefinition, value);
291
357
  }
292
358
  //#endregion
293
- //#region src/files.ts
294
- const fileTextLimit = 16777216;
295
- const mediaType = z.string().max(128).regex(/^[\w!#$&^.+-]+\/[\w!#$&^.+-]+$/);
296
- const fileOpenOptions = z.strictObject({
297
- extensions: z.array(z.string().regex(/^[a-zA-Z0-9]{1,16}$/)).min(1).max(16),
298
- mimeTypes: z.array(mediaType).max(16)
299
- });
300
- const fileSaveOptions = z.strictObject({
301
- name: z.string().trim().min(1).max(240).regex(/^[^/\\]+$/).refine((value) => value !== "." && value !== ".." && [...value].every((character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127)),
302
- mediaType,
303
- text: z.string().max(fileTextLimit).refine((value) => new TextEncoder().encode(value).byteLength <= fileTextLimit, "File text byte limit exceeded")
304
- });
305
- const fileOpenResult = z.strictObject({
306
- name: z.string().min(1).max(240),
307
- mediaType,
308
- text: fileSaveOptions.shape.text
309
- }).nullable();
310
- function parseFileOptions(kind, value) {
311
- return parseOrThrow(kind === "open" ? fileOpenOptions : fileSaveOptions, value);
312
- }
313
- //#endregion
314
359
  //#region ../core/dist/commands.js
315
360
  function createWriteCommands(applyOperations, created) {
316
361
  return {
@@ -460,33 +505,41 @@ const resolvePluginText = (value, locale) => value[locale] ?? value.en;
460
505
  //#endregion
461
506
  //#region src/data.ts
462
507
  function checkMessageSize(value, limit, maximumDepth = 32) {
508
+ const exceeded = () => new PluginError("invalid-input", [{
509
+ path: "message",
510
+ message: "Message limit exceeded"
511
+ }]);
512
+ let size = 0;
463
513
  const visit = (value, depth) => {
464
514
  if (depth > maximumDepth) throw new PluginError("invalid-input", [{
465
515
  path: "message",
466
516
  message: "Nesting limit exceeded"
467
517
  }]);
518
+ if (value === void 0) return;
519
+ size += typeof value === "string" ? value.length + 1 : 1;
520
+ if (size > limit) throw exceeded();
468
521
  if (value === null) return;
469
522
  if (typeof value === "object") {
470
- if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype) throw new PluginError("invalid-input", [{
523
+ const array = Array.isArray(value);
524
+ if (!array && Object.getPrototypeOf(value) !== Object.prototype) throw new PluginError("invalid-input", [{
471
525
  path: "message",
472
526
  message: "Expected plain data"
473
527
  }]);
474
- for (const item of Object.values(value)) visit(item, depth + 1);
528
+ for (const [key, item] of Object.entries(value)) {
529
+ if (!array && item !== void 0) size += key.length;
530
+ visit(item, depth + 1);
531
+ }
475
532
  } else if (![
476
533
  "string",
477
534
  "number",
478
- "boolean",
479
- "undefined"
535
+ "boolean"
480
536
  ].includes(typeof value) || typeof value === "number" && !Number.isFinite(value)) throw new PluginError("invalid-input", [{
481
537
  path: "message",
482
538
  message: "Expected serializable data"
483
539
  }]);
484
540
  };
485
541
  visit(value, 0);
486
- if (new TextEncoder().encode(JSON.stringify(value)).byteLength > limit) throw new PluginError("invalid-input", [{
487
- path: "message",
488
- message: "Message limit exceeded"
489
- }]);
542
+ if (new TextEncoder().encode(JSON.stringify(value)).byteLength > limit) throw exceeded();
490
543
  }
491
544
  //#endregion
492
545
  //#region src/storage.ts
@@ -506,9 +559,16 @@ const isJsonValue = (value, depth = 0) => {
506
559
  if (Array.isArray(value)) return Reflect.ownKeys(value).length === value.length + 1 && Array.from(value).every((item) => isJsonValue(item, depth + 1));
507
560
  return Object.getPrototypeOf(value) === Object.prototype && Reflect.ownKeys(value).length === Object.keys(value).length && Object.values(value).every((item) => isJsonValue(item, depth + 1));
508
561
  };
562
+ const pluginStorageScope = z.discriminatedUnion("kind", [z.strictObject({
563
+ kind: z.literal("concept"),
564
+ id: z.string().max(2048)
565
+ }), z.strictObject({
566
+ kind: z.literal("view"),
567
+ id: z.string().max(2048)
568
+ })]);
509
569
  const fields = {
510
570
  key: z.string().min(1).max(128),
511
- conceptId: z.string().max(2048).optional()
571
+ scope: pluginStorageScope.optional()
512
572
  };
513
573
  const pluginStorageKey = z.strictObject(fields);
514
574
  const pluginStorageRecord = z.strictObject({
@@ -752,7 +812,7 @@ function parsePluginI18n(value) {
752
812
  checkMessageSize(value, 65536);
753
813
  return parseOrThrow(pluginI18n, value, "i18n.");
754
814
  }
755
- const manifestFields = { apiVersion: z.literal(1) };
815
+ const manifestFields = { apiVersion: z.literal(2) };
756
816
  const jsEntry = z.string().max(240).regex(/^(?:[\w-]+\/)*[\w-]+\.js$/);
757
817
  const jsonEntry = z.string().max(240).regex(/^(?:[\w-]+\/)*[\w-]+\.json$/);
758
818
  const operationDeclarations = z.array(z.enum([
@@ -780,6 +840,7 @@ const manifest = z.discriminatedUnion("kind", [z.strictObject({
780
840
  writes: operationDeclarations,
781
841
  capabilities: z.array(z.enum([
782
842
  "files",
843
+ "images",
783
844
  "notifications",
784
845
  "storage",
785
846
  "ui"
@@ -848,20 +909,15 @@ const request = z.discriminatedUnion("method", [
848
909
  ...envelope,
849
910
  method: z.literal("files.save"),
850
911
  params: fileSaveOptions
912
+ }),
913
+ z.strictObject({
914
+ ...envelope,
915
+ method: z.literal("images.renderView"),
916
+ params: imageRenderOptions
851
917
  })
852
918
  ]);
853
919
  const wireError = z.strictObject({
854
- code: z.enum([
855
- "invalid-input",
856
- "denied",
857
- "stale-state",
858
- "stale-context",
859
- "unavailable",
860
- "cancelled",
861
- "timeout",
862
- "closed",
863
- "failed"
864
- ]),
920
+ code: z.enum(pluginErrorCodes),
865
921
  issues: z.array(z.strictObject({
866
922
  path: text(256),
867
923
  message: text(2048)
@@ -1004,7 +1060,8 @@ const results = {
1004
1060
  }),
1005
1061
  "notifications.notify": id,
1006
1062
  "files.open": fileOpenResult,
1007
- "files.save": z.strictObject({ saved: z.boolean() })
1063
+ "files.save": z.strictObject({ saved: z.boolean() }),
1064
+ "images.renderView": renderedImage
1008
1065
  };
1009
1066
  function parsePluginMessage(value) {
1010
1067
  checkMessageSize(value, runtimeLimits.request);
@@ -1171,23 +1228,24 @@ function createPluginClient(port, initial) {
1171
1228
  applyOperations
1172
1229
  },
1173
1230
  notifications: { notify: (value) => call("notifications.notify", value) },
1231
+ images: { renderView: (options) => call("images.renderView", options) },
1174
1232
  files: {
1175
1233
  open: (options) => call("files.open", options),
1176
1234
  save: (options) => call("files.save", options)
1177
1235
  },
1178
1236
  storage: {
1179
1237
  list: listStorage,
1180
- set: (key, value, conceptId) => mutateStorage("storage.set", conceptId === void 0 ? {
1238
+ set: (key, value, scope) => mutateStorage("storage.set", scope === void 0 ? {
1181
1239
  key,
1182
1240
  value
1183
1241
  } : {
1184
1242
  key,
1185
1243
  value,
1186
- conceptId
1244
+ scope
1187
1245
  }),
1188
- delete: (key, conceptId) => mutateStorage("storage.delete", conceptId === void 0 ? { key } : {
1246
+ delete: (key, scope) => mutateStorage("storage.delete", scope === void 0 ? { key } : {
1189
1247
  key,
1190
- conceptId
1248
+ scope
1191
1249
  })
1192
1250
  },
1193
1251
  signal: controller.signal
@@ -1200,4 +1258,4 @@ function createPluginClient(port, initial) {
1200
1258
  };
1201
1259
  }
1202
1260
  //#endregion
1203
- export { PluginError as C, themeColors as S, checkMessageSize as _, parseContribution as a, parseFileOptions as b, parsePluginMessage as c, themeTokens as d, fontFaces as f, pluginStorageLimits as g, parsePluginStorageSnapshot as h, parseActionBadgeResult as i, runtimeLimits as l, parsePluginStorageRecord as m, badgeLimits as n, parsePluginI18n as o, parsePluginStorageKey as p, createPluginClient as r, parsePluginManifest as s, actionIconNames as t, sha256Hex as u, resolvePluginText as v, parseOrThrow as w, parseDefinition as x, fileTextLimit as y };
1261
+ export { PluginError as C, parseFileOptions as S, checkMessageSize as _, parseContribution as a, themeColors as b, parsePluginMessage as c, themeTokens as d, fontFaces as f, pluginStorageLimits as g, parsePluginStorageSnapshot as h, parseActionBadgeResult as i, runtimeLimits as l, parsePluginStorageRecord as m, badgeLimits as n, parsePluginI18n as o, parsePluginStorageKey as p, createPluginClient as r, parsePluginManifest as s, actionIconNames as t, sha256Hex as u, resolvePluginText as v, parseOrThrow as w, fileTextLimit as x, parseDefinition as y };
@@ -207,6 +207,8 @@ type Preferences = {
207
207
  readonly locale?: Locale;
208
208
  readonly introSeen?: boolean;
209
209
  readonly mcpEnabled?: boolean;
210
+ readonly disabledBundledActionPlugins?: readonly string[];
211
+ readonly canvasTabOrder?: readonly string[];
210
212
  readonly activeVocabId: string;
211
213
  readonly activeRendererId: string;
212
214
  readonly activeThemeId: string;
@@ -348,17 +350,33 @@ declare class PluginError extends NessoError {
348
350
  }
349
351
  declare function parseOrThrow(schema: ZodType, value: unknown, prefix?: string): any;
350
352
  //#endregion
353
+ //#region src/images.d.ts
354
+ declare const imageRenderOptions: z.ZodObject<{
355
+ format: z.ZodLiteral<"png">;
356
+ scale: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<4>]>>;
357
+ }, z.core.$strict>;
358
+ declare const renderedImage: z.ZodObject<{
359
+ mediaType: z.ZodLiteral<"image/png">;
360
+ base64: z.ZodString;
361
+ }, z.core.$strict>;
362
+ type ImageRenderOptions = Readonly<z.infer<typeof imageRenderOptions>>;
363
+ type RenderedImage = Readonly<z.infer<typeof renderedImage>>;
364
+ //#endregion
351
365
  //#region src/files.d.ts
352
366
  declare const fileTextLimit: number;
353
367
  declare const fileOpenOptions: z.ZodObject<{
354
368
  extensions: z.ZodArray<z.ZodString>;
355
369
  mimeTypes: z.ZodArray<z.ZodString>;
356
370
  }, z.core.$strict>;
357
- declare const fileSaveOptions: z.ZodObject<{
371
+ declare const fileSaveOptions: z.ZodUnion<readonly [z.ZodObject<{
358
372
  name: z.ZodString;
359
373
  mediaType: z.ZodString;
360
374
  text: z.ZodString;
361
- }, z.core.$strict>;
375
+ }, z.core.$strict>, z.ZodObject<{
376
+ name: z.ZodString;
377
+ mediaType: z.ZodString;
378
+ base64: z.ZodString;
379
+ }, z.core.$strict>]>;
362
380
  declare const fileOpenResult: z.ZodNullable<z.ZodObject<{
363
381
  name: z.ZodString;
364
382
  mediaType: z.ZodString;
@@ -381,13 +399,32 @@ declare const pluginStorageLimits: {
381
399
  type JsonValue = null | string | number | boolean | readonly JsonValue[] | {
382
400
  readonly [key: string]: JsonValue;
383
401
  };
402
+ declare const pluginStorageScope: z.ZodDiscriminatedUnion<[z.ZodObject<{
403
+ kind: z.ZodLiteral<"concept">;
404
+ id: z.ZodString;
405
+ }, z.core.$strict>, z.ZodObject<{
406
+ kind: z.ZodLiteral<"view">;
407
+ id: z.ZodString;
408
+ }, z.core.$strict>], "kind">;
384
409
  declare const pluginStorageKey: z.ZodObject<{
385
410
  key: z.ZodString;
386
- conceptId: z.ZodOptional<z.ZodString>;
411
+ scope: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
412
+ kind: z.ZodLiteral<"concept">;
413
+ id: z.ZodString;
414
+ }, z.core.$strict>, z.ZodObject<{
415
+ kind: z.ZodLiteral<"view">;
416
+ id: z.ZodString;
417
+ }, z.core.$strict>], "kind">>;
387
418
  }, z.core.$strict>;
388
419
  declare const pluginStorageRecord: z.ZodObject<{
389
420
  key: z.ZodString;
390
- conceptId: z.ZodOptional<z.ZodString>;
421
+ scope: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
422
+ kind: z.ZodLiteral<"concept">;
423
+ id: z.ZodString;
424
+ }, z.core.$strict>, z.ZodObject<{
425
+ kind: z.ZodLiteral<"view">;
426
+ id: z.ZodString;
427
+ }, z.core.$strict>], "kind">>;
391
428
  value: z.ZodPipe<z.ZodCustom<JsonValue, JsonValue>, z.ZodTransform<string | number | boolean | readonly JsonValue[] | {
392
429
  readonly [key: string]: JsonValue;
393
430
  } | null, JsonValue>>;
@@ -396,7 +433,13 @@ declare const pluginStorageSnapshot: z.ZodObject<{
396
433
  revision: z.ZodNumber;
397
434
  records: z.ZodArray<z.ZodObject<{
398
435
  key: z.ZodString;
399
- conceptId: z.ZodOptional<z.ZodString>;
436
+ scope: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
437
+ kind: z.ZodLiteral<"concept">;
438
+ id: z.ZodString;
439
+ }, z.core.$strict>, z.ZodObject<{
440
+ kind: z.ZodLiteral<"view">;
441
+ id: z.ZodString;
442
+ }, z.core.$strict>], "kind">>;
400
443
  value: z.ZodPipe<z.ZodCustom<JsonValue, JsonValue>, z.ZodTransform<string | number | boolean | readonly JsonValue[] | {
401
444
  readonly [key: string]: JsonValue;
402
445
  } | null, JsonValue>>;
@@ -404,10 +447,11 @@ declare const pluginStorageSnapshot: z.ZodObject<{
404
447
  }, z.core.$strict>;
405
448
  type PluginStorageRecord = DeepReadonly<z.infer<typeof pluginStorageRecord>>;
406
449
  type PluginStorageKey = DeepReadonly<z.infer<typeof pluginStorageKey>>;
450
+ type PluginStorageScope = DeepReadonly<z.infer<typeof pluginStorageScope>>;
407
451
  type PluginStorage = {
408
452
  readonly list: () => Promise<readonly PluginStorageRecord[]>;
409
- readonly set: (key: string, value: PluginStorageRecord['value'], conceptId?: string) => Promise<boolean>;
410
- readonly delete: (key: string, conceptId?: string) => Promise<boolean>;
453
+ readonly set: (key: string, value: PluginStorageRecord['value'], scope?: PluginStorageScope) => Promise<boolean>;
454
+ readonly delete: (key: string, scope?: PluginStorageScope) => Promise<boolean>;
411
455
  };
412
456
  declare function parsePluginStorageSnapshot(value: unknown): DeepReadonly<z.infer<typeof pluginStorageSnapshot>>;
413
457
  declare function parsePluginStorageRecord(value: unknown): PluginStorageRecord;
@@ -472,7 +516,7 @@ type PluginI18n = DeepReadonly<{
472
516
  }>;
473
517
  declare function parsePluginI18n(value: unknown): PluginI18n;
474
518
  declare const manifest: z.ZodDiscriminatedUnion<[z.ZodObject<{
475
- apiVersion: z.ZodLiteral<1>;
519
+ apiVersion: z.ZodLiteral<2>;
476
520
  kind: z.ZodLiteral<"actions">;
477
521
  entry: z.ZodString;
478
522
  writes: z.ZodArray<z.ZodEnum<{
@@ -495,12 +539,13 @@ declare const manifest: z.ZodDiscriminatedUnion<[z.ZodObject<{
495
539
  }>>;
496
540
  capabilities: z.ZodArray<z.ZodEnum<{
497
541
  files: "files";
542
+ images: "images";
498
543
  notifications: "notifications";
499
544
  storage: "storage";
500
545
  ui: "ui";
501
546
  }>>;
502
547
  }, z.core.$strict>, ...z.ZodObject<{
503
- apiVersion: z.ZodLiteral<1>;
548
+ apiVersion: z.ZodLiteral<2>;
504
549
  kind: z.ZodLiteral<"theme" | "vocab">;
505
550
  entry: z.ZodString;
506
551
  writes: z.ZodTuple<[], null>;
@@ -678,7 +723,13 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
678
723
  method: z.ZodLiteral<"storage.set">;
679
724
  params: z.ZodObject<{
680
725
  key: z.ZodString;
681
- conceptId: z.ZodOptional<z.ZodString>;
726
+ scope: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
727
+ kind: z.ZodLiteral<"concept">;
728
+ id: z.ZodString;
729
+ }, z.core.$strict>, z.ZodObject<{
730
+ kind: z.ZodLiteral<"view">;
731
+ id: z.ZodString;
732
+ }, z.core.$strict>], "kind">>;
682
733
  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 | {
683
734
  readonly [key: string]: string | number | boolean | /*elided*/ any | /*elided*/ any | null;
684
735
  } | null)[] | {
@@ -785,7 +836,13 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
785
836
  method: z.ZodLiteral<"storage.delete">;
786
837
  params: z.ZodObject<{
787
838
  key: z.ZodString;
788
- conceptId: z.ZodOptional<z.ZodString>;
839
+ scope: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
840
+ kind: z.ZodLiteral<"concept">;
841
+ id: z.ZodString;
842
+ }, z.core.$strict>, z.ZodObject<{
843
+ kind: z.ZodLiteral<"view">;
844
+ id: z.ZodString;
845
+ }, z.core.$strict>], "kind">>;
789
846
  revision: z.ZodNumber;
790
847
  }, z.core.$strict>;
791
848
  }, z.core.$strict>, z.ZodObject<{
@@ -823,10 +880,23 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
823
880
  id: z.ZodNumber;
824
881
  contextId: z.ZodString;
825
882
  method: z.ZodLiteral<"files.save">;
826
- params: z.ZodObject<{
883
+ params: z.ZodUnion<readonly [z.ZodObject<{
827
884
  name: z.ZodString;
828
885
  mediaType: z.ZodString;
829
886
  text: z.ZodString;
887
+ }, z.core.$strict>, z.ZodObject<{
888
+ name: z.ZodString;
889
+ mediaType: z.ZodString;
890
+ base64: z.ZodString;
891
+ }, z.core.$strict>]>;
892
+ }, z.core.$strict>, z.ZodObject<{
893
+ type: z.ZodLiteral<"request">;
894
+ id: z.ZodNumber;
895
+ contextId: z.ZodString;
896
+ method: z.ZodLiteral<"images.renderView">;
897
+ params: z.ZodObject<{
898
+ format: z.ZodLiteral<"png">;
899
+ scale: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<4>]>>;
830
900
  }, z.core.$strict>;
831
901
  }, z.core.$strict>], "method">, z.ZodObject<{
832
902
  type: z.ZodLiteral<"panel-ready">;
@@ -950,6 +1020,9 @@ type ActionContext = {
950
1020
  }>;
951
1021
  };
952
1022
  readonly storage: PluginStorage;
1023
+ readonly images: {
1024
+ readonly renderView: (options: ImageRenderOptions) => Promise<RenderedImage>;
1025
+ };
953
1026
  readonly signal: AbortSignal;
954
1027
  };
955
1028
  declare function parsePluginMessage(value: unknown): z.infer<typeof message>;
@@ -960,4 +1033,4 @@ declare function createPluginClient(port: MessagePort, initial: unknown): {
960
1033
  getPresentation: () => Pick<ActionState, 'theme' | 'locale'>;
961
1034
  };
962
1035
  //#endregion
963
- export { FileOpenOptions as A, ThemeDefinition as B, PluginStorage as C, parsePluginStorageRecord as D, parsePluginStorageKey as E, PluginError as F, SavedView as G, themeColors as H, parseOrThrow as I, Selection as K, LocalizedText as L, FileSaveOptions as M, fileTextLimit as N, parsePluginStorageSnapshot as O, parseFileOptions as P, resolvePluginText as R, checkMessageSize as S, PluginStorageRecord as T, GraphSnapshot as U, parseDefinition as V, NessoOperation as W, parsePluginMessage as _, ActionDescriptor as a, themeTokens as b, PluginI18n as c, badgeLimits as d, createPluginClient as f, parsePluginManifest as g, parsePluginI18n as h, ActionContribution as i, FileOpenResult as j, pluginStorageLimits as k, PluginManifest as l, parseContribution as m, ActionBadgeResult as n, ActionIconName as o, parseActionBadgeResult as p, VocabDefinition as q, ActionContext as r, ActionState as s, ActionBadgeInput as t, actionIconNames as u, runtimeLimits as v, PluginStorageKey as w, fontFaces as x, sha256Hex as y, Definition as z };
1036
+ export { pluginStorageLimits as A, LocalizedText as B, PluginStorage as C, parsePluginStorageKey as D, PluginStorageScope as E, parseFileOptions as F, themeColors as G, Definition as H, ImageRenderOptions as I, SavedView as J, GraphSnapshot as K, RenderedImage as L, FileOpenResult as M, FileSaveOptions as N, parsePluginStorageRecord as O, fileTextLimit as P, PluginError as R, checkMessageSize as S, PluginStorageRecord as T, ThemeDefinition as U, resolvePluginText as V, parseDefinition as W, VocabDefinition as X, Selection as Y, parsePluginMessage as _, ActionDescriptor as a, themeTokens as b, PluginI18n as c, badgeLimits as d, createPluginClient as f, parsePluginManifest as g, parsePluginI18n as h, ActionContribution as i, FileOpenOptions as j, parsePluginStorageSnapshot as k, PluginManifest as l, parseContribution as m, ActionBadgeResult as n, ActionIconName as o, parseActionBadgeResult as p, NessoOperation as q, ActionContext as r, ActionState as s, ActionBadgeInput as t, actionIconNames as u, runtimeLimits as v, PluginStorageKey as w, fontFaces as x, sha256Hex as y, parseOrThrow as z };
package/dist/runtime.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- import { A as FileOpenOptions, D as parsePluginStorageRecord, E as parsePluginStorageKey, F as PluginError, H as themeColors, I as parseOrThrow, L as LocalizedText, M as FileSaveOptions, N as fileTextLimit, O as parsePluginStorageSnapshot, P as parseFileOptions, R as resolvePluginText, S as checkMessageSize, V as parseDefinition, _ as parsePluginMessage, a as ActionDescriptor, b as themeTokens, c as PluginI18n, d as badgeLimits, f as createPluginClient, g as parsePluginManifest, h as parsePluginI18n, i as ActionContribution, j as FileOpenResult, k as pluginStorageLimits, l as PluginManifest, m as parseContribution, n as ActionBadgeResult, o as ActionIconName, p as parseActionBadgeResult, r as ActionContext, s as ActionState, t as ActionBadgeInput, u as actionIconNames, v as runtimeLimits, x as fontFaces, y as sha256Hex, z as Definition } from "./runtime-BxtTAcko.js";
2
- export { ActionBadgeInput, ActionBadgeResult, ActionContext, ActionContribution, ActionDescriptor, ActionIconName, ActionState, type Definition, type FileOpenOptions, type FileOpenResult, type FileSaveOptions, type LocalizedText, PluginError, PluginI18n, PluginManifest, actionIconNames, badgeLimits, checkMessageSize, createPluginClient, fileTextLimit, fontFaces, parseActionBadgeResult, parseContribution, parseDefinition, parseFileOptions, parseOrThrow, parsePluginI18n, parsePluginManifest, parsePluginMessage, parsePluginStorageKey, parsePluginStorageRecord, parsePluginStorageSnapshot, pluginStorageLimits, resolvePluginText, runtimeLimits, sha256Hex, themeColors, themeTokens };
1
+ import { A as pluginStorageLimits, B as LocalizedText, D as parsePluginStorageKey, F as parseFileOptions, G as themeColors, H as Definition, I as ImageRenderOptions, L as RenderedImage, M as FileOpenResult, N as FileSaveOptions, O as parsePluginStorageRecord, P as fileTextLimit, R as PluginError, S as checkMessageSize, V as resolvePluginText, W as parseDefinition, _ as parsePluginMessage, a as ActionDescriptor, b as themeTokens, c as PluginI18n, d as badgeLimits, f as createPluginClient, g as parsePluginManifest, h as parsePluginI18n, i as ActionContribution, j as FileOpenOptions, k as parsePluginStorageSnapshot, l as PluginManifest, m as parseContribution, n as ActionBadgeResult, o as ActionIconName, p as parseActionBadgeResult, r as ActionContext, s as ActionState, t as ActionBadgeInput, u as actionIconNames, v as runtimeLimits, x as fontFaces, y as sha256Hex, z as parseOrThrow } from "./runtime-DGDBGkWs.js";
2
+ export { ActionBadgeInput, ActionBadgeResult, ActionContext, ActionContribution, ActionDescriptor, ActionIconName, ActionState, type Definition, type FileOpenOptions, type FileOpenResult, type FileSaveOptions, type ImageRenderOptions, type LocalizedText, PluginError, PluginI18n, PluginManifest, type RenderedImage, actionIconNames, badgeLimits, checkMessageSize, createPluginClient, fileTextLimit, fontFaces, parseActionBadgeResult, 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 { C as PluginError, t as actionIconNames, n as badgeLimits, _ as checkMessageSize, r as createPluginClient, y as fileTextLimit, f as fontFaces, i as parseActionBadgeResult, a as parseContribution, x as parseDefinition, b as parseFileOptions, w as parseOrThrow, o as parsePluginI18n, s as parsePluginManifest, c as parsePluginMessage, p as parsePluginStorageKey, m as parsePluginStorageRecord, h as parsePluginStorageSnapshot, g as pluginStorageLimits, v as resolvePluginText, l as runtimeLimits, u as sha256Hex, S as themeColors, d as themeTokens } from "./runtime-BM45o1qi.js";
1
+ export { C as PluginError, t as actionIconNames, n as badgeLimits, _ as checkMessageSize, r as createPluginClient, x as fileTextLimit, f as fontFaces, i as parseActionBadgeResult, a as parseContribution, y as parseDefinition, S as parseFileOptions, w as parseOrThrow, o as parsePluginI18n, s as parsePluginManifest, c as parsePluginMessage, p as parsePluginStorageKey, m as parsePluginStorageRecord, h as parsePluginStorageSnapshot, g as pluginStorageLimits, v as resolvePluginText, l as runtimeLimits, u as sha256Hex, b as themeColors, d as themeTokens } from "./runtime-D6GosMdU.js";
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nesso-how/plugin-example",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Official example showing how to build Nesso plugins with the SDK and plugin APIs",
5
5
  "keywords": [
6
6
  "nesso-plugin"
@@ -28,12 +28,12 @@
28
28
  "prepack": "npm run build"
29
29
  },
30
30
  "dependencies": {
31
- "@nesso-how/ui": "1.0.0-beta.1",
31
+ "@nesso-how/ui": "1.0.0-beta.2",
32
32
  "react": "^19.2.8",
33
33
  "react-dom": "^19.2.8"
34
34
  },
35
35
  "devDependencies": {
36
- "@nesso-how/plugin": "0.6.0",
36
+ "@nesso-how/plugin": "0.7.0",
37
37
  "@types/react": "^19.2.18",
38
38
  "@types/react-dom": "^19.2.7",
39
39
  "typescript": "~7.0.2",
@@ -54,7 +54,7 @@
54
54
  }
55
55
  },
56
56
  "nesso": {
57
- "apiVersion": 1,
57
+ "apiVersion": 2,
58
58
  "kind": "actions",
59
59
  "entry": "dist/index.js",
60
60
  "writes": [
@@ -11,7 +11,7 @@ export function Quiz({ document, storage, viewId }: ActionContext) {
11
11
  useEffect(() => {
12
12
  void storage.list().then((records) => {
13
13
  const value = records.find(
14
- (record) => record.key === key && record.conceptId === undefined,
14
+ (record) => record.key === key && record.scope === undefined,
15
15
  )?.value
16
16
  setStep(typeof value === 'number' ? value : 0)
17
17
  })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nesso-how/plugin",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Types, validation, and asynchronous clients for isolated Nesso plugins",
5
5
  "license": "MIT",
6
6
  "repository": {