@abraca/plugin 2.3.0

package/dist/index.d.ts

@@ -0,0 +1,642 @@
+//#region packages/plugin/src/types.d.ts
+/**
+ * Shared plugin contract for cou-shell and `@abraca/nuxt`.
+ *
+ * `AbraPlugin` is the universal interface every plugin satisfies. App-specific
+ * supersets (`CouPlugin`, `AbracadabraPlugin`) extend or intersect this with
+ * tightened contribution shapes — TipTap toolbar items, Nuxt UI dropdown
+ * items, page-type renderers, file importers, etc.
+ *
+ * Zero peer-dep types. `Y.Doc`, `@tiptap/core`'s `Extension`, and Vue's
+ * `Component` are all referenced via local structural markers (`AbraYDoc`,
+ * `AbraTiptapExtension`, `unknown`) so this package compiles in isolation
+ * and can be consumed by hosts on any TipTap / yjs / Vue version without
+ * dragging duplicate-type fights along.
+ */
+/**
+ * Structural marker for `yjs`'s `Y.Doc`. Defined locally — and intentionally
+ * permissive — so the plugin contract doesn't pin a specific yjs version. Any
+ * `Y.Doc` from any minor yjs version (13.6.29, 13.6.30, …) is structurally
+ * compatible. Consumers cast back to their own `Y.Doc` as needed.
+ */
+interface AbraYDoc {
+  readonly clientID?: number;
+}
+/**
+ * Structural marker for `@tiptap/core`'s `Extension`. Defined locally — and
+ * intentionally permissive — so the plugin contract doesn't pin a specific
+ * TipTap version. Any `Extension` from any minor TipTap version (3.22.5,
+ * 3.23.2, …) is structurally compatible. Consumers cast back to their own
+ * `Extension` as needed.
+ */
+interface AbraTiptapExtension {
+  readonly name?: string;
+  readonly type?: string;
+}
+/**
+ * The universal plugin shape. Every plugin in the Abracadabra ecosystem
+ * (built-in or third-party, in cou-shell or any `@abraca/nuxt` consumer)
+ * satisfies this interface.
+ *
+ * Contribution fields use widened shapes (`unknown`, `Record<string, unknown>`)
+ * where the concrete type is consumer-defined. App-level plugin aliases
+ * (e.g. `CouPlugin`, `AbracadabraPlugin`) narrow them.
+ */
+interface AbraPlugin {
+  /** Unique slug. Must be stable across versions, e.g. `core`, `kanban`, `my-plugin`. */
+  name: string;
+  /** Human-readable label shown in plugin browsers. Falls back to `name`. */
+  label?: string;
+  /** Plugin version. Should follow semver. */
+  version?: string;
+  /** One-line plugin description shown in browsers and scorecards. */
+  description?: string;
+  /**
+   * Whether a built-in plugin is enabled by default. `true` if omitted.
+   * Only consulted for plugins that ship as built-ins; external plugins
+   * are opt-in regardless.
+   */
+  defaultEnabled?: boolean;
+  /** TipTap extensions (nodes, marks, extensions) contributed by this plugin. */
+  extensions?: () => AbraTiptapExtension[];
+  /**
+   * Optional promise that resolves when this plugin's extensions are fully
+   * loaded. Used by `PluginRegistry.waitForExtensions()` so the editor
+   * doesn't initialise before async extension bundles are ready.
+   */
+  extensionsReady?: Promise<void>;
+  /** Page-type renderers keyed by type slug. Concrete shape is consumer-defined. */
+  pageTypes?: Record<string, unknown>;
+  /**
+   * Custom editor handlers (e.g. `table`, `fileUpload`). Each entry merges
+   * into the host's handler map. Handler signatures are consumer-defined —
+   * cou-shell types them as `EditorHandler` from `@nuxt/ui` (which uses
+   * specific arg counts that wouldn't match `(...args: any[]) => any`), the
+   * module uses a different shape; the shared contract just promises a
+   * record of any values.
+   */
+  customHandlers?: () => Record<string, any>;
+  /**
+   * Editor toolbar / menu / slash-command / drag-handle contributions.
+   *
+   * The context shape and item-group shape are both consumer-defined. Method
+   * shorthand syntax is used deliberately — interface-method positions are
+   * bivariant in TypeScript, so app-specific aliases (`AbracadabraPlugin`,
+   * `CouPlugin`) can narrow `ctx` to their own tightened context types
+   * without `Omit`-and-rewrite gymnastics.
+   */
+  toolbarItems?(ctx: EditorPluginCtx): readonly (readonly unknown[])[];
+  bubbleMenuItems?(ctx: EditorPluginCtx): readonly (readonly unknown[])[];
+  suggestionItems?(ctx: EditorPluginCtx): readonly (readonly unknown[])[];
+  dragHandleItems?(ctx: DragHandlePluginCtx): readonly (readonly unknown[])[];
+  /** Mention (@) providers contributing items to the mention popup. */
+  mentionProviders?: AbraMentionProvider[];
+  /** Awareness field declarations — keys this plugin reads/writes on awareness. */
+  awarenessContributions?: AbraAwarenessContribution[];
+  /** Global command-palette (⌘K) items. */
+  commandPaletteItems?(ctx: CommandPaletteCtx): readonly AbraCommandItem[] | Promise<readonly AbraCommandItem[]>;
+  /** Extra tabs rendered in the child-document slideover panel. */
+  nodePanelSlots?: AbraNodePanelSlot[];
+  /** Settings panel contributed to the global settings view. */
+  settingsPanel?: AbraSettingsPanel;
+  /** Global keyboard shortcuts (document-level, not inside TipTap scope). */
+  keyboardShortcuts?: AbraKeyboardShortcut[];
+  /**
+   * Client-side setup hook — called once after the client + provider are
+   * ready. May return a teardown function called on app unmount.
+   */
+  clientSetup?(ctx: ClientPluginCtx): undefined | void | (() => void) | Promise<undefined | void | (() => void)>;
+  /** TipTap extensions safe for server-side Y.Doc → HTML rendering (no Vue NodeViews). */
+  serverExtensions?: () => AbraTiptapExtension[];
+  /**
+   * Custom cache renderer for non-doc page types. Receives the Y.Doc and
+   * returns serialisable data for the host's cache. Method shorthand —
+   * bivariant, so consumer plugins can narrow the `ydoc` parameter to a
+   * real `Y.Doc` from their own yjs version.
+   */
+  serverCacheRenderer?(docId: string, ydoc: AbraYDoc): unknown;
+  /**
+   * Server-side background runners (Nitro context, service-role identity).
+   *
+   * Typed as `unknown[]` in the shared contract because each host wraps
+   * the runner ctx with its own `AbracadabraClient` / `AbracadabraProvider`
+   * / `DocCacheAPI` / etc. — a structural override here would force every
+   * consumer to either match the shared base structure exactly or fight
+   * input-contravariance. Consumers narrow this to their own
+   * `ServerRunnerDefinition[]` in their `CouPlugin` / `AbracadabraPlugin`
+   * aliases.
+   */
+  serverRunners?: readonly unknown[];
+}
+/**
+ * Context passed to editor-scoped plugin hooks.
+ *
+ * `editor` is the TipTap editor wrapped in whatever ref-like the host uses
+ * (`ShallowRef<Editor | null>` in Vue 3 hosts). Typed as a structural ref to
+ * avoid pulling `vue` into the type closure of plugin consumers that don't
+ * use Vue.
+ */
+interface EditorPluginCtx<TEditor = unknown> {
+  editor: EditorRefLike<TEditor>;
+  docId: string;
+}
+/**
+ * Context passed to drag-handle plugin hooks. Carries the currently-selected
+ * node plus its document position.
+ */
+interface DragHandlePluginCtx<TEditor = unknown, TNode = unknown> extends EditorPluginCtx<TEditor> {
+  selectedNode: RefLike<{
+    node: TNode | null;
+    pos: number;
+  } | undefined>;
+}
+/**
+ * Context passed to `clientSetup`. `abracadabra` is the host's full reactive
+ * state — typed as `unknown` here; app-specific plugin aliases tighten this
+ * to `AbracadabraState` / `ReturnType<typeof useAbracadabra>` / similar.
+ */
+interface ClientPluginCtx<TState = unknown> {
+  abracadabra: TState;
+}
+/** Context passed to command-palette plugin hooks. */
+interface CommandPaletteCtx<TState = unknown, TTree = unknown> {
+  docId: string | null;
+  /** `useRouter()`'s return value. Typed as `unknown` to avoid a `vue-router` peer dep. */
+  router: unknown;
+  abracadabra: TState;
+  tree: TTree | null;
+}
+/** Context passed to mention provider hooks. */
+interface MentionPluginCtx {
+  docId: string;
+  connectedUsers: readonly CollaborationUser[];
+  rootDoc: AbraYDoc;
+}
+/**
+ * Minimal shape of a Vue `Ref`/`ShallowRef`/Solid signal. Defined locally so
+ * the plugin contract doesn't depend on a specific reactivity library.
+ */
+interface RefLike<T> {
+  value: T;
+}
+/** A read-mostly ref for the TipTap editor instance. */
+type EditorRefLike<TEditor = unknown> = RefLike<TEditor | null>;
+interface AbraMentionProvider {
+  /** Group label shown in the suggestion popup. */
+  label: string;
+  /**
+   * Method shorthand (not arrow property) — TS treats this position as
+   * bivariant, so consumer plugins can narrow `ctx` to their own tightened
+   * mention-context type without contravariance fights.
+   */
+  getItems(query: string, ctx: MentionPluginCtx): readonly AbraMentionItem[] | Promise<readonly AbraMentionItem[]>;
+}
+interface AbraMentionItem {
+  id: string;
+  label: string;
+  avatar?: string;
+  color?: string;
+  attrs?: Record<string, unknown>;
+}
+interface AbraAwarenessContribution {
+  /** Namespaced keys this plugin writes, e.g. `['cursor', 'presence:kanban']`. */
+  keys: readonly string[];
+  /**
+   * Optional Vue component rendered as a presence overlay. Typed as
+   * `unknown` so the plugin contract stays Vue-free at the type level.
+   * Concrete consumers cast to `Component` / `DefineComponent` as needed.
+   */
+  cursorComponent?: unknown;
+}
+interface AbraCommandItem {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: string;
+  group?: string;
+  shortcut?: string;
+  /** Method shorthand — bivariant, so consumer types can narrow `ctx`. */
+  when?(ctx: CommandPaletteCtx): boolean;
+  /** Method shorthand — bivariant, so consumer types can narrow `ctx`. */
+  handler(ctx: CommandPaletteCtx): void | Promise<void>;
+}
+interface AbraNodePanelSlot {
+  id: string;
+  label: string;
+  icon: string;
+  /** Method shorthand — bivariant, so consumer types can narrow `ctx`. */
+  when(ctx: NodePanelCtx): boolean;
+  component: unknown;
+}
+interface NodePanelCtx {
+  childId: string;
+  childDoc: AbraYDoc | null;
+  parentDocId: string;
+  parentType: string | undefined;
+  meta: Record<string, unknown>;
+  tree: unknown;
+}
+interface AbraSettingsPanel {
+  label: string;
+  icon: string;
+  component: unknown;
+}
+interface AbraKeyboardShortcut {
+  /** Key spec, e.g. `'Meta+Shift+K'`, `'Control+Alt+P'`. */
+  key: string;
+  description: string;
+  handler: () => void | Promise<void>;
+}
+interface CollaborationUser {
+  name: string;
+  color: string;
+  publicKey?: string;
+  docId?: string;
+}
+/**
+ * Cleanup function returned by a runner's `start()`. Called on graceful
+ * server shutdown.
+ */
+type RunnerCleanup = (() => void | Promise<void>) | undefined | void;
+/**
+ * A named background task that runs inside the host's server process
+ * (Nitro, in `@abraca/nuxt`'s case).
+ *
+ * The runner context is parameterised so each host can extend it with its
+ * own client/provider/storage shapes without the plugin contract dragging
+ * `@abraca/dabra` along.
+ */
+interface ServerRunnerDefinition<TCtx = ServerRunnerContextBase> {
+  name: string;
+  /** Method shorthand — bivariant, so consumer types can narrow `ctx`. */
+  start(ctx: TCtx): Promise<RunnerCleanup> | RunnerCleanup;
+}
+/**
+ * Minimum context every server runner receives. Hosts extend this with
+ * `client`, `wsp`, `rootProvider`, etc.
+ */
+interface ServerRunnerContextBase {
+  /** Root Y.Doc (the world / hub doc, or the space root doc for space-scoped runners). */
+  rootDoc: AbraYDoc;
+  /** Space ID if this runner is scoped to a space; `null` for hub-scoped runners. */
+  spaceId?: string | null;
+}
+//#endregion
+//#region packages/plugin/src/registry.d.ts
+/** Extract the value type from a `Record<string, V>`-shaped optional field. */
+type RecordValueOf<T> = T extends Record<string, infer V> ? V : never;
+/** Extract the item type from a `(ctx) => readonly (readonly T[])[]` field. */
+type GroupedItemOf<T> = T extends ((...args: never[]) => readonly (infer Group)[]) ? Group extends readonly (infer Item)[] ? Item : never : never;
+/** Extract the array element type from an optional array field. */
+type ElementOf<T> = T extends readonly (infer V)[] ? V : never;
+/** Result-shape of `commandPaletteItems` collapsed to its item type. */
+type CommandItemOf<T> = T extends ((...args: never[]) => infer R) ? R extends Promise<readonly (infer Item)[]> ? Item : R extends readonly (infer Item)[] ? Item : never : never;
+type PageTypeOf<P> = P extends {
+  pageTypes?: infer R;
+} ? RecordValueOf<R> : never;
+type CustomHandlerOf<P> = P extends {
+  customHandlers?: () => infer R;
+} ? R : never;
+type ToolbarItemOf<P> = P extends {
+  toolbarItems?: infer F;
+} ? GroupedItemOf<F> : never;
+type BubbleItemOf<P> = P extends {
+  bubbleMenuItems?: infer F;
+} ? GroupedItemOf<F> : never;
+type SuggestionItemOf<P> = P extends {
+  suggestionItems?: infer F;
+} ? GroupedItemOf<F> : never;
+type DragHandleItemOf<P> = P extends {
+  dragHandleItems?: infer F;
+} ? GroupedItemOf<F> : never;
+type MentionProviderOf<P> = P extends {
+  mentionProviders?: infer A;
+} ? ElementOf<A> : never;
+type AwarenessContributionOf<P> = P extends {
+  awarenessContributions?: infer A;
+} ? ElementOf<A> : never;
+type CommandPaletteItemOf<P> = P extends {
+  commandPaletteItems?: infer F;
+} ? CommandItemOf<F> : never;
+type NodePanelSlotOf<P> = P extends {
+  nodePanelSlots?: infer A;
+} ? ElementOf<A> : never;
+type SettingsPanelOf<P> = P extends {
+  settingsPanel?: infer V;
+} ? NonNullable<V> : never;
+type KeyboardShortcutOf<P> = P extends {
+  keyboardShortcuts?: infer A;
+} ? ElementOf<A> : never;
+declare class PluginRegistry<P extends AbraPlugin = AbraPlugin> {
+  private _builtins;
+  private _spacePlugins;
+  private _frozen;
+  private _spaceVersion;
+  /**
+   * Register a built-in plugin. No-ops with a warning after `freeze()`.
+   * Use `registerSpacePlugin()` for plugins that arrive after boot.
+   */
+  register(plugin: P): void;
+  /** Lock the registry. Called once after all built-in + external plugins are loaded. */
+  freeze(): void;
+  isFrozen(): boolean;
+  /** Reactive registration channel for space-driven plugins (bypasses freeze). */
+  registerSpacePlugin(plugin: P): void;
+  unregisterSpacePlugin(name: string): void;
+  clearSpacePlugins(): void;
+  /** Monotonically increasing counter — bump when space plugins change. */
+  getSpacePluginVersion(): number;
+  getBuiltinPlugins(): readonly P[];
+  getSpacePlugins(): readonly P[];
+  /** All active plugins — built-ins first, then space plugins. */
+  getPlugins(): readonly P[];
+  getAllExtensions(): AbraTiptapExtension[];
+  getServerExtensions(): AbraTiptapExtension[];
+  /** Resolves once every plugin with `extensionsReady` has settled. */
+  waitForExtensions(): Promise<void>;
+  getAllPageTypes(): Record<string, PageTypeOf<P>>;
+  getAllCustomHandlers(): CustomHandlerOf<P>;
+  getAllToolbarItems(ctx: EditorPluginCtx): ToolbarItemOf<P>[][];
+  getAllBubbleMenuItems(ctx: EditorPluginCtx): BubbleItemOf<P>[][];
+  getAllSuggestionItems(ctx: EditorPluginCtx): SuggestionItemOf<P>[][];
+  getAllDragHandleItems(ctx: DragHandlePluginCtx): DragHandleItemOf<P>[][];
+  getAllMentionProviders(): MentionProviderOf<P>[];
+  getAllAwarenessContributions(): AwarenessContributionOf<P>[];
+  getAllCommandPaletteItems(ctx: CommandPaletteCtx): Promise<CommandPaletteItemOf<P>[]>;
+  getAllNodePanelSlots(): NodePanelSlotOf<P>[];
+  getSettingsPanels(): SettingsPanelOf<P>[];
+  getAllKeyboardShortcuts(): KeyboardShortcutOf<P>[];
+}
+//#endregion
+//#region packages/plugin/src/source-spec.d.ts
+/**
+ * Plugin source specification — the user-typed shorthand that resolves to a
+ * loadable URL.
+ *
+ * Today the registry server (Phase C) hosts artifacts at canonical URLs.
+ * Until then, both `cou-shell` and `@abraca/nuxt` accept three forms:
+ *
+ *   - `npm:<package>[@version]`     → jsDelivr npm CDN
+ *   - `github:<user>/<repo>[@ref]`  → jsDelivr GitHub CDN
+ *   - any other string              → returned as-is (must be `https://` or `http://localhost`)
+ *
+ * Once Phase C ships we add:
+ *
+ *   - `abra:<plugin-id>[@version]`  → the official registry
+ *
+ * The output URL points at the plugin's bundle entry. Convention is
+ * `<root>/dist/plugin.js`.
+ */
+/** A locally-installed external plugin record (persisted to host storage). */
+interface ExternalPluginEntry {
+  /** Resolved fetch URL — the output of `normalizePluginUrl`. */
+  url: string;
+  /** Plugin `name` from the loaded bundle's manifest / default export. */
+  name: string;
+  label?: string;
+  version?: string;
+  description?: string;
+  enabled: boolean;
+  /** Most recent load error, if any. Cleared on next successful load. */
+  error?: string;
+  installedAt: number;
+  /**
+   * Integrity hash from the plugin's manifest, if known. Verified on every
+   * load — a silent change indicates supply-chain tampering and the host
+   * should refuse to instantiate the plugin.
+   */
+  integrity?: string;
+}
+/**
+ * Resolve a user-typed plugin spec to a fetchable URL.
+ *
+ * - `npm:foo@1.2.3` → `https://cdn.jsdelivr.net/npm/foo@1.2.3/dist/plugin.js`
+ * - `github:org/repo@main` → `https://cdn.jsdelivr.net/gh/org/repo@main/dist/plugin.js`
+ * - anything else → returned trimmed, unchanged
+ */
+declare function normalizePluginUrl(input: string): string;
+/**
+ * Reject any URL that isn't HTTPS or localhost over HTTP. Hosts should call
+ * this before importing — `normalizePluginUrl` does not enforce the policy
+ * (npm:/github: shorthand always produces HTTPS, so callers only need this
+ * for raw third-party URLs).
+ */
+declare function isSafePluginUrl(url: string): boolean;
+//#endregion
+//#region packages/plugin/src/manifest.d.ts
+/**
+ * Plugin manifest v1 — the declarative `manifest.json` colocated with a
+ * plugin's bundle. Hosts parse this before executing the bundle, and the
+ * registry server (Phase C) validates it server-side too.
+ *
+ * Phase A scope: types only. Zod validators + JSON Schema generation live
+ * in `@abraca/schema` (Phase B).
+ */
+/**
+ * Capability tokens declared by a plugin's manifest. The host enforces these
+ * at the plugin-host boundary — a plugin without `network:*` cannot `fetch()`,
+ * a plugin without `clipboard:write` cannot write the clipboard, etc.
+ *
+ * Phase 1 enforcement is contract-based (we wrap host APIs). Phase 4 adds
+ * Wasm / Web Worker / iframe sandboxing so the contract is enforced at the
+ * runtime boundary, not just the host-API boundary.
+ */
+type PluginCapability = /** Outbound HTTP — `network` (any host) or `network:<host>` (exact match, wildcards allowed). */`network${"" | `:${string}`}` /** Filesystem reads — only meaningful in Tauri / native hosts. */ | "fs:read" /** Filesystem writes — Tauri / native only. */ | "fs:write" /** Read the clipboard. */ | "clipboard:read" /** Write the clipboard. */ | "clipboard:write" /** Read any Y.Doc the host has loaded. */ | "doc-read" /** Mutate Y.Docs (transact_mut against the host's provider). */ | "doc-write" /** Broadcast presence / awareness state. */ | "awareness" /** Register an RPC v1 handler on the service runner. */ | "server-runner" /** Contribute items to the global command palette. */ | "command-palette" /** Contribute editor toolbar items. */ | "toolbar" /** Contribute bubble-menu items (text selection). */ | "bubble-menu" /** Contribute slash-command suggestion items. */ | "slash-command" /** Contribute drag-handle items. */ | "drag-handle" /** Register a page-type renderer with the given slug. */ | `page-type:${string}` /** Send messages on the in-doc chat channel. */ | "chat:send" /** Read in-doc chat history. */ | "chat:read" /** Show user-visible notifications. */ | "notifications:show";
+interface PluginManifestAuthor {
+  /** GitHub login. Identifies the author in the registry. */
+  github?: string;
+  /** Human-readable display name. */
+  name?: string;
+  url?: string;
+  email?: string;
+}
+/** Pricing label as defined in the registry — see registry docs for semantics. */
+type PluginPricing = "free" | "optional" | "paid";
+/** Submission / publication status as exposed by the registry's catalog API. */
+type PluginVersionStatus = "live" | "pending" | "rejected" | "superseded";
+/** Declared contributions — the plugin's static claim about what it ships. */
+interface PluginManifestContributes {
+  pageTypes?: readonly string[];
+  extensions?: readonly string[];
+  awarenessFields?: readonly string[];
+  serverRunners?: readonly string[];
+  commands?: readonly string[];
+  settingsPanels?: readonly string[];
+}
+/**
+ * The static manifest colocated with the plugin entry. Versioned via the
+ * top-level `manifestVersion` field — the only field guaranteed to exist
+ * verbatim across all manifest versions.
+ */
+interface PluginManifest {
+  /** Schema version of this manifest format. Currently always `1`. */
+  manifestVersion: 1;
+  /** Unique lowercase-kebab slug. Stable across versions. */
+  id: string;
+  /** Display name. Falls back to `id`. */
+  name?: string;
+  /** Plugin version (semver). */
+  version: string;
+  /** Author / maintainer info. */
+  author: PluginManifestAuthor;
+  /** SPDX license identifier (e.g. `MIT`, `Apache-2.0`). */
+  license: string;
+  /** One- to two-sentence summary shown in browsers and scorecards. */
+  description: string;
+  /** Long-form description / changelog — markdown allowed. */
+  readme?: string;
+  homepage?: string;
+  /** `github:user/repo` shorthand or any URL. */
+  repository?: string;
+  /** Minimum Abracadabra SDK version required (semver range). */
+  minAbracadabraVersion?: string;
+  /** Path to the bundle entry, relative to the manifest. */
+  entry: string;
+  /**
+   * SHA-256 of the bundle entry, hex-encoded. Verified by hosts before
+   * `import()`. Mismatch → refuse to load.
+   */
+  integrity: string;
+  /** Pricing tier as defined in the registry. */
+  pricing?: PluginPricing;
+  /** Screenshot paths (relative to manifest), shown on the detail page. */
+  screenshots?: readonly string[];
+  /** Free-form category tags for catalog filtering. */
+  categories?: readonly string[];
+  /** Required capabilities — host MUST grant these or refuse the install. */
+  capabilities: {
+    required: readonly PluginCapability[];
+    optional?: readonly PluginCapability[];
+  };
+  /** Declared contributions. Static check; verified against runtime registrations. */
+  contributes?: PluginManifestContributes;
+  /**
+   * Peer dependencies the plugin expects the host to provide. Hosts publish
+   * the versions they ship via `globalThis.__ABRACA_SHARED__`.
+   */
+  peerDeps?: Record<string, string>;
+}
+/** Registry-decorated manifest — what the catalog API returns. */
+interface PluginRegistryEntry {
+  manifest: PluginManifest;
+  /** Resolved bundle URL (R2 / jsDelivr / etc). */
+  artifactUrl: string;
+  /** Registry-side artifact hash, mirrors `manifest.integrity`. */
+  artifactSha256: string;
+  /** Status as seen by the registry. */
+  status: PluginVersionStatus;
+  publishedAt: string;
+  /**
+   * Scorecard summary — `null` until the registry has scanned this version.
+   * Concrete shape lives in `@abraca/schema` (Phase H).
+   */
+  scorecard: unknown | null;
+}
+//#endregion
+//#region packages/plugin/src/host.d.ts
+/**
+ * Thrown when a plugin tries to use an API it didn't declare in its
+ * manifest. Distinct from runtime failures (network 500, file not found,
+ * etc.) so the host can show the user "the plugin tried to do X without
+ * permission" instead of a generic error.
+ */
+declare class CapabilityDenied extends Error {
+  readonly capability: PluginCapability | string;
+  readonly pluginId: string;
+  constructor(pluginId: string, capability: PluginCapability | string, detail?: string);
+}
+/** Subset of the global `fetch` signature the host exposes. */
+type GuardedFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/** Subset of `navigator.clipboard` the host exposes. */
+interface GuardedClipboard {
+  readText(): Promise<string>;
+  writeText(text: string): Promise<void>;
+}
+/** Permission-aware desktop notification. */
+interface GuardedNotifications {
+  show(title: string, options?: NotificationOptions): Promise<void>;
+}
+/**
+ * Everything a plugin is allowed to touch through the host contract.
+ * Each plugin gets its own instance via `createPluginHost(manifest)`.
+ */
+interface PluginHost {
+  readonly pluginId: string;
+  readonly capabilities: ReadonlySet<PluginCapability>;
+  fetch: GuardedFetch;
+  clipboard: GuardedClipboard;
+  notifications: GuardedNotifications;
+  /** Test whether a capability is granted without invoking the wrapped API. */
+  can(capability: PluginCapability | string): boolean;
+}
+interface PluginHostOptions {
+  /**
+   * Override the underlying `fetch`. Tests inject a stub here; production
+   * hosts leave this unset and use the global.
+   */
+  fetch?: typeof fetch;
+  /** Override `navigator.clipboard`. */
+  clipboard?: {
+    readText?(): Promise<string>;
+    writeText?(text: string): Promise<void>;
+  };
+  /**
+   * Override the host's notification surface. The default uses the
+   * browser's `Notification` API — fine for web hosts; native hosts
+   * (Tauri, Electron) inject their own.
+   */
+  showNotification?(title: string, options?: NotificationOptions): Promise<void>;
+}
+/**
+ * Build a `PluginHost` from a manifest. The set of granted capabilities
+ * is `manifest.capabilities.required ∪ optional`; runtime gates check
+ * membership before forwarding to the underlying API.
+ *
+ * Network capabilities support host patterns:
+ *   - `network`           — any host
+ *   - `network:api.foo.io` — exact match
+ *   - `network:*.foo.io`   — wildcard subdomain match
+ *   - `network:foo.io,bar.io` — comma-separated list
+ */
+declare function createPluginHost(manifest: Pick<PluginManifest, "id" | "capabilities">, options?: PluginHostOptions): PluginHost;
+/**
+ * Network capability matcher — `network`, `network:exact.host`,
+ * `network:*.wildcard.host`, `network:a,b,c` comma-list. Exported so
+ * the iframe sandbox can reuse the same rules without forking the
+ * vocabulary.
+ */
+declare function matchesNetworkCapability(granted: ReadonlySet<PluginCapability>, host: string): boolean;
+//#endregion
+//#region packages/plugin/src/sandbox.d.ts
+/** Public result of `loadSandboxedPlugin` — what the host actually keeps. */
+interface SandboxedPlugin {
+  /** Stable id from the manifest. */
+  pluginId: string;
+  /** Capabilities granted to this sandbox. */
+  capabilities: ReadonlySet<PluginCapability>;
+  /** The plugin's default export, copied across the postMessage boundary. */
+  exported: unknown;
+  /** Tear down: removes the iframe + closes the bridge. */
+  dispose(): void;
+}
+interface SandboxOptions extends PluginHostOptions {
+  /**
+   * Override the document the iframe attaches to. Tests inject a jsdom
+   * document; production hosts use the default `document` global.
+   */
+  doc?: Document;
+  /**
+   * Hard timeout (ms) on the plugin's `ready` handshake. Defaults to
+   * 10 s. Plugins that don't post `ready` within the window get the
+   * sandbox torn down + a load failure.
+   */
+  readyTimeoutMs?: number;
+}
+/**
+ * Spin up a sandboxed iframe, load the plugin bundle inside it, wait
+ * for the plugin to post `ready`, then return a handle. The host bridges
+ * capability-gated APIs to the iframe via postMessage.
+ */
+declare function loadSandboxedPlugin(manifest: Pick<PluginManifest, "id" | "capabilities">, artifactUrl: string, options?: SandboxOptions): Promise<SandboxedPlugin>;
+//#endregion
+export { type AbraAwarenessContribution, type AbraCommandItem, type AbraKeyboardShortcut, type AbraMentionItem, type AbraMentionProvider, type AbraNodePanelSlot, type AbraPlugin, type AbraSettingsPanel, type AbraTiptapExtension, type AbraYDoc, CapabilityDenied, type ClientPluginCtx, type CollaborationUser, type CommandPaletteCtx, type DragHandlePluginCtx, type EditorPluginCtx, type EditorRefLike, type ExternalPluginEntry, type GuardedClipboard, type GuardedFetch, type GuardedNotifications, type MentionPluginCtx, type NodePanelCtx, type PluginCapability, type PluginHost, type PluginHostOptions, type PluginManifest, type PluginManifestAuthor, type PluginManifestContributes, type PluginPricing, PluginRegistry, type PluginRegistryEntry, type PluginVersionStatus, type RefLike, type RunnerCleanup, type SandboxOptions, type SandboxedPlugin, type ServerRunnerContextBase, type ServerRunnerDefinition, createPluginHost, isSafePluginUrl, loadSandboxedPlugin, matchesNetworkCapability, normalizePluginUrl };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@abraca/plugin",
+  "version": "2.3.0",
+  "description": "Shared plugin contract + registry for @abraca/nuxt and cou-shell.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/abracadabra-plugin.cjs",
+  "module": "dist/abracadabra-plugin.esm.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "source": {
+      "import": "./src/index.ts"
+    },
+    "default": {
+      "import": "./dist/abracadabra-plugin.esm.js",
+      "require": "./dist/abracadabra-plugin.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "peerDependencies": {},
+  "devDependencies": {},
+  "scripts": {
+    "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"
+  }
+}