@notegen/plugin-api 0.1.0 → 0.1.2

package/README.md

@@ -100,3 +100,93 @@ to the old data branch. Reinstalling an existing fingerprint reuses its branch.
 This does not roll back note writes, attachments, settings or remote effects.
 Use explicit data schema versions and idempotent migration steps. The test host
 does not simulate package installation or versioned storage.
+
+## Active document paths
+
+`editor.getActiveEditor()` and active-editor events may include `path`, the workspace-relative Markdown path. It is protected by `editor.read` and never contains an absolute filesystem path. Older hosts and non-workspace documents may omit it; plugins must handle absence without treating the opaque document ID as a path.
+
+## Opening existing notes only
+
+Updated hosts accept `notes.openOrCreate({ ..., open: true, create: false })`. This requires `notes.open` only and fails for missing files without creating them. Omitted `create` preserves the original behavior and requires `notes.create`. Open-only mode requires an updated host; older hosts do not implement this option.
+
+## Navigation lists (updated local hosts)
+
+The `navigation-list` UI block provides a compact host-rendered sortable list. Each item has a unique stable ID and a label. Item open/remove commands receive `{ generation, itemId }`; the add command receives `{ generation }`. Reorder receives `{ generation, itemIds }` with the complete new order. Plugins must check generation, reject duplicate/missing/foreign IDs, persist the new order, and publish a new document. Hosts validate all referenced commands and limit lists to 100 items. Older hosts reject this block type.
+
+## API 0.1.1: editor menus and composable UI
+
+New contributions require `apiVersion: "^0.1.1"`. The corresponding NoteGen host
+changes must be present; publishing this SDK does not update an installed app.
+The older `^0.1.0` plugin contract remains accepted by the new host.
+
+Menu locations now include `editor/slash`, `editor/context`, `editor/selection`
+(the text-selection floating toolbar), `editor/toolbar` (visual editor footer),
+`tab/context`, `file/context`, and `mobile/writing/overflow`.
+`editor/context` uses Alt/Option + right-click to preserve the native clipboard menu.
+The tab menu also retains file-menu contributions, deduplicated by command ID.
+
+Each menu accepts `icon`, `group`, `order`, `when`, and `enableWhen`. Groups sort
+lexically, then entries sort by ascending order. A menu icon overrides the command
+icon. Commands accept up to 20 `keywords` for slash-menu and palette search.
+Selection/toolbar menus display three direct buttons and put additional commands
+in an accessible overflow menu. Existing built-in editing commands remain intact.
+
+```json
+{
+  "location": "editor/selection",
+  "command": "com.example.notes.extract",
+  "icon": "files",
+  "group": "notes",
+  "order": 10,
+  "when": "editor == markdown && selection",
+  "enableWhen": "!readOnly && !codeBlock"
+}
+```
+
+Conditions support boolean `selection`, `readOnly`, `codeBlock`; string `editor`,
+`resourceKind` (`file`, `folder`, `root`), and `resourceExt` (e.g. `md`). Use `!`,
+`==`, `!=`, `&&`, `||`; `&&` binds more tightly than `||`. Parentheses, arbitrary
+properties and executable JavaScript are rejected. Unknown/missing context fails
+closed, including negated conditions. Conditions control UI only, never permission
+grants. Read selection/text through `editor.read`; keep the captured editor ID and
+revision when applying an edit through `editor.write`. Menu arguments do not leak
+selected text or circumvent permissions.
+
+Composable blocks:
+
+- `layout`: row/column, small/medium/large gap, nested `blocks`.
+- `section`: title, nested blocks, optional collapse and initial open state.
+- `tabs`: stable ID, accessible label, tabs with ID/label/blocks.
+- `toolbar`: labeled actions with optional icon, iconOnly, variant and confirmation.
+- `item-list`: stable IDs, generation, click action, optional checkbox action,
+  drag and keyboard reordering, context actions and a touch-accessible overflow.
+  Items may supply `metadata` (up to 1024 characters) for a separate information
+  line below the description, such as a workspace-relative file path.
+- `markdown`: formatted text with raw HTML, links and image loading disabled.
+- `badge`, `empty`, `loading`: standard theme-aware feedback.
+- Form fields additionally support `search`, ISO `date`, and searchable
+  `note-picker`. Supply note choices as `{label,value}` through existing scoped
+  `notes.list` permissions. The picker does not enumerate files or grant access.
+
+Nested forms retain their values when a surrounding section/tab rerenders. IDs
+must be unique per block type across the whole document. Limits: 6 nesting levels,
+200 total blocks, 50 blocks per container, 100 list items, 20 actions, 12 tabs,
+and the existing 128 KiB document limit. Command ownership is validated recursively.
+
+List open/toggle/action commands receive `{generation,itemId}`; toggle adds
+`checked`. Context actions add `actionId` and optionally nested `argument`.
+Reorder commands receive `{generation,itemIds}` with the complete requested order.
+The plugin must reject stale generations and invalid IDs, persist successful
+changes, then publish updated content. The host never mutates plugin storage.
+
+An action may provide `confirmation: {title,description?,confirmLabel,cancelLabel}`.
+Its command runs only after confirmation. Legacy `navigation-list` remains a
+compatibility adapter; new plugins should compose toolbar and item-list blocks.
+
+Supported symbolic icons include bookmark, calendar-days, file-text, files, folder,
+folder-open, layout-template, list-checks, list-todo, link, search, plus, minus,
+trash-2, pencil, copy, check, x, star, pin, tag, settings, more-horizontal, arrow-up,
+arrow-down, download, upload, external-link, list, table-2, columns-3, clock,
+book-open, code, sparkles, shuffle, refresh-cw, chart-no-axes-combined, file-input,
+and flask-conical. Unknown icons fall back to a puzzle icon. Raw SVG/HTML and
+external icon URLs are not accepted as executable markup.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** The public API version implemented by this release of NoteGen. */
-export declare const PLUGIN_API_VERSION: "0.1.0";
+export declare const PLUGIN_API_VERSION: "0.1.1";
 export type PluginPlatform = 'desktop' | 'ios' | 'android';
 export type PluginActivationEvent = `onCommand:${string}` | 'onEditor:markdown' | 'onWorkspace:open' | 'onNotes:change';
 export type PluginPermissionScope = 'active-editor' | 'workspace-file' | 'workspace-files' | 'workspace-folder' | 'network-origins';
@@ -28,6 +28,7 @@ export interface PluginCommandContribution {
     title: string;
     description?: string;
     icon?: string;
+    keywords?: readonly string[];
     suggestedShortcut?: string;
 }
 export interface PluginSettingOption {
@@ -91,12 +92,15 @@ export interface PluginViewContribution {
     location: 'left-sidebar' | 'right-sidebar' | 'editor-tab';
     icon?: string;
 }
-export type PluginMenuLocation = 'editor/slash' | 'editor/context' | 'file/context' | 'mobile/writing/overflow';
+export type PluginMenuLocation = 'editor/slash' | 'editor/context' | 'editor/selection' | 'editor/toolbar' | 'tab/context' | 'file/context' | 'mobile/writing/overflow';
 export interface PluginMenuContribution {
     location: PluginMenuLocation;
     command: string;
     when?: string;
     group?: string;
+    order?: number;
+    icon?: string;
+    enableWhen?: string;
 }
 export interface PluginContributions {
     commands?: readonly PluginCommandContribution[];
@@ -156,6 +160,8 @@ export interface ResolvedDay {
     localDateTime: string;
 }
 export interface NoteSnapshot {
+    /** Saved file modification time in Unix milliseconds, when supported by the host/filesystem. */
+    modifiedAt?: number;
     id: string;
     path: string;
     revision: number;
@@ -165,6 +171,8 @@ export interface ReadNoteOptions {
     path: string;
 }
 export interface OpenOrCreateNoteOptions {
+    /** Defaults to true. Set false with open: true to open an existing file using only notes.open. Missing files fail. */
+    create?: boolean;
     workspaceId: string;
     path: string;
     initialContent: string;
@@ -239,6 +247,8 @@ export interface NoteChangeEvent {
     previousPath?: string;
 }
 export interface ActiveEditorContext {
+    /** Workspace-relative Markdown path, when available. Never an absolute path. Requires editor.read. */
+    path?: string;
     windowId: string;
     editorId: string;
     documentId: string;
@@ -324,7 +334,7 @@ export type PluginFormField = {
     disabled?: boolean;
     visibleWhen?: PluginFormCondition;
 } & ({
-    type: 'text' | 'textarea';
+    type: 'text' | 'textarea' | 'search' | 'date';
     value?: string;
     placeholder?: string;
     maxLength?: number;
@@ -334,7 +344,7 @@ export type PluginFormField = {
     min?: number;
     max?: number;
 } | {
-    type: 'select';
+    type: 'select' | 'note-picker';
     value?: string;
     options: readonly {
         label: string;
@@ -385,7 +395,27 @@ export type PluginTableCell = string | {
     argument?: PluginCommandArgument;
     disabled?: boolean;
 };
-export type PluginUiBlock = PluginFormBlock | {
+/** Host-rendered navigation list. Commands receive { generation, itemId? };
+ * reorder receives { generation, itemIds } containing the complete new order. */
+export interface PluginNavigationListBlock {
+    type: 'navigation-list';
+    id: string;
+    generation: string;
+    label: string;
+    emptyText: string;
+    addLabel: string;
+    removeLabel: string;
+    reorderLabel: string;
+    items: readonly {
+        id: string;
+        label: string;
+    }[];
+    openCommand: string;
+    addCommand: string;
+    removeCommand: string;
+    reorderCommand: string;
+}
+export type PluginUiBlock = PluginExtendedUiBlock | PluginNavigationListBlock | PluginFormBlock | {
     type: 'separator';
 } | {
     type: 'callout';
@@ -615,3 +645,101 @@ export declare class PluginError extends Error {
 export declare function isPluginError(value: unknown): value is PluginError;
 /** Preserve literal manifest values while checking the v1 shape at compile time. */
 export declare function definePluginManifest<const Manifest extends PluginManifestV1>(manifest: Manifest): Manifest;
+/** Menu conditions are data, never JavaScript. && binds more tightly than ||.
+ * Supported atoms: boolean keys / !key, or key == value / key != value.
+ * No parentheses, property access, or executable expressions are accepted. */
+export interface PluginMenuContext {
+    editor?: 'markdown';
+    selection?: boolean;
+    readOnly?: boolean;
+    codeBlock?: boolean;
+    resourceKind?: 'file' | 'folder' | 'root';
+    resourceExt?: string;
+}
+export declare function isValidPluginMenuCondition(condition: string): boolean;
+export declare function matchesPluginMenuCondition(condition: string | undefined, context: PluginMenuContext): boolean;
+export interface PluginActionConfirmation {
+    title: string;
+    description?: string;
+    confirmLabel: string;
+    cancelLabel: string;
+}
+export interface PluginUiAction {
+    id: string;
+    label: string;
+    command: string;
+    argument?: PluginCommandArgument;
+    icon?: string;
+    iconOnly?: boolean;
+    confirmation?: PluginActionConfirmation;
+    disabled?: boolean;
+    variant?: 'default' | 'secondary' | 'destructive' | 'ghost' | 'outline';
+}
+export interface PluginItemListBlock {
+    type: 'item-list';
+    id: string;
+    generation: string;
+    label: string;
+    emptyText: string;
+    items: readonly {
+        id: string;
+        label: string;
+        description?: string;
+        metadata?: string;
+        icon?: string;
+        checked?: boolean;
+        disabled?: boolean;
+    }[];
+    openCommand?: string;
+    toggleCommand?: string;
+    reorderCommand?: string;
+    reorderLabel?: string;
+    actions?: readonly PluginUiAction[];
+}
+export type PluginExtendedUiBlock = PluginItemListBlock | {
+    type: 'layout';
+    id: string;
+    direction?: 'row' | 'column';
+    gap?: 'small' | 'medium' | 'large';
+    blocks: readonly PluginUiBlock[];
+} | {
+    type: 'section';
+    id: string;
+    title: string;
+    collapsible?: boolean;
+    defaultOpen?: boolean;
+    blocks: readonly PluginUiBlock[];
+} | {
+    type: 'tabs';
+    id: string;
+    label: string;
+    tabs: readonly {
+        id: string;
+        label: string;
+        blocks: readonly PluginUiBlock[];
+    }[];
+} | {
+    type: 'toolbar';
+    id: string;
+    label: string;
+    actions: readonly PluginUiAction[];
+} | {
+    type: 'markdown';
+    text: string;
+} | {
+    type: 'badge';
+    text: string;
+    tone?: 'default' | 'secondary' | 'outline' | 'destructive';
+} | {
+    type: 'empty';
+    title: string;
+    description?: string;
+    icon?: string;
+} | {
+    type: 'loading';
+    label: string;
+};
+/** Walk a UI document with shared depth/count limits, including nested forms. */
+export declare function flattenPluginUiBlocks(blocks: readonly PluginUiBlock[]): PluginUiBlock[];
+/** Shared validation used by NoteGen and the SDK's in-memory host. */
+export declare function parsePluginUiExtension(value: unknown, parseChildren: (value: unknown) => readonly PluginUiBlock[]): PluginExtendedUiBlock | undefined;

package/dist/index.js

@@ -1,5 +1,5 @@
 /** The public API version implemented by this release of NoteGen. */
-export const PLUGIN_API_VERSION = '0.1.0';
+export const PLUGIN_API_VERSION = '0.1.1';
 export const PLUGIN_ERROR_CODES = Object.freeze([
     'PermissionDenied',
     'AlreadyRegistered',
@@ -45,3 +45,150 @@ export function isPluginError(value) {
 export function definePluginManifest(manifest) {
     return manifest;
 }
+const menuBooleanKeys = new Set(['selection', 'readOnly', 'codeBlock']);
+const menuStringKeys = new Set(['editor', 'resourceKind', 'resourceExt']);
+function parseMenuAtom(atom) {
+    const boolean = /^(!)?(selection|readOnly|codeBlock)$/.exec(atom.trim());
+    if (boolean)
+        return { key: boolean[2], operator: '==', value: !boolean[1] };
+    const comparison = /^(\w+)\s*(==|!=)\s*([\w.-]+)$/.exec(atom.trim());
+    if (!comparison)
+        return null;
+    const [, key, operator, value] = comparison;
+    if (menuBooleanKeys.has(key) && (value === 'true' || value === 'false'))
+        return { key: key, operator, value: value === 'true' };
+    if (menuStringKeys.has(key))
+        return { key: key, operator, value };
+    return null;
+}
+export function isValidPluginMenuCondition(condition) {
+    return condition.length > 0 && condition.length <= 240
+        && condition.split('||').every(group => group.split('&&').every(atom => parseMenuAtom(atom) !== null));
+}
+export function matchesPluginMenuCondition(condition, context) {
+    if (condition === undefined)
+        return true;
+    if (!isValidPluginMenuCondition(condition))
+        return false;
+    return condition.split('||').some(group => group.split('&&').every(atom => {
+        const parsed = parseMenuAtom(atom);
+        const actual = context[parsed.key];
+        if (actual === undefined)
+            return false;
+        return parsed.operator === '==' ? actual === parsed.value : actual !== parsed.value;
+    }));
+}
+/** Walk a UI document with shared depth/count limits, including nested forms. */
+export function flattenPluginUiBlocks(blocks) {
+    const result = [];
+    function visit(items, depth) {
+        if (depth > 6)
+            throw new PluginError('QuotaExceeded', 'Plugin UI nesting exceeds 6 levels');
+        for (const block of items) {
+            result.push(block);
+            if (result.length > 200)
+                throw new PluginError('QuotaExceeded', 'Plugin UI exceeds 200 blocks');
+            if (block.type === 'layout' || block.type === 'section')
+                visit(block.blocks, depth + 1);
+            if (block.type === 'tabs')
+                for (const tab of block.tabs)
+                    visit(tab.blocks, depth + 1);
+        }
+    }
+    visit(blocks, 0);
+    const ids = new Set();
+    for (const block of result) {
+        if ('id' in block && block.id !== undefined) {
+            const key = `${block.type}:${block.id}`;
+            if (ids.has(key))
+                throw new PluginError('InvalidPath', 'Duplicate UI block ID');
+            ids.add(key);
+        }
+    }
+    return result;
+}
+/** Shared validation used by NoteGen and the SDK's in-memory host. */
+export function parsePluginUiExtension(value, parseChildren) {
+    const parsed = parsePluginUiExtensionValue(value, parseChildren);
+    // Validation constructs optional fields explicitly. Omit absent fields from
+    // the normalized result so snapshots remain valid JSON on both host paths.
+    // Raw input and command arguments are validated before this normalization.
+    return parsed === undefined ? undefined : JSON.parse(JSON.stringify(parsed));
+}
+function parsePluginUiExtensionValue(value, parseChildren) {
+    const fail = () => { throw new PluginError('InvalidPath', 'Malformed extended plugin UI block'); };
+    const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : fail();
+    const text = (value, max = 500, min = 1) => typeof value === 'string' && value.length >= min && value.length <= max ? value : fail();
+    const boolean = (value) => value === undefined || typeof value === 'boolean' ? value : fail();
+    const choice = (value, options) => value === undefined ? undefined : options.includes(value) ? value : fail();
+    const keys = (value, allowed) => { if (Object.keys(value).some(key => !allowed.includes(key)))
+        fail(); };
+    const array = (value, max) => Array.isArray(value) && value.length <= max ? value : fail();
+    const unique = (items) => { if (new Set(items.map(item => item.id)).size !== items.length)
+        fail(); };
+    const optionalText = (value, max = 500) => value === undefined ? undefined : text(value, max);
+    const action = (value) => {
+        const v = record(value);
+        keys(v, ['id', 'label', 'command', 'argument', 'icon', 'iconOnly', 'confirmation', 'disabled', 'variant']);
+        // Arguments cross the existing JSON-only RPC boundary; reject non-JSON values here too.
+        const json = (value, depth = 0) => depth <= 12 && (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value) || Array.isArray(value) && value.every(item => json(item, depth + 1)) || typeof value === 'object' && value !== null && Object.values(value).every(item => json(item, depth + 1)));
+        if (v.argument !== undefined && !json(v.argument))
+            fail();
+        let confirmation;
+        if (v.confirmation !== undefined) {
+            const c = record(v.confirmation);
+            keys(c, ['title', 'description', 'confirmLabel', 'cancelLabel']);
+            confirmation = { title: text(c.title, 240), description: optionalText(c.description, 2000), confirmLabel: text(c.confirmLabel, 160), cancelLabel: text(c.cancelLabel, 160) };
+        }
+        if (v.iconOnly === true && !v.icon)
+            fail();
+        return { iconOnly: boolean(v.iconOnly), confirmation, id: text(v.id, 160), label: text(v.label, 160), command: text(v.command, 220), argument: v.argument, icon: optionalText(v.icon, 80), disabled: boolean(v.disabled), variant: choice(v.variant, ['default', 'secondary', 'destructive', 'ghost', 'outline']) };
+    };
+    const v = record(value);
+    switch (v.type) {
+        case 'layout':
+            keys(v, ['type', 'id', 'direction', 'gap', 'blocks']);
+            return { type: 'layout', id: text(v.id, 160), direction: choice(v.direction, ['row', 'column']), gap: choice(v.gap, ['small', 'medium', 'large']), blocks: parseChildren(v.blocks) };
+        case 'section':
+            keys(v, ['type', 'id', 'title', 'collapsible', 'defaultOpen', 'blocks']);
+            return { type: 'section', id: text(v.id, 160), title: text(v.title, 240), collapsible: boolean(v.collapsible), defaultOpen: boolean(v.defaultOpen), blocks: parseChildren(v.blocks) };
+        case 'tabs': {
+            keys(v, ['type', 'id', 'label', 'tabs']);
+            const tabs = array(v.tabs, 12).map(value => { const tab = record(value); keys(tab, ['id', 'label', 'blocks']); return { id: text(tab.id, 160), label: text(tab.label, 160), blocks: parseChildren(tab.blocks) }; });
+            if (!tabs.length)
+                fail();
+            unique(tabs);
+            return { type: 'tabs', id: text(v.id, 160), label: text(v.label, 160), tabs };
+        }
+        case 'toolbar': {
+            keys(v, ['type', 'id', 'label', 'actions']);
+            const actions = array(v.actions, 20).map(action);
+            unique(actions);
+            return { type: 'toolbar', id: text(v.id, 160), label: text(v.label, 160), actions };
+        }
+        case 'item-list': {
+            keys(v, ['type', 'id', 'generation', 'label', 'emptyText', 'items', 'openCommand', 'toggleCommand', 'reorderCommand', 'reorderLabel', 'actions']);
+            const items = array(v.items, 100).map(value => { const item = record(value); keys(item, ['id', 'label', 'description', 'metadata', 'icon', 'checked', 'disabled']); return { id: text(item.id, 1024), label: text(item.label), description: optionalText(item.description, 2000), metadata: optionalText(item.metadata, 1024), icon: optionalText(item.icon, 80), checked: boolean(item.checked), disabled: boolean(item.disabled) }; });
+            unique(items);
+            const actions = v.actions === undefined ? undefined : array(v.actions, 20).map(action);
+            if (actions)
+                unique(actions);
+            if (v.reorderCommand !== undefined && v.reorderLabel === undefined)
+                fail();
+            return { type: 'item-list', id: text(v.id, 160), generation: text(v.generation, 160), label: text(v.label, 160), emptyText: text(v.emptyText, 500, 0), items, actions, openCommand: optionalText(v.openCommand, 220), toggleCommand: optionalText(v.toggleCommand, 220), reorderCommand: optionalText(v.reorderCommand, 220), reorderLabel: optionalText(v.reorderLabel, 160) };
+        }
+        case 'markdown':
+            keys(v, ['type', 'text']);
+            return { type: 'markdown', text: text(v.text, 20000, 0) };
+        case 'badge':
+            keys(v, ['type', 'text', 'tone']);
+            return { type: 'badge', text: text(v.text, 160), tone: choice(v.tone, ['default', 'secondary', 'outline', 'destructive']) };
+        case 'empty':
+            keys(v, ['type', 'title', 'description', 'icon']);
+            return { type: 'empty', title: text(v.title, 240), description: optionalText(v.description, 2000), icon: optionalText(v.icon, 80) };
+        case 'loading':
+            keys(v, ['type', 'label']);
+            return { type: 'loading', label: text(v.label, 160) };
+        default: return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notegen/plugin-api",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Public TypeScript contract for NoteGen plugins.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "url": "https://github.com/codexu/note-gen-plugin-sdk/issues"
   },
   "notegen": {
-    "pluginApiVersion": "0.1.0"
+    "pluginApiVersion": "0.1.1"
   },
   "devDependencies": {
     "typescript": "^5.8.3"

package/schema/plugin-manifest-v1.schema.json

@@ -186,6 +186,7 @@
         "title": { "$ref": "#/$defs/localizedText" },
         "description": { "$ref": "#/$defs/localizedText" },
         "icon": { "type": "string", "pattern": "^[A-Za-z0-9-]+$", "maxLength": 80 },
+        "keywords": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 80 } },
         "suggestedShortcut": { "type": "string", "minLength": 1, "maxLength": 80 }
       }
     },
@@ -277,10 +278,13 @@
       "additionalProperties": false,
       "required": ["location", "command"],
       "properties": {
-        "location": { "enum": ["editor/slash", "editor/context", "file/context", "mobile/writing/overflow"] },
+        "location": { "enum": ["editor/slash", "editor/context", "editor/selection", "editor/toolbar", "tab/context", "file/context", "mobile/writing/overflow"] },
         "command": { "$ref": "#/$defs/namespacedId" },
         "when": { "type": "string", "minLength": 1, "maxLength": 240 },
-        "group": { "type": "string", "minLength": 1, "maxLength": 80 }
+        "group": { "type": "string", "minLength": 1, "maxLength": 80 },
+        "enableWhen": { "type": "string", "minLength": 1, "maxLength": 240 },
+        "order": { "type": "integer", "minimum": -10000, "maximum": 10000 },
+        "icon": { "type": "string", "pattern": "^[A-Za-z0-9-]+$", "maxLength": 80 }
       }
     },
     "view": {