@rigee/plugin-api 0.0.0-stage → 0.2.0

package/dist/host.js

@@ -0,0 +1,234 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+let host = null;
+/**
+ * Called by the shell, exactly once, before any plugin activates.
+ *
+ * Throwing on a second call is not pedantry: a second install means a second copy of this module
+ * got loaded, and the plugins that imported the first copy are now talking to a host the shell has
+ * stopped updating. That failure is invisible — components render, calls resolve, and one plugin's
+ * tabs quietly go to the wrong place. Far better to fail at the install.
+ */
+export function installShellHost(impl) {
+    if (host)
+        throw new Error('@rigee/plugin-api: the shell host is already installed');
+    host = impl;
+    Object.assign(icons, impl.icons);
+}
+/** True once the shell has installed itself. For the shell's own start-up assertions. */
+export function shellHostInstalled() {
+    return host !== null;
+}
+function shell() {
+    if (!host) {
+        throw new Error('@rigee/plugin-api: no shell host installed. Either this is being called outside Rigee, ' +
+            'or a second copy of @rigee/plugin-api was bundled into the plugin instead of being ' +
+            'left external and resolved through the import map.');
+    }
+    return host;
+}
+/**
+ * The shell's icons, filled in at install.
+ *
+ * A mutable object rather than named exports because named exports cannot be assigned from
+ * outside the module, and a per-icon forwarding component would add a React layer to every row of
+ * a file tree. After install these are the shell's own components, reached by one property read.
+ */
+export const icons = {};
+// ---------------------------------------------------------------------------
+// The functions. Each is a forward; the comments that matter are on ShellHost.
+// ---------------------------------------------------------------------------
+export const isMac = () => shell().isMac();
+export const monoFamily = () => shell().monoFamily();
+export const editorFontSize = () => shell().editorFontSize();
+export const activeWorkspaceId = () => shell().activeWorkspaceId();
+export const useActiveWorkspace = () => shell().useActiveWorkspace();
+export const workspaceDir = (workspace) => shell().workspaceDir(workspace);
+export const addWorkspaceFolders = (paths) => shell().addWorkspaceFolders(paths);
+export const removeWorkspaceFolders = (paths) => shell().removeWorkspaceFolders(paths);
+export const openTerminal = (request) => shell().openTerminal(request);
+export const popupMenu = (items) => shell().popupMenu(items);
+/**
+ * Open (or re-activate) a tab this plugin owns, in the active workspace's active group.
+ *
+ * Returns the tab's id, or null when there is no workspace to put it in. The view type must be one
+ * this plugin declared; the shell throws if it belongs to somebody else.
+ */
+export const openPluginTab = (pluginId, request) => shell().openPluginTab(pluginId, request);
+/**
+ * Open a file in whichever editor claims it.
+ *
+ * The resolution is the SHELL's — it reads the manifests, so no plugin is loaded to answer "who
+ * opens a .pdf" and the caller does not need to know that editors have priorities. This is what a
+ * file tree calls; before it existed the explorer reached into the store, invented a tab id and
+ * resolved the view type itself, which meant three shell internals in one click handler.
+ */
+export const openFile = (request) => shell().openFile(request);
+/**
+ * The editors that open this file only when asked — a Markdown file's preview — in the words to
+ * offer them in. What a file tree puts in a file's menu; picking one is `openFile({ viewType })`.
+ * Read off the manifests, so nothing is loaded to answer, and empty for most files.
+ */
+export const editorsOnRequest = (path) => shell().editorsOnRequest(path);
+export const patchPluginTab = (tabId, patch) => shell().patchPluginTab(tabId, patch);
+export const closePluginTab = (tabId) => shell().closePluginTab(tabId);
+/**
+ * Make this tab the one its column shows, and its column the active one. For content that takes
+ * the keyboard where the shell cannot see it — a click inside a native view — so that the shell's
+ * idea of "where the user is working", which every shortcut acts on, follows. A no-op when it is
+ * already so.
+ */
+export const activateTab = (tabId) => shell().activateTab(tabId);
+/**
+ * Every open tab of one of this plugin's own view types, across every workspace.
+ *
+ * Exists for one job: repairing tabs restored from a persisted state older than the plugin. The
+ * shell can move an old tab's fields into `state`, but it cannot invent a dedup key — only the
+ * plugin knows what identifies one of its tabs.
+ */
+export const pluginTabs = (viewType) => shell().pluginTabs(viewType);
+/**
+ * Every tab id that exists, in every group of every workspace.
+ *
+ * For plugins holding a resource per tab — a native browser view, a parsed document — that has to
+ * be released when the tab goes. Callers treat anything absent from this set as closed, so it spans
+ * every workspace deliberately: switching workspace must not read as "every tab was closed".
+ */
+export const liveTabIds = () => shell().liveTabIds();
+/** Watch for tabs disappearing. Wrap the returned undo in `ctx.effect` so it dies with the plugin. */
+export const subscribeTabs = (listener) => shell().subscribeTabs(listener);
+/**
+ * The tab this one was split from, or null.
+ *
+ * CONSUME-ONCE. Read it on first mount and keep what you got; the second caller, and every render
+ * after the first, gets null. StrictMode's double-invoked effect counts as a second caller, so this
+ * belongs in a `useState` initialiser or a ref, never in an effect body.
+ */
+export const duplicatedFrom = (tabId) => shell().duplicatedFrom(tabId);
+/**
+ * The one tab with the keyboard: the active group's active tab, in the active workspace.
+ *
+ * One rule, in one place. Two copies of it is how two visible panes end up disagreeing about which
+ * of them should be typing.
+ */
+export const focusedTabId = () => shell().focusedTabId();
+/** The same rule as a hook, for a pane that has to re-render when focus moves to another column. */
+export const useFocusedTabId = () => shell().useFocusedTabId();
+/**
+ * The active tab of every group in the active workspace, left to right.
+ *
+ * What is actually on screen. A plugin compositing something outside the DOM — a native view — has
+ * to know exactly this set, and only for the active workspace: the tabs of the workspace you
+ * switched away from are alive but not visible.
+ */
+export const mountedTabIds = () => shell().mountedTabIds();
+/** Fires when `mountedTabIds` changes — a split, a drag between groups, a workspace switch. */
+export const subscribeMountedTabs = (listener) => shell().subscribeMountedTabs(listener);
+/**
+ * A plugin's own persisted state for one workspace.
+ *
+ * Saved and restored with the workspace by the shell, which never looks inside it. For the things
+ * a panel wants to remember per project — which directories are expanded, a filter, a scroll
+ * position. Undefined means "nothing recorded yet", which is different from "recorded as empty":
+ * the file tree opens its root folders on first sight and must not do it again after the user
+ * collapses everything.
+ */
+export const pluginState = (pluginId, workspaceId) => shell().pluginState(pluginId, workspaceId);
+/** The same, as a hook. Null workspace yields undefined rather than throwing. */
+export const usePluginState = (pluginId, workspaceId) => shell().usePluginState(pluginId, workspaceId);
+/** Merge into this plugin's state for one workspace, and persist it. */
+export const setPluginState = (pluginId, workspaceId, patch) => shell().setPluginState(pluginId, workspaceId, patch);
+/**
+ * Say whether a file has unsaved changes, and how to save or drop them.
+ *
+ * The shell marks its tabs with a dot and, when one would close — or the app would quit — with
+ * the changes unsaved, asks the user and calls `save` or `discard`. Keyed by PATH, not tab: one
+ * document can be open in two columns, and it is the document that is unsaved.
+ */
+export const setFileDirty = (path, dirty, handlers) => shell().setFileDirty(path, dirty, handlers);
+/**
+ * Replace every decoration one source publishes, keyed by absolute path. A path ending in a
+ * separator covers the folder and everything inside it. An empty record withdraws the source.
+ * Folders above a decorated path take its colour, so collapsed trees still show where changes are.
+ */
+export const setFileDecorations = (source, decorations) => shell().setFileDecorations(source, decorations);
+/** The decoration to draw for a path. A hook: re-renders when that path's decoration changes. */
+export const useFileDecoration = (path) => shell().useFileDecoration(path);
+/**
+ * Where the cursor should go in the file this tab shows — the target of a search result or any
+ * other `openFile({ selection })`. A request made before the editor subscribed is delivered as it
+ * subscribes, so subscribe on mount. Wrap the returned undo in the unmount.
+ */
+export const onRevealInFile = (tabId, cb) => shell().onRevealInFile(tabId, cb);
+/**
+ * Called when the user asks for this side panel by keyboard — the panel should take the keyboard,
+ * as a search box does. Delivered on subscribe if the request came before the panel mounted.
+ */
+export const onViewRevealed = (viewId, cb) => shell().onViewRevealed(viewId, cb);
+/**
+ * Whether this tab was opened with `preserveFocus`, so its viewer should leave the keyboard where
+ * it is instead of taking it as it mounts. Answers true once, for the open that asked: call it at
+ * the moment the viewer would focus itself, not before.
+ */
+export const openedInBackground = (tabId) => shell().openedInBackground(tabId);
+/**
+ * Files a plugin has just renamed or moved for the user — a file tree's Rename, its Cut and Paste,
+ * a drag — so the tabs showing them follow, under their new names. A folder covers everything in
+ * it. Files moved by other programs are not reported here, and their tabs stay where they were.
+ */
+export const filesMoved = (moves) => shell().filesMoved(moves);
+/**
+ * Files a plugin has just deleted for the user. Their tabs close, and unsaved changes in them are
+ * dropped — so ask about those first, with `unsavedFiles`. A folder covers everything in it.
+ */
+export const filesDeleted = (paths) => shell().filesDeleted(paths);
+/** Which files at these paths, or inside them, have unsaved changes. */
+export const unsavedFiles = (paths) => shell().unsavedFiles(paths);
+/**
+ * Needs `files:read`. `notUtf8` means the bytes were not valid UTF-8 and `content` is a lossy
+ * decoding — show it, but never write it back.
+ */
+export const readFile = (path) => shell().readFile(path);
+/** Needs `files:write`. */
+export const writeFile = (path, content) => shell().writeFile(path, content);
+/** Needs `files:read`. */
+export const listDir = (path) => shell().listDir(path);
+/**
+ * Tokenise code with the text editor's own tokenizers: the tokens of each line, in order, or null
+ * when no language goes by that name. The name may be a language id, an alias or an extension —
+ * `ts`, `typescript` and `TypeScript` all find TypeScript — so a Markdown fence's word can be
+ * passed as it is.
+ *
+ * The tokens' text is the caller's: slice each line at the offsets. That is the point of asking
+ * for tokens rather than coloured HTML — HTML from the editor writes spaces as no-break spaces, so
+ * code copied out of it would not be the code that was written.
+ *
+ * Loads the editor's tokenizers the first time, which is megabytes: call it for code that is about
+ * to be shown, not speculatively. Since Rigee 1.1.0.
+ */
+export const tokenizeCode = (text, language) => shell().tokenizeCode(text, language);
+/**
+ * The URL to start a Web Worker from, for a script that ships with this plugin.
+ *
+ * A window may only start a worker from its own origin, and a plugin's files are served from
+ * another — `rigee-plugin://` — so `new Worker(new URL('./x.js', import.meta.url))` is refused.
+ * Pass the same URL here instead and start the worker from what comes back, as a module worker:
+ *
+ *   new Worker(workerUrl(new URL('./parse.worker.js', import.meta.url)), { type: 'module' })
+ *
+ * The script must be self-contained: a worker has no import map, so `react` and this package
+ * cannot be imported from inside one. Messages posted before the script has loaded are held until
+ * it has, and then delivered. The worker gets no Content Security Policy of its own, so it may
+ * compile WebAssembly, which the window may not. Since Rigee 1.1.0.
+ */
+export const workerUrl = (script) => shell().workerUrl(script);
+/**
+ * The shell's "this pane has nothing to show" state.
+ *
+ * A wrapper rather than an entry in `icons`, because a notice is rendered once per failed pane
+ * where an icon is rendered once per row — the extra component layer costs nothing here and reads
+ * better at the call site.
+ */
+export function Notice(props) {
+    const Impl = shell().Notice;
+    return _jsx(Impl, { ...props });
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@rigee/plugin-api` — everything a plugin is allowed to know about Rigee.
+ *
+ * A plugin should import from here and from nowhere else in the app. That is the whole point of
+ * the package: what is exported here is versioned and will be kept working, and what is not is the
+ * shell's own business and will be moved without warning.
+ *
+ * TWO ENTRY POINTS, and the split is load-bearing rather than tidy:
+ *
+ *   `@rigee/plugin-api`            the full surface. Needs a DOM and React. Renderer halves.
+ *   `@rigee/plugin-api/manifest`   the declarative contract alone: no React, no DOM, no runtime.
+ *
+ * The main process reads manifests too — to decide which plugin owns a command before importing a
+ * line of it — and importing this barrel there would drag React into a process that can never
+ * render. The same reason the manifests themselves hold no import thunks.
+ */
+export * from './data';
+export * from './manifest';
+export * from './ui';
+export * from './host';
+export * from './context';

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@rigee/plugin-api` — everything a plugin is allowed to know about Rigee.
+ *
+ * A plugin should import from here and from nowhere else in the app. That is the whole point of
+ * the package: what is exported here is versioned and will be kept working, and what is not is the
+ * shell's own business and will be moved without warning.
+ *
+ * TWO ENTRY POINTS, and the split is load-bearing rather than tidy:
+ *
+ *   `@rigee/plugin-api`            the full surface. Needs a DOM and React. Renderer halves.
+ *   `@rigee/plugin-api/manifest`   the declarative contract alone: no React, no DOM, no runtime.
+ *
+ * The main process reads manifests too — to decide which plugin owns a command before importing a
+ * line of it — and importing this barrel there would drag React into a process that can never
+ * render. The same reason the manifests themselves hold no import thunks.
+ */
+export * from './data';
+export * from './manifest';
+export * from './ui';
+export * from './host';
+export * from './context';

package/dist/manifest.d.ts

@@ -0,0 +1,331 @@
+/**
+ * The plugin contract, shared by main / preload / renderer.
+ *
+ * Rigee's core is a shell: a window, workspaces, a tab framework, terminals, persistence and the
+ * IPC spine. Everything that shows a document or a panel — the text editor, source control, the
+ * browser, the PDF viewer — is a plugin. This file is the contract they are written against.
+ *
+ * A plugin is not one object but up to two halves. Electron leaves no choice: a PDF renders in the
+ * sandboxed renderer, and the bytes it renders can only be read in main. So a plugin declares a
+ * `main` half and a `renderer` half, sharing an id and talking over one IPC channel.
+ *
+ * THREE RULES THAT SHAPE EVERYTHING HERE
+ *
+ * 1. This file holds the declarative part only — the shape read at boot to decide *what exists*.
+ *    Knowing that some plugin claims `*.pdf` must not cost the 437 kB of pdf.js that renders one.
+ *    The imperative halves load on demand, through the per-realm registries.
+ *
+ * 2. A manifest carries NO import thunks. They used to live here, and they cannot: TypeScript
+ *    resolves the literal specifier of a dynamic `import()` into the program, so one manifest
+ *    naming both halves drags the main half (node:fs) into the web project and the renderer half
+ *    (.tsx) into the node project. Both fail `tsc -b`. The thunks live in `registry.main.ts` and
+ *    `registry.renderer.ts`, each covered by exactly one tsconfig.
+ *
+ * 3. Contributions name components; they never hold them. cordis service access is between 700x
+ *    and 2000x the cost of a plain property read (measured: 15.5 us for `ctx.svc.method()` against
+ *    8 ns), so the framework stays on the activation path and every render-path lookup goes
+ *    through the plain Maps in the renderer's `bindings.ts`.
+ *
+ * This file is the root of `@rigee/plugin-api`, which is the version the two sides agree on. It
+ * must stay free of runtime imports: it is read at boot in main AND in the renderer, and anything
+ * it reaches lands in both bundles.
+ */
+/** Stable identity of a plugin. Namespaces its commands, its view types and its events. */
+export type PluginId = string;
+/**
+ * A view type is a `<pluginId>.<name>` pair, e.g. `pdf.preview`.
+ *
+ * Dotted rather than colon-separated so it stays distinguishable at a glance from an IPC channel
+ * (`fs:readFile`) and from a command (`pdf:read`) in a stack trace or a log line.
+ */
+export type ViewType = string;
+/**
+ * Icons a contribution may ask for, by name.
+ *
+ * A name rather than a component, because a manifest is read at boot in both realms and must stay
+ * plain data — a React element here would put the whole icon module, and with it a value import of
+ * React, into the main process. The names map to `src/renderer/src/icons.tsx`.
+ */
+export type IconName = 'file' | 'files' | 'diff' | 'globe' | 'terminal' | 'branch' | 'folder' | 'plugin' | 'search' | 'image' | 'video' | 'preview';
+/**
+ * A file matcher, in the only two forms worth supporting before someone asks for a third:
+ * an extension list, or a predicate on the absolute path.
+ *
+ * Deliberately not a glob. A glob library is 20 kB to express `*.pdf`, and the moment one appears
+ * in a manifest people start writing `**\/node_modules/**` in it and expecting gitignore
+ * semantics.
+ */
+export type FileSelector = 
+/** Lower-case, no leading dot: `['pdf']`. Matched against the path's final extension. */
+{
+    extensions: string[];
+} | {
+    match: (absolutePath: string) => boolean;
+};
+/** One editor a plugin contributes. Declared in the manifest, bound when the plugin activates. */
+export interface EditorContribution {
+    viewType: ViewType;
+    /** Shown in the "Open with" affordance and in the tab's tooltip. */
+    displayName: string;
+    selector: FileSelector;
+    icon?: IconName;
+    /**
+     * Higher wins when several editors claim the same file; ties break on manifest order.
+     *
+     * The text editor contributes at -Infinity and claims everything, so it is the floor: any other
+     * editor beats it, and a file nothing else claims still opens.
+     */
+    priority?: number;
+    /**
+     * Open a file in this editor only when the user asks for it by name, never because it claims the
+     * file — and say how they ask.
+     *
+     * For a second way of looking at a file that has a first one already: a Markdown file is source,
+     * written in the text editor, and its preview is something you ask for. Claiming `*.md` outright
+     * would take the editing away; claiming it at a priority below the text editor is impossible,
+     * because the text editor is the floor. So `priority` does not apply here, and the file opens in
+     * whatever else claims it — this editor is offered in its menu instead.
+     *
+     * Such an editor is taken to SHOW the file, never to edit it: its tab is not somewhere unsaved
+     * changes can be, so closing the file's own tab beside it still asks about them.
+     */
+    onRequest?: EditorRequest;
+}
+/** How an editor that opens only on request is asked for, and how its tabs read. */
+export interface EditorRequest {
+    /** The item in a file's menu that opens it: `Open Preview`. */
+    label: string;
+    /**
+     * Put before the file's name on the tab, so it reads apart from the file's own tab beside it:
+     * `Preview` gives `Preview README.md`.
+     */
+    tabPrefix?: string;
+}
+/**
+ * A tab type a plugin owns end to end — a browser tab, a diff.
+ *
+ * Distinct from an editor, which is "a viewer for a file the shell opened". A custom tab carries
+ * its own state and the shell knows nothing about it beyond what is declared here.
+ */
+export interface TabContribution {
+    viewType: ViewType;
+    displayName: string;
+    icon?: IconName;
+    /**
+     * Whether this tab shows a document — a diff does, a browser tab does not — which is how the
+     * tab strip tells files from everything else.
+     *
+     * It used to decide what the bulk-close commands reached. They reach every tab now, as in VS
+     * Code, and a program a sweep would stop is asked about instead.
+     */
+    isDocument?: boolean;
+    /**
+     * A tab kind from a persisted state older than the plugin system, to be rewritten into this
+     * view type on load.
+     *
+     * Migration lives in the manifest rather than in the shell so the shell keeps no list of the
+     * features it used to own. `sanitizeTabs` reads this; it is pure data and costs one scan.
+     */
+    legacyKind?: string;
+    /**
+     * What the split button does to a tab of this type: put a copy in the new group, or move it.
+     *
+     * Defaults to 'move', which is the safe answer — a plugin that has not thought about being in two
+     * places at once probably cannot be. A browser tab cannot: its native view is keyed by tab id, so
+     * a copy would either share the view or quietly start a second page with no session. A diff can,
+     * and should, because reading two revisions of the same file side by side is the point.
+     *
+     * The shell reads this from the manifest alone, so pressing split does not activate the plugin
+     * just to ask it.
+     */
+    split?: 'copy' | 'move';
+    /**
+     * Offer a button in the tab strip that opens a new one of these.
+     *
+     * The label is declarative, so the button exists before the plugin does; pressing it activates
+     * the plugin and asks the factory it bound for the new tab's title and initial state. That
+     * ordering is why the factory cannot live here: only the plugin knows what an empty browser tab
+     * is, and the whole point is not to have loaded it yet.
+     */
+    creatable?: {
+        label: string;
+    };
+}
+/**
+ * A panel in one of the two side bars.
+ *
+ * The left slot is an activity bar: one icon per view, one view visible at a time, the way VS Code
+ * arranges it. The right slot stacks whatever is contributed to it — source control lives there so
+ * the file tree and the changes stay visible together, which is the one thing this layout does
+ * better than VS Code's.
+ */
+export interface ViewContribution {
+    /** `<pluginId>.<name>`, like a view type: the same namespace rule, the same reason. */
+    id: ViewType;
+    title: string;
+    slot: 'left' | 'right';
+    /**
+     * The activity bar button. Required, not optional: a left-slot view with no icon would be a
+     * button nobody can identify, and an icon invented by the shell on its behalf would be worse.
+     */
+    icon: IconName;
+    /** Lower sorts first within a slot, and top to bottom in the activity bar. */
+    order?: number;
+}
+/** An item in the status bar. */
+export interface StatusBarContribution {
+    id: ViewType;
+    align: 'left' | 'right';
+    order?: number;
+}
+/**
+ * A component mounted at the shell root while the plugin is active — a modal, a prompt.
+ *
+ * Mounted on activation rather than at boot, which is what keeps this honest: the browser plugin's
+ * HTTP auth dialog cannot be needed before a browser view exists, and by then the plugin that owns
+ * the view is already loaded.
+ */
+export interface OverlayContribution {
+    id: ViewType;
+}
+export interface PluginContributions {
+    editors?: EditorContribution[];
+    tabs?: TabContribution[];
+    views?: ViewContribution[];
+    statusBar?: StatusBarContribution[];
+    overlays?: OverlayContribution[];
+}
+/**
+ * A capability a plugin must ASK FOR before the shell will give it.
+ *
+ * Deliberately coarse, and deliberately short. A long list of fine-grained permissions reads well
+ * in a design document and is worthless in a dialog: nobody can weigh nine checkboxes, so everyone
+ * presses yes, and the nine were only ever a way of not deciding which three mattered. These four
+ * are the ones a reviewer can actually reason about.
+ *
+ * BE CLEAR ABOUT WHAT THESE DO, BECAUSE IT IS NOT WHAT THE WORD "PERMISSION" SUGGESTS. Nothing
+ * enforces them at the call site, and nothing can in this architecture: a main half is an ES module
+ * in the main process and imports `node:fs` itself, and a renderer half runs in the shell's own
+ * JavaScript context and can reach `window.rigee` directly. A declaration is a statement of intent,
+ * not a capability the shell hands over and can withhold.
+ *
+ * What they are actually for is CHANGE DETECTION, and that part is enforced. The set is recorded
+ * with the trust grant, so a plugin that asked only to read files and comes back next version
+ * wanting to run programs cannot be silently loaded — approval is withdrawn and the user is asked
+ * again. Nobody re-reads a plugin they already trusted; this is the moment they would.
+ *
+ * Real enforcement needs a separate context per plugin — a worker for the logic, a locked-down
+ * frame for the UI, every contribution point becoming a message — which is a much larger change
+ * and is not pretended at here. Installing a plugin runs its code with the application's
+ * privileges, and Rigee's install dialog says exactly that.
+ */
+export type PluginPermission = 
+/** Read files anywhere the user can. Any viewer needs this. */
+'files:read'
+/** Write files. The text editor needs it; a reader does not. */
+ | 'files:write'
+/** Run programs. Source control needs it to run `git`; almost nothing else should. */
+ | 'process:spawn'
+/** Reach the network, directly or by showing a remote page. */
+ | 'net';
+export declare const ALL_PERMISSIONS: readonly PluginPermission[];
+/** One line each, for the install dialog. The user reads these, not the identifiers. */
+export declare const PERMISSION_LABELS: Record<PluginPermission, string>;
+/**
+ * What the host reads at boot.
+ *
+ * Shaped so it can move into a plugin's `package.json` unchanged once plugins load from disk
+ * rather than from the bundled barrel — `id`/`version`/`displayName`/`contributes` are the same
+ * four fields VS Code reads, for the same reason. A plugin on disk supplies exactly this object
+ * under a `rigee` key, plus the two entry points (see `DiskPluginManifest`).
+ */
+export interface PluginManifest {
+    id: PluginId;
+    version: string;
+    displayName: string;
+    description?: string;
+    /**
+     * What it needs to be allowed to do. Absent means none, and a plugin that asks for nothing is
+     * installable without a prompt beyond "this code will run inside rigee".
+     */
+    permissions?: PluginPermission[];
+    contributes?: PluginContributions;
+}
+/**
+ * The extra fields a plugin loaded FROM DISK carries, on top of the manifest itself.
+ *
+ * Bundled plugins do not need them: their halves are reached through `registry.main.ts` and
+ * `registry.renderer.ts`, which the build resolves statically. A plugin from somebody else's
+ * repository has no such entry, so it names its own files — relative to its own directory, and
+ * checked for containment before anything is read.
+ */
+export interface DiskPluginManifest extends PluginManifest {
+    /** ESM entry for the main half, relative to the plugin directory. Omit if it has none. */
+    main?: string;
+    /** ESM entry for the renderer half, relative to the plugin directory. Omit if it has none. */
+    renderer?: string;
+    /**
+     * Major version of `@rigee/plugin-api` this was built against.
+     *
+     * Checked before anything is loaded. A plugin built against a contract the shell no longer
+     * speaks must be refused with that as the reason, not allowed to fail later as a missing export
+     * in a stack trace nobody can act on.
+     */
+    apiVersion: number;
+    /**
+     * The oldest Rigee this runs in, as a version: `1.1.0`. Omit if any Rigee that speaks
+     * `apiVersion` will do.
+     *
+     * The other half of what `apiVersion` cannot say. Adding a function to this package does not
+     * bump `apiVersion`, because a plugin that never calls it is unaffected — but a plugin that DOES
+     * call it fails to link in an older shell, whose copy of the package has no such export, and the
+     * error names a module rather than the problem. Declaring the version that added the function
+     * turns that into a refusal at discovery, with "needs Rigee X" as the reason.
+     */
+    minAppVersion?: string;
+}
+/**
+ * The API generation the shell implements.
+ *
+ * Bumped when something is REMOVED or changed shape — adding a function does not break a plugin
+ * that never calls it. A disk plugin whose `apiVersion` differs is refused at discovery.
+ */
+export declare const PLUGIN_API_VERSION = 1;
+/**
+ * Every renderer→main plugin call rides one channel, `plugin:invoke`.
+ *
+ * The alternative was to let plugins add entries to `REQUEST_CHANNELS`, which would mean the
+ * preload allowlist is no longer a literal — it would have to be assembled at runtime from
+ * whatever main happens to have loaded, and a static allowlist that is actually static is worth
+ * more than the ergonomics of a per-plugin channel name. So the allowlist grows by exactly two
+ * entries, once, and never again.
+ *
+ * Authorisation lives in main: `plugin:invoke` reaches the command registry, and a command that
+ * was never registered is rejected there. Registration is where the namespace rule is enforced —
+ * a plugin may only register commands prefixed with its own id, so one plugin cannot shadow
+ * another's.
+ */
+export interface PluginInvocation {
+    /** `<pluginId>:<verb>`, e.g. `pdf:read`. */
+    command: string;
+    payload: unknown;
+}
+/**
+ * The other direction: main→renderer push, also on one channel.
+ *
+ * Plugins need this for anything they do not own the timing of — a git status arriving because a
+ * watcher fired, a page finishing its navigation. The envelope carries the plugin id so the
+ * renderer can hand the payload to that plugin's listeners without every plugin seeing every
+ * other plugin's events.
+ */
+export interface PluginEventEnvelope {
+    pluginId: PluginId;
+    /** Plugin-local name, NOT prefixed: `status`, not `scm:status`. */
+    event: string;
+    payload: unknown;
+}
+/** Prefix a command must carry to be registerable by `id`. */
+export declare function commandNamespace(id: PluginId): string;
+/** Prefix a view type, tab type, view or status bar item must carry to belong to `id`. */
+export declare function viewNamespace(id: PluginId): string;
+export declare function matchesSelector(selector: FileSelector, absolutePath: string): boolean;