@notegen/plugin-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NoteGen contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# `@notegen/plugin-api`
+
+UI lifecycle: forms retain values by field ID until removed, closed, or explicitly
+reset with a new `resetKey`. `ui.openDialog(options)` returns `{ id }`;
+`ui.closeDialog(id)` only closes that instance. To replace an existing dialog,
+pass its ID as `replaceId`. Another plugin's dialog cannot be replaced.
+`ui.onDidCloseDialog` reports `{ id, reason }`. Form commands inside dialogs
+also receive `dialogId` alongside `formId` and `values`; capture it before
+awaiting work so a stale submission cannot close a newer dialog.
+
+The public TypeScript contract for NoteGen plugins.
+
+```bash
+pnpm add -D @notegen/plugin-api
+```
+
+Use type-only imports whenever possible:
+
+```ts
+import type { PluginActivate } from '@notegen/plugin-api'
+
+export const activate: PluginActivate = async (context) => {
+  context.commands.handle('com.example.hello.open', async () => {
+    await context.ui.showNotice('Hello from NoteGen')
+  })
+}
+```
+
+The package contains manifest, permission, contribution, lifecycle, host-context,
+and stable error types. It has no runtime dependencies and does not require DOM
+types.
+
+Values that cross the runtime boundary use `PluginJsonValue`. Command arguments
+and results, storage values, and declarative UI action arguments therefore accept
+only finite JSON-compatible data. Convert class instances such as `Date`, maps,
+sets, and custom errors to plain objects before passing them to the host.
+`undefined` is allowed only at the outer command boundary to mean “no argument”
+or “no result,” and as the missing-key result of storage `get`; it cannot appear
+inside a stored, returned, or action-argument JSON value.
+
+The package also publishes an editor-oriented manifest schema at
+`@notegen/plugin-api/plugin-manifest-v1.schema.json`. The schema catches shape
+errors while editing; `notegen-plugin validate` remains authoritative for
+namespace ownership, localization files, API/app compatibility, and packaged
+file checks.
+
+API 0.1.0 covers commands, settings, storage, calendar resolution, active-editor
+snapshots and revision-checked edits, note listing/read/write/move/delete and
+change events, declarative sidebars/dialogs, and text-only requests to exact
+user-approved HTTPS origins. Every sensitive operation is permission scoped.
+
+API 0.1.0 adds declarative forms (text, textarea, number, select, checkbox), tables,
+trees, editor-area plugin tabs, view visibility events and close/focus methods.
+Forms submit `{ formId, values }` to a declared command; its result may contain
+`fieldErrors` and `message`. The UI remains host-rendered without DOM access.
+`editor.applyEdits` and `editor.setSelection` use UTF-16 Markdown offsets and
+currently require source mode. Batch edits cannot overlap and form one undo step.
+`notes.search` searches saved Markdown within both list and read grants (up to
+200 files, 16 MiB scanned, 100 matching lines); inspect `truncated`.
+`attachments.read/create` require separate grants, accept PNG/JPEG/GIF/WebP,
+PDF/TXT/CSV, and transport standard Base64 up to 1 MiB decoded. Creation never
+overwrites an existing file. There is no attachment delete, arbitrary-file API,
+or automatic preview/open operation.
+
+File mutations (`notes.write`, `notes.move`, and `notes.delete`) run only from
+the main window and require every affected note to be closed in all tabs,
+panes, and separate editor windows. Otherwise they return `EditorBusy`.
+Use `editor.applyEdit` for the active document. The host drains pending saves
+before checking a file's `expectedRevision`; re-read after a stale-revision
+error. If a mutation error includes `details.committed: true`, the disk change
+completed and only its UI reconciliation failed. Read the file state before
+retrying.
+
+The current community runtime loads one self-contained ESM entry. Type-only
+imports disappear during compilation. Any value import or other dependency must
+be bundled into that entry by the authoring build.
+
+See the [NoteGen documentation](https://notegen.top) for the complete plugin
+development guide.
+
+## Local diagnostics and folder permission bindings
+
+`context.log.info/warning/error(message)` writes local diagnostics. The QuickJS
+host truncates messages to 1,000 characters and drops entries beyond 50 per
+10 seconds. Use `error.stack` explicitly when a stack trace helps; do not log
+credentials or note contents. The developer panel can export its filtered log.
+The in-process test host records these calls but does not emulate the quota.
+
+One `string` setting with `scope: "workspace"` may declare
+`permissionPaths: ["notes.create", "notes.open"]`. Each listed permission must
+be declared, required, unique and use `workspace-folder` scope (at most 20).
+The permission dialog uses the setting's fixed folder prefix, lets the user
+choose another folder, and preserves `{{...}}` date subfolders. This is a UI
+suggestion only: permissions still require explicit user approval. Plugins
+without this declaration use the normal per-permission inputs.
+
+Production KV storage now follows the installed package content fingerprint.
+A new package starts with a copy of the current package's data; rollback returns
+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.

package/dist/index.d.ts

@@ -0,0 +1,617 @@
+/** The public API version implemented by this release of NoteGen. */
+export declare const PLUGIN_API_VERSION: "0.1.0";
+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';
+export interface PluginPermissionDeclaration<Scope extends PluginPermissionScope = PluginPermissionScope> {
+    scope: Scope;
+    optional?: boolean;
+    description?: string;
+}
+export interface PluginPermissionDeclarations {
+    'editor.read'?: PluginPermissionDeclaration<'active-editor'>;
+    'editor.write'?: PluginPermissionDeclaration<'active-editor'>;
+    'notes.read'?: PluginPermissionDeclaration<'workspace-file' | 'workspace-files' | 'workspace-folder'>;
+    'notes.create'?: PluginPermissionDeclaration<'workspace-folder'>;
+    'notes.open'?: PluginPermissionDeclaration<'workspace-folder'>;
+    'notes.list'?: PluginPermissionDeclaration<'workspace-folder'>;
+    'notes.write'?: PluginPermissionDeclaration<'workspace-file' | 'workspace-files' | 'workspace-folder'>;
+    'notes.delete'?: PluginPermissionDeclaration<'workspace-file' | 'workspace-files' | 'workspace-folder'>;
+    'notes.move'?: PluginPermissionDeclaration<'workspace-folder'>;
+    'network.fetch'?: PluginPermissionDeclaration<'network-origins'>;
+    'attachments.read'?: PluginPermissionDeclaration<'workspace-file' | 'workspace-files' | 'workspace-folder'>;
+    'attachments.create'?: PluginPermissionDeclaration<'workspace-folder'>;
+}
+export type PluginPermissionName = keyof PluginPermissionDeclarations;
+export interface PluginCommandContribution {
+    id: string;
+    title: string;
+    description?: string;
+    icon?: string;
+    suggestedShortcut?: string;
+}
+export interface PluginSettingOption {
+    readonly label: string;
+    readonly value: string;
+}
+export type PluginSettingContribution = {
+    key: string;
+    type: 'boolean';
+    scope: 'device' | 'workspace';
+    title: string;
+    description?: string;
+    default: boolean;
+} | {
+    key: string;
+    type: 'string';
+    /** One workspace folder template may bind required workspace-folder grants. */
+    permissionPaths?: readonly PluginPermissionName[];
+    scope: 'device' | 'workspace';
+    title: string;
+    description?: string;
+    default: string;
+    placeholder?: string;
+    /** Maximum UTF-8 byte length accepted by the host. */
+    maxLength?: number;
+} | {
+    key: string;
+    type: 'number';
+    scope: 'device' | 'workspace';
+    title: string;
+    description?: string;
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+} | {
+    key: string;
+    type: 'select';
+    scope: 'device' | 'workspace';
+    title: string;
+    description?: string;
+    default: string;
+    options: readonly PluginSettingOption[];
+} | {
+    key: string;
+    type: 'workspace-file' | 'workspace-folder';
+    scope: 'workspace';
+    title: string;
+    description?: string;
+    default: string;
+};
+export interface PluginStatusBarContribution {
+    id: string;
+    alignment: 'left' | 'right';
+    priority?: number;
+    command?: string;
+}
+export interface PluginViewContribution {
+    id: string;
+    title: string;
+    location: 'left-sidebar' | 'right-sidebar' | 'editor-tab';
+    icon?: string;
+}
+export type PluginMenuLocation = 'editor/slash' | 'editor/context' | 'file/context' | 'mobile/writing/overflow';
+export interface PluginMenuContribution {
+    location: PluginMenuLocation;
+    command: string;
+    when?: string;
+    group?: string;
+}
+export interface PluginContributions {
+    commands?: readonly PluginCommandContribution[];
+    settings?: readonly PluginSettingContribution[];
+    statusBar?: readonly PluginStatusBarContribution[];
+    menus?: readonly PluginMenuContribution[];
+    views?: readonly PluginViewContribution[];
+}
+export interface PluginAuthor {
+    name: string;
+    url?: string;
+}
+export interface PluginManifestV1 {
+    manifestVersion: 1;
+    id: string;
+    name: string;
+    description?: string;
+    version: string;
+    apiVersion: string;
+    minAppVersion: string;
+    platforms: readonly PluginPlatform[];
+    entry: string;
+    activationEvents: readonly PluginActivationEvent[];
+    permissions: Readonly<PluginPermissionDeclarations>;
+    contributes: PluginContributions;
+    defaultLocale?: string;
+    locales?: Readonly<Record<string, string>>;
+    author?: PluginAuthor;
+    repository?: string;
+    license?: string;
+}
+export type PluginSettingValue = string | number | boolean;
+/**
+ * Values that can cross the NoteGen plugin boundary without losing meaning.
+ *
+ * Plugin commands, storage, and declarative UI are transported as JSON. Class
+ * instances, functions, symbols, bigint values, `undefined` inside containers,
+ * and cyclic objects are therefore intentionally excluded from this type.
+ */
+export type PluginJsonValue = null | boolean | number | string | readonly PluginJsonValue[] | {
+    readonly [key: string]: PluginJsonValue;
+};
+export type PluginCommandArgument = PluginJsonValue | undefined;
+export type PluginCommandResult = PluginJsonValue | void;
+export interface WorkspaceInfo {
+    id: string;
+    name: string;
+}
+export interface ResolveDayOptions {
+    timeZone: 'system' | string;
+    dayStartsAt: string;
+}
+export interface ResolvedDay {
+    instant: string;
+    logicalDate: string;
+    timeZone: string;
+    localDateTime: string;
+}
+export interface NoteSnapshot {
+    id: string;
+    path: string;
+    revision: number;
+    content: string;
+}
+export interface ReadNoteOptions {
+    path: string;
+}
+export interface OpenOrCreateNoteOptions {
+    workspaceId: string;
+    path: string;
+    initialContent: string;
+    conflict: 'open-existing';
+    open: boolean;
+    idempotencyKey: string;
+}
+export interface OpenOrCreateResult {
+    status: 'created' | 'opened-existing';
+    workspaceId: string;
+    path: string;
+    opened: boolean;
+}
+export interface NoteEntry {
+    path: string;
+    name: string;
+    size: number;
+}
+export interface ListNotesOptions {
+    folder?: string;
+    recursive?: boolean;
+    limit?: number;
+    /** Opaque continuation returned by notes.list; keep folder/recursive unchanged. */
+    cursor?: string;
+}
+export interface ListNotesResult {
+    entries: readonly NoteEntry[];
+    truncated: boolean;
+    nextCursor?: string;
+}
+export interface SearchNotesOptions {
+    query: string;
+    folder?: string;
+    caseSensitive?: boolean;
+    limit?: number;
+}
+export interface SearchNotesResult {
+    matches: readonly {
+        path: string;
+        revision: number;
+        line: number;
+        preview: string;
+    }[];
+    /** True when the scan or result quota was reached. Searches saved Markdown only. */
+    truncated: boolean;
+}
+export interface WriteNoteOptions {
+    path: string;
+    content: string;
+    /** Required when the target exists, including with create: true. Read before writing. */
+    expectedRevision?: number;
+    create?: boolean;
+}
+export interface WriteNoteResult {
+    path: string;
+    revision: number;
+    created: boolean;
+}
+export interface MoveNoteOptions {
+    from: string;
+    to: string;
+    overwrite?: false;
+}
+export interface DeleteNoteOptions {
+    path: string;
+    /** Desktop moves to system trash; mobile deletion is unavailable. */
+    expectedRevision: number;
+}
+export interface NoteChangeEvent {
+    type: 'created' | 'changed' | 'deleted' | 'moved';
+    path: string;
+    previousPath?: string;
+}
+export interface ActiveEditorContext {
+    windowId: string;
+    editorId: string;
+    documentId: string;
+    kind: 'markdown';
+    mode: 'visual' | 'source' | 'sectioned';
+    revision: number;
+    composing: boolean;
+    size: {
+        utf16Length: number;
+        bytes: number;
+        lines: number;
+    };
+}
+export interface EditorSelection {
+    editorId: string;
+    revision: number;
+    from?: number;
+    to?: number;
+    offsetsAvailable: boolean;
+    empty: boolean;
+    text: string;
+}
+export interface EditorTextSnapshot {
+    editorId: string;
+    documentId: string;
+    revision: number;
+    format: 'markdown';
+    text: string;
+}
+export interface GetEditorTextSnapshotOptions {
+    editorId: string;
+    expectedRevision: number;
+    format: 'markdown';
+}
+export interface EditorActiveChangeEvent {
+    previous: ActiveEditorContext | null;
+    current: ActiveEditorContext | null;
+}
+export interface EditorContentChangeEvent {
+    editorId: string;
+    documentId: string;
+    revision: number;
+    composing: boolean;
+    size: ActiveEditorContext['size'];
+}
+export interface ApplyEditorEditOptions {
+    editorId: string;
+    expectedRevision: number;
+    text: string;
+    target: 'cursor' | 'selection';
+}
+export interface ApplyEditorEditResult {
+    applied: true;
+    insertedLength: number;
+}
+/** All ranges use UTF-16 offsets into the Markdown snapshot at expectedRevision. */
+export interface EditorRangeEdit {
+    from: number;
+    to: number;
+    text: string;
+}
+export interface ApplyEditorEditsOptions {
+    editorId: string;
+    expectedRevision: number;
+    edits: readonly EditorRangeEdit[];
+}
+export interface SetEditorSelectionOptions {
+    editorId: string;
+    expectedRevision: number;
+    from: number;
+    to: number;
+}
+export type PluginFormValue = string | number | boolean;
+export interface PluginFormCondition {
+    field: string;
+    equals: PluginFormValue;
+}
+export type PluginFormField = {
+    id: string;
+    label: string;
+    description?: string;
+    required?: boolean;
+    disabled?: boolean;
+    visibleWhen?: PluginFormCondition;
+} & ({
+    type: 'text' | 'textarea';
+    value?: string;
+    placeholder?: string;
+    maxLength?: number;
+} | {
+    type: 'number';
+    value?: number;
+    min?: number;
+    max?: number;
+} | {
+    type: 'select';
+    value?: string;
+    options: readonly {
+        label: string;
+        value: string;
+    }[];
+} | {
+    type: 'checkbox';
+    value?: boolean;
+});
+export interface PluginFormBlock {
+    type: 'form';
+    id: string;
+    /** Change this token to explicitly reset values and feedback. */
+    resetKey?: string;
+    /** Debounced user changes; receives { formId, fieldId, values, revision, generation, dialogId? }. Return value is ignored. */
+    changeCommand?: string;
+    submitDisabled?: boolean;
+    fields: readonly PluginFormField[];
+    submitLabel: string;
+    /** Receives { formId, values, dialogId? }. Hidden/disabled fields are omitted. May return { fieldErrors, message }. */
+    command: string;
+}
+export interface PluginViewState {
+    id: string;
+    location: PluginViewContribution['location'];
+    visible: boolean;
+}
+export interface WorkspaceChangeEvent {
+    previous: WorkspaceInfo | null;
+    current: WorkspaceInfo;
+}
+export interface PluginNetworkRequest {
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    headers?: Readonly<Record<string, string>>;
+    body?: string;
+    timeoutMs?: number;
+}
+export interface PluginNetworkResponse {
+    url: string;
+    status: number;
+    headers: Readonly<Record<string, string>>;
+    body: string;
+}
+export type PluginTableCell = string | {
+    text: string;
+    command: string;
+    argument?: PluginCommandArgument;
+    disabled?: boolean;
+};
+export type PluginUiBlock = PluginFormBlock | {
+    type: 'separator';
+} | {
+    type: 'callout';
+    title: string;
+    text: string;
+    tone?: 'default' | 'destructive';
+} | {
+    type: 'progress';
+    label: string;
+    value: number;
+} | {
+    type: 'table';
+    id?: string;
+    rowIds?: readonly string[];
+    columns: readonly string[];
+    rows: readonly (readonly PluginTableCell[])[];
+} | {
+    type: 'tree';
+    items: readonly {
+        id: string;
+        parentId?: string;
+        label: string;
+        command?: string;
+        argument?: PluginCommandArgument;
+    }[];
+} | {
+    type: 'heading';
+    text: string;
+} | {
+    type: 'text';
+    text: string;
+    tone?: 'default' | 'muted' | 'warning';
+} | {
+    type: 'list';
+    items: readonly string[];
+} | {
+    type: 'key-value';
+    items: readonly {
+        label: string;
+        value: string;
+    }[];
+} | {
+    type: 'actions';
+    actions: readonly {
+        id: string;
+        label: string;
+        command: string;
+        argument?: PluginCommandArgument;
+        variant?: 'default' | 'secondary' | 'destructive';
+        disabled?: boolean;
+    }[];
+};
+export interface PluginUiDocument {
+    blocks: readonly PluginUiBlock[];
+    /** Apply only while this form input snapshot is current in the target surface. */
+    expectedForm?: {
+        formId: string;
+        generation: string;
+        revision: number;
+    };
+}
+export interface PluginDialogOptions {
+    /** Replace only this still-open dialog owned by this plugin. Otherwise a busy dialog returns Conflict. */
+    replaceId?: string;
+    title: string;
+    description?: string;
+    content: PluginUiDocument;
+    closeLabel?: string;
+}
+export interface PluginDisposable {
+    readonly dispose: () => void;
+}
+export interface PluginStorageArea {
+    readonly get: (key: string) => Promise<PluginJsonValue | undefined>;
+    readonly set: (key: string, value: PluginJsonValue) => Promise<void>;
+    readonly delete: (key: string) => Promise<void>;
+}
+export type PluginAbortListener = () => void;
+/** The AbortSignal subset implemented by NoteGen marketplace and development runtimes. */
+export interface PluginAbortSignal {
+    readonly aborted: boolean;
+    readonly reason: unknown;
+    readonly throwIfAborted: () => void;
+    readonly addEventListener: (type: 'abort', listener: PluginAbortListener, options?: {
+        once?: boolean;
+    }) => void;
+    readonly removeEventListener: (type: 'abort', listener: PluginAbortListener) => void;
+}
+export interface PluginStatusBarUpdate {
+    visible: boolean;
+    text?: string;
+    compactText?: string;
+    tooltip?: string;
+    accessibleLabel?: string;
+    busy?: boolean;
+}
+export interface PluginDialogHandle {
+    id: string;
+}
+export type PluginDialogUpdate = Omit<PluginDialogOptions, 'replaceId'>;
+/** Non-destructive main-window navigation only; no arbitrary command execution. */
+export type PluginHostCommand = 'app.openSearch' | 'app.openSettings' | 'app.openPluginSettings';
+export interface PluginDialogCloseEvent {
+    id: string;
+    reason: 'user' | 'programmatic' | 'replaced' | 'disposed';
+}
+export interface PluginAttachment {
+    /** Workspace-relative path; never an absolute filesystem path or file URL. */
+    path: string;
+    size: number;
+    /** Standard padded Base64, limited to 1 MiB of decoded bytes. */
+    base64: string;
+}
+export interface PluginContext {
+    readonly plugin: {
+        readonly id: string;
+        readonly version: string;
+        /** The concrete host API version, which may be newer than this SDK release. */
+        readonly apiVersion: string;
+    };
+    /** Local diagnostics only. Messages are truncated to 1,000 characters and rate limited. Never log secrets. */
+    readonly log: {
+        readonly info: (message: string) => void;
+        readonly warning: (message: string) => void;
+        readonly error: (message: string) => void;
+    };
+    readonly signal: PluginAbortSignal;
+    readonly commands: {
+        readonly executeHost: (command: PluginHostCommand) => Promise<void>;
+        readonly handle: (commandId: string, handler: (argument?: PluginCommandArgument) => PluginCommandResult | Promise<PluginCommandResult>) => PluginDisposable;
+    };
+    readonly workspace: {
+        readonly getCurrent: () => Promise<WorkspaceInfo>;
+        readonly onDidChange: (listener: (event: WorkspaceChangeEvent) => void | Promise<void>) => PluginDisposable;
+    };
+    readonly calendar: {
+        readonly resolveDay: (options: ResolveDayOptions) => Promise<ResolvedDay>;
+    };
+    readonly attachments: {
+        readonly read: (options: {
+            path: string;
+        }) => Promise<PluginAttachment>;
+        /** Creates a new file only. Existing files are never overwritten. */
+        readonly create: (options: {
+            path: string;
+            base64: string;
+        }) => Promise<{
+            path: string;
+            size: number;
+        }>;
+    };
+    readonly notes: {
+        readonly read: (options: ReadNoteOptions) => Promise<NoteSnapshot>;
+        readonly openOrCreate: (options: OpenOrCreateNoteOptions) => Promise<OpenOrCreateResult>;
+        readonly list: (options?: ListNotesOptions) => Promise<ListNotesResult>;
+        /** Requires both notes.list and notes.read within the granted folder. */
+        readonly search: (options: SearchNotesOptions) => Promise<SearchNotesResult>;
+        /** Main window only. Close every tab, pane, and separate window for the target first; otherwise EditorBusy. */
+        readonly write: (options: WriteNoteOptions) => Promise<WriteNoteResult>;
+        /** Main window only. Source and destination must be closed in every editor; otherwise EditorBusy. */
+        readonly move: (options: MoveNoteOptions) => Promise<void>;
+        /** Main window only. Close every tab, pane, and separate window for the target first; otherwise EditorBusy. */
+        readonly delete: (options: DeleteNoteOptions) => Promise<void>;
+        readonly onDidChange: (listener: (event: NoteChangeEvent) => void | Promise<void>) => PluginDisposable;
+    };
+    readonly editor: {
+        readonly getActiveEditor: () => Promise<ActiveEditorContext | null>;
+        readonly getSelection: () => Promise<EditorSelection | null>;
+        readonly getTextSnapshot: (options: GetEditorTextSnapshotOptions) => Promise<EditorTextSnapshot>;
+        readonly applyEdit: (options: ApplyEditorEditOptions) => Promise<ApplyEditorEditResult>;
+        /** Atomic, non-overlapping Markdown edits. Currently available in source mode. */
+        readonly applyEdits: (options: ApplyEditorEditsOptions) => Promise<ApplyEditorEditResult>;
+        /** Canonical Markdown offsets; currently available in source mode. */
+        readonly setSelection: (options: SetEditorSelectionOptions) => Promise<void>;
+        readonly onDidChangeActiveEditor: (listener: (event: EditorActiveChangeEvent) => void | Promise<void>) => PluginDisposable;
+        readonly onDidChangeContent: (listener: (event: EditorContentChangeEvent) => void | Promise<void>) => PluginDisposable;
+    };
+    readonly storage: {
+        readonly device: PluginStorageArea;
+        readonly workspace: PluginStorageArea;
+    };
+    readonly ui: {
+        readonly showNotice: (message: string) => Promise<void>;
+        readonly statusBar: {
+            readonly update: (id: string, state: PluginStatusBarUpdate) => Promise<void>;
+        };
+        readonly views: {
+            readonly update: (id: string, content: PluginUiDocument) => Promise<void>;
+            readonly open: (id: string) => Promise<void>;
+            readonly close: (id: string) => Promise<void>;
+            readonly focus: (id: string) => Promise<void>;
+            readonly getState: (id: string) => Promise<PluginViewState>;
+            readonly onDidChange: (listener: (state: PluginViewState) => void | Promise<void>) => PluginDisposable;
+        };
+        readonly openDialog: (options: PluginDialogOptions) => Promise<PluginDialogHandle>;
+        readonly updateDialog: (id: string, options: PluginDialogUpdate) => Promise<void>;
+        /** Closes only the calling plugin's dialog. */
+        readonly closeDialog: (id: string) => Promise<void>;
+        readonly onDidCloseDialog: (listener: (event: PluginDialogCloseEvent) => void | Promise<void>) => PluginDisposable;
+    };
+    readonly network: {
+        readonly fetch: (request: PluginNetworkRequest) => Promise<PluginNetworkResponse>;
+    };
+    readonly i18n: {
+        readonly t: (key: string, values?: Record<string, string | number>) => string;
+    };
+    readonly settings: {
+        readonly get: (key: string) => PluginSettingValue | undefined;
+        readonly onDidChange: (listener: (key: string, value: PluginSettingValue) => void | Promise<void>) => PluginDisposable;
+    };
+}
+export interface PluginModule {
+    activate: (context: PluginContext) => void | Promise<void>;
+    deactivate?: () => void | Promise<void>;
+}
+export type PluginActivate = PluginModule['activate'];
+export type PluginDeactivate = NonNullable<PluginModule['deactivate']>;
+export declare const PLUGIN_ERROR_CODES: readonly ["PermissionDenied", "AlreadyRegistered", "UnavailableOnPlatform", "QuotaExceeded", "StaleRevision", "Conflict", "NotFound", "InvalidTimeZone", "InvalidPath", "EditorBusy", "WorkspaceChanged", "CreatedNotOpened", "ReadOnly", "NoSpace", "Timeout", "Cancelled", "InvalidManifest", "Incompatible", "RuntimeFailure", "SignatureInvalid", "IntegrityMismatch"];
+export type PluginErrorCode = typeof PLUGIN_ERROR_CODES[number];
+/** Errors crossing the plugin boundary expose a stable code and message. */
+export declare class PluginError extends Error {
+    readonly code: PluginErrorCode;
+    readonly details?: Readonly<Record<string, PluginJsonValue>>;
+    constructor(code: PluginErrorCode, message: string, details?: Readonly<Record<string, PluginJsonValue>>);
+}
+/** Works for both local errors and errors received across the Worker boundary. */
+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;

package/dist/index.js

@@ -0,0 +1,47 @@
+/** The public API version implemented by this release of NoteGen. */
+export const PLUGIN_API_VERSION = '0.1.0';
+export const PLUGIN_ERROR_CODES = Object.freeze([
+    'PermissionDenied',
+    'AlreadyRegistered',
+    'UnavailableOnPlatform',
+    'QuotaExceeded',
+    'StaleRevision',
+    'Conflict',
+    'NotFound',
+    'InvalidTimeZone',
+    'InvalidPath',
+    'EditorBusy',
+    'WorkspaceChanged',
+    'CreatedNotOpened',
+    'ReadOnly',
+    'NoSpace',
+    'Timeout',
+    'Cancelled',
+    'InvalidManifest',
+    'Incompatible',
+    'RuntimeFailure',
+    'SignatureInvalid',
+    'IntegrityMismatch',
+]);
+/** Errors crossing the plugin boundary expose a stable code and message. */
+export class PluginError extends Error {
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'PluginError';
+        this.code = code;
+        this.details = details;
+    }
+}
+/** Works for both local errors and errors received across the Worker boundary. */
+export function isPluginError(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return typeof candidate.message === 'string'
+        && typeof candidate.code === 'string'
+        && PLUGIN_ERROR_CODES.includes(candidate.code);
+}
+/** Preserve literal manifest values while checking the v1 shape at compile time. */
+export function definePluginManifest(manifest) {
+    return manifest;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@notegen/plugin-api",
+  "version": "0.1.0",
+  "description": "Public TypeScript contract for NoteGen plugins.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./plugin-manifest-v1.schema.json": "./schema/plugin-manifest-v1.schema.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codexu/note-gen-plugin-sdk.git",
+    "directory": "packages/plugin-api"
+  },
+  "homepage": "https://notegen.top",
+  "bugs": {
+    "url": "https://github.com/codexu/note-gen-plugin-sdk/issues"
+  },
+  "notegen": {
+    "pluginApiVersion": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "check:contract": "node -e \"const fs=require('node:fs');const pkg=require('./package.json');const source=fs.readFileSync('src/index.ts','utf8');const match=source.match(/PLUGIN_API_VERSION = '([^']+)'/);if(!match)throw new Error('Missing PLUGIN_API_VERSION');if(match[1]!==pkg.notegen.pluginApiVersion)throw new Error('Package contract metadata '+pkg.notegen.pluginApiVersion+' does not match exported plugin API '+match[1]);\"",
+    "build": "pnpm run clean && pnpm run check:contract && tsc -p tsconfig.json"
+  }
+}

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

@@ -0,0 +1,309 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://notegen.top/schemas/plugin-manifest-v1.schema.json",
+  "title": "NoteGen Plugin Manifest v1",
+  "description": "Editor schema for plugin.json. The NoteGen CLI remains authoritative for semantic, localization, compatibility, and package-file validation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "manifestVersion",
+    "id",
+    "name",
+    "version",
+    "apiVersion",
+    "minAppVersion",
+    "platforms",
+    "entry",
+    "activationEvents",
+    "permissions",
+    "contributes"
+  ],
+  "properties": {
+    "manifestVersion": { "const": 1 },
+    "id": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 160,
+      "pattern": "^(?!app\\.notegen(?:\\.|$))(?=.{3,160}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
+    },
+    "name": { "$ref": "#/$defs/pluginName" },
+    "description": { "$ref": "#/$defs/pluginDescription" },
+    "version": { "$ref": "#/$defs/semver" },
+    "apiVersion": {
+      "type": "string",
+      "maxLength": 80,
+      "pattern": "^(?:(?:>=|<=|\\^|~|>|<) *)?(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"
+    },
+    "minAppVersion": { "$ref": "#/$defs/semver" },
+    "platforms": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 3,
+      "uniqueItems": true,
+      "items": { "enum": ["desktop", "ios", "android"] },
+      "contains": { "const": "desktop" }
+    },
+    "entry": { "$ref": "#/$defs/entryPath" },
+    "activationEvents": {
+      "type": "array",
+      "maxItems": 100,
+      "uniqueItems": true,
+      "items": {
+        "anyOf": [
+          { "enum": ["onEditor:markdown", "onWorkspace:open", "onNotes:change"] },
+          { "type": "string", "pattern": "^onCommand:[A-Za-z0-9._-]+$", "maxLength": 240 }
+        ]
+      }
+    },
+    "permissions": { "$ref": "#/$defs/permissions" },
+    "contributes": { "$ref": "#/$defs/contributions" },
+    "defaultLocale": { "$ref": "#/$defs/localeTag" },
+    "locales": {
+      "type": "object",
+      "maxProperties": 50,
+      "propertyNames": { "$ref": "#/$defs/localeTag" },
+      "additionalProperties": { "$ref": "#/$defs/packagePath" }
+    },
+    "author": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "url": { "$ref": "#/$defs/publicUrl" }
+      }
+    },
+    "repository": { "$ref": "#/$defs/publicUrl" },
+    "license": { "type": "string", "minLength": 1, "maxLength": 80 }
+  },
+  "$defs": {
+    "pluginName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 100
+    },
+    "pluginDescription": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "localizedText": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240
+    },
+    "semver": {
+      "type": "string",
+      "maxLength": 80,
+      "pattern": "^(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"
+    },
+    "namespacedId": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 220,
+      "pattern": "^[A-Za-z0-9._-]+$"
+    },
+    "packagePath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "^(?!/)(?![A-Za-z]:)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
+    },
+    "entryPath": {
+      "type": "string",
+      "minLength": 4,
+      "maxLength": 240,
+      "pattern": "^(?!/)(?![A-Za-z]:)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+\\.js$"
+    },
+    "localeTag": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 35,
+      "pattern": "^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"
+    },
+    "publicUrl": {
+      "type": "string",
+      "maxLength": 500,
+      "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://"
+    },
+    "permission": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scope"],
+      "properties": {
+        "scope": { "type": "string" },
+        "optional": { "type": "boolean" },
+        "description": { "$ref": "#/$defs/localizedText" }
+      }
+    },
+    "activeEditorPermission": {
+      "allOf": [
+        { "$ref": "#/$defs/permission" },
+        { "properties": { "scope": { "const": "active-editor" } } }
+      ]
+    },
+    "folderPermission": {
+      "allOf": [
+        { "$ref": "#/$defs/permission" },
+        { "properties": { "scope": { "const": "workspace-folder" } } }
+      ]
+    },
+    "filePermission": {
+      "allOf": [
+        { "$ref": "#/$defs/permission" },
+        { "properties": { "scope": { "enum": ["workspace-file", "workspace-files", "workspace-folder"] } } }
+      ]
+    },
+    "permissions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "editor.read": { "$ref": "#/$defs/activeEditorPermission" },
+        "editor.write": { "$ref": "#/$defs/activeEditorPermission" },
+        "notes.read": { "$ref": "#/$defs/filePermission" },
+        "notes.create": { "$ref": "#/$defs/folderPermission" },
+        "notes.open": { "$ref": "#/$defs/folderPermission" },
+        "notes.list": { "$ref": "#/$defs/folderPermission" },
+        "notes.write": { "$ref": "#/$defs/filePermission" },
+        "attachments.read": { "$ref": "#/$defs/filePermission" },
+        "attachments.create": { "$ref": "#/$defs/folderPermission" },
+        "notes.delete": { "$ref": "#/$defs/filePermission" },
+        "notes.move": { "$ref": "#/$defs/folderPermission" },
+        "network.fetch": {
+          "allOf": [
+            { "$ref": "#/$defs/permission" },
+            { "properties": { "scope": { "const": "network-origins" } } }
+          ]
+        }
+      }
+    },
+    "command": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "properties": {
+        "id": { "$ref": "#/$defs/namespacedId" },
+        "title": { "$ref": "#/$defs/localizedText" },
+        "description": { "$ref": "#/$defs/localizedText" },
+        "icon": { "type": "string", "pattern": "^[A-Za-z0-9-]+$", "maxLength": 80 },
+        "suggestedShortcut": { "type": "string", "minLength": 1, "maxLength": 80 }
+      }
+    },
+    "settingCommon": {
+      "type": "object",
+      "required": ["key", "type", "scope", "title", "default"],
+      "properties": {
+        "key": { "$ref": "#/$defs/namespacedId" },
+        "scope": { "enum": ["device", "workspace"] },
+        "title": { "$ref": "#/$defs/localizedText" },
+        "description": { "$ref": "#/$defs/localizedText" }
+      }
+    },
+    "setting": {
+      "oneOf": [
+        {
+          "allOf": [{ "$ref": "#/$defs/settingCommon" }],
+          "additionalProperties": false,
+          "properties": {
+            "key": { "$ref": "#/$defs/namespacedId" }, "type": { "const": "boolean" },
+            "scope": { "enum": ["device", "workspace"] }, "title": { "$ref": "#/$defs/localizedText" },
+            "description": { "$ref": "#/$defs/localizedText" }, "default": { "type": "boolean" }
+          }
+        },
+        {
+          "allOf": [{ "$ref": "#/$defs/settingCommon" }],
+          "additionalProperties": false,
+          "properties": {
+            "key": { "$ref": "#/$defs/namespacedId" }, "type": { "const": "string" },
+            "scope": { "enum": ["device", "workspace"] }, "title": { "$ref": "#/$defs/localizedText" },
+            "description": { "$ref": "#/$defs/localizedText" }, "default": { "type": "string" },
+            "placeholder": { "$ref": "#/$defs/localizedText" },
+            "maxLength": { "type": "integer", "minimum": 1, "maximum": 65536 },
+            "permissionPaths": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": { "type": "string" } }
+          }
+        },
+        {
+          "allOf": [{ "$ref": "#/$defs/settingCommon" }],
+          "additionalProperties": false,
+          "properties": {
+            "key": { "$ref": "#/$defs/namespacedId" }, "type": { "const": "number" },
+            "scope": { "enum": ["device", "workspace"] }, "title": { "$ref": "#/$defs/localizedText" },
+            "description": { "$ref": "#/$defs/localizedText" }, "default": { "type": "number" },
+            "min": { "type": "number" }, "max": { "type": "number" },
+            "step": { "type": "number", "exclusiveMinimum": 0 }
+          }
+        },
+        {
+          "allOf": [{ "$ref": "#/$defs/settingCommon" }],
+          "additionalProperties": false,
+          "properties": {
+            "key": { "$ref": "#/$defs/namespacedId" }, "type": { "const": "select" },
+            "scope": { "enum": ["device", "workspace"] }, "title": { "$ref": "#/$defs/localizedText" },
+            "description": { "$ref": "#/$defs/localizedText" }, "default": { "type": "string" },
+            "options": {
+              "type": "array", "minItems": 1, "maxItems": 100,
+              "items": {
+                "type": "object", "additionalProperties": false, "required": ["label", "value"],
+                "properties": { "label": { "$ref": "#/$defs/localizedText" }, "value": { "type": "string", "minLength": 1, "maxLength": 160 } }
+              }
+            }
+          },
+          "required": ["options"]
+        },
+        {
+          "allOf": [{ "$ref": "#/$defs/settingCommon" }],
+          "additionalProperties": false,
+          "properties": {
+            "key": { "$ref": "#/$defs/namespacedId" }, "type": { "enum": ["workspace-file", "workspace-folder"] },
+            "scope": { "const": "workspace" }, "title": { "$ref": "#/$defs/localizedText" },
+            "description": { "$ref": "#/$defs/localizedText" }, "default": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "statusBar": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "alignment"],
+      "properties": {
+        "id": { "$ref": "#/$defs/namespacedId" },
+        "alignment": { "enum": ["left", "right"] },
+        "priority": { "type": "integer", "minimum": -10000, "maximum": 10000 },
+        "command": { "$ref": "#/$defs/namespacedId" }
+      }
+    },
+    "menu": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["location", "command"],
+      "properties": {
+        "location": { "enum": ["editor/slash", "editor/context", "file/context", "mobile/writing/overflow"] },
+        "command": { "$ref": "#/$defs/namespacedId" },
+        "when": { "type": "string", "minLength": 1, "maxLength": 240 },
+        "group": { "type": "string", "minLength": 1, "maxLength": 80 }
+      }
+    },
+    "view": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "location"],
+      "properties": {
+        "id": { "$ref": "#/$defs/namespacedId" },
+        "title": { "$ref": "#/$defs/localizedText" },
+        "location": { "enum": ["left-sidebar", "right-sidebar", "editor-tab"] },
+        "icon": { "type": "string", "pattern": "^[A-Za-z0-9-]+$", "maxLength": 80 }
+      }
+    },
+    "contributions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "commands": { "type": "array", "maxItems": 100, "items": { "$ref": "#/$defs/command" } },
+        "settings": { "type": "array", "maxItems": 100, "items": { "$ref": "#/$defs/setting" } },
+        "statusBar": { "type": "array", "maxItems": 30, "items": { "$ref": "#/$defs/statusBar" } },
+        "menus": { "type": "array", "maxItems": 100, "items": { "$ref": "#/$defs/menu" } },
+        "views": { "type": "array", "maxItems": 30, "items": { "$ref": "#/$defs/view" } }
+      }
+    }
+  }
+}