@rigee/plugin-api 0.0.0-stage → 0.2.0

package/dist/manifest.js

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+export const ALL_PERMISSIONS = [
+    'files:read',
+    'files:write',
+    'process:spawn',
+    'net'
+];
+/** One line each, for the install dialog. The user reads these, not the identifiers. */
+export const PERMISSION_LABELS = {
+    'files:read': 'Read files on this computer',
+    'files:write': 'Create and change files on this computer',
+    'process:spawn': 'Run other programs',
+    net: 'Send and receive data over the network'
+};
+/**
+ * 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 const PLUGIN_API_VERSION = 1;
+/** Prefix a command must carry to be registerable by `id`. */
+export function commandNamespace(id) {
+    return `${id}:`;
+}
+/** Prefix a view type, tab type, view or status bar item must carry to belong to `id`. */
+export function viewNamespace(id) {
+    return `${id}.`;
+}
+export function matchesSelector(selector, absolutePath) {
+    if ('match' in selector)
+        return selector.match(absolutePath);
+    const dot = absolutePath.lastIndexOf('.');
+    const slash = Math.max(absolutePath.lastIndexOf('/'), absolutePath.lastIndexOf('\\'));
+    if (dot < 0 || dot < slash)
+        return false;
+    const ext = absolutePath.slice(dot + 1).toLowerCase();
+    return selector.extensions.some((e) => e.toLowerCase() === ext);
+}

package/dist/ui.d.ts

@@ -0,0 +1,106 @@
+/**
+ * What the shell hands a plugin's components, and what it expects back.
+ *
+ * Types only — there is no React value import here, and there must not be. This module is read by
+ * the main process too (a manifest is validated in both realms), and pulling React into main would
+ * cost every launch several milliseconds to load a library it can never render with.
+ *
+ * These used to live in the shell's `plugins/bindings.ts`, which is also where they are still
+ * implemented. The split is deliberate: the SHAPE is public and versioned with this package, the
+ * Maps that hold the components are private to the shell and may be rewritten at will.
+ */
+import type { ComponentType, ReactNode } from 'react';
+/** What every plugin-contributed editor receives. Kept to the two things a viewer cannot infer. */
+export interface PluginEditorProps {
+    /** Absolute path of the file to show. */
+    filePath: string;
+    /** The tab this instance belongs to; the right key for any per-tab state a viewer keeps. */
+    tabId: string;
+    readOnly: boolean;
+}
+/** What a plugin-owned tab receives: its own persisted state, and the way to change it. */
+export interface PluginTabProps {
+    tabId: string;
+    state: Record<string, unknown>;
+    /** Merged into the tab's state and persisted with it. */
+    patchState: (patch: Record<string, unknown>) => void;
+    /**
+     * Rename the tab in the strip, and optionally give it a hover tooltip.
+     *
+     * The tooltip is a second argument rather than a second function because the two always change
+     * together: a page navigates and both its title and its URL are new.
+     */
+    setTitle: (title: string, tooltip?: string) => void;
+}
+/** What a side-bar panel receives. The shell owns the rail and the collapse affordance. */
+export interface PluginViewProps {
+    onCollapse: () => void;
+}
+export type PluginEditorComponent = ComponentType<PluginEditorProps>;
+export type PluginTabComponent = ComponentType<PluginTabProps>;
+export type PluginViewComponent = ComponentType<PluginViewProps>;
+/**
+ * No props at all. `Record<never, never>` rather than `Record<string, never>`: the latter carries
+ * an index signature, and React's JSX check then rejects the `key` the shell has to put on every
+ * item it maps over.
+ */
+export type PluginStatusItemComponent = ComponentType<Record<never, never>>;
+export type PluginOverlayComponent = ComponentType<Record<never, never>>;
+/** What a plugin returns when the shell asks it for a fresh tab of its own type. */
+export type PluginTabFactory = () => {
+    title: string;
+    state: Record<string, unknown>;
+    key?: string;
+};
+/** Props every icon in `icons` accepts. */
+export interface IconProps {
+    size?: number;
+    className?: string;
+}
+/**
+ * The shell's icon set, so a plugin draws the same chevron the file tree does.
+ *
+ * An object of components rather than one `<Icon name="…">`, because the file tree renders one per
+ * row and an extra component layer per row is a real cost in a 5,000-entry directory. The object
+ * is filled in when the shell installs its host (see `host.ts`), so a property read at render time
+ * is all it costs.
+ */
+export interface IconSet {
+    Terminal: ComponentType<IconProps>;
+    File: ComponentType<IconProps>;
+    Files: ComponentType<IconProps>;
+    Diff: ComponentType<IconProps>;
+    Globe: ComponentType<IconProps>;
+    Folder: ComponentType<IconProps>;
+    AddFolder: ComponentType<IconProps>;
+    NewFile: ComponentType<IconProps>;
+    Plugin: ComponentType<IconProps>;
+    Plus: ComponentType<IconProps>;
+    Close: ComponentType<IconProps>;
+    Gear: ComponentType<IconProps>;
+    Split: ComponentType<IconProps>;
+    Branch: ComponentType<IconProps>;
+    Stage: ComponentType<IconProps>;
+    Unstage: ComponentType<IconProps>;
+    Discard: ComponentType<IconProps>;
+    Back: ComponentType<IconProps>;
+    Forward: ComponentType<IconProps>;
+    Reload: ComponentType<IconProps>;
+    Stop: ComponentType<IconProps>;
+    DevTools: ComponentType<IconProps>;
+    ExpandAll: ComponentType<IconProps>;
+    CollapseAll: ComponentType<IconProps>;
+    CollapseLeft: ComponentType<IconProps>;
+    CollapseRight: ComponentType<IconProps>;
+    Search: ComponentType<IconProps>;
+    Image: ComponentType<IconProps>;
+    Video: ComponentType<IconProps>;
+    /** The one icon with a state: `open` rotates it. */
+    Chevron: ComponentType<IconProps & {
+        open?: boolean;
+    }>;
+}
+export interface NoticeProps {
+    children: ReactNode;
+    tone?: 'muted' | 'error';
+}

package/dist/ui.js

@@ -0,0 +1,12 @@
+/**
+ * What the shell hands a plugin's components, and what it expects back.
+ *
+ * Types only — there is no React value import here, and there must not be. This module is read by
+ * the main process too (a manifest is validated in both realms), and pulling React into main would
+ * cost every launch several milliseconds to load a library it can never render with.
+ *
+ * These used to live in the shell's `plugins/bindings.ts`, which is also where they are still
+ * implemented. The split is deliberate: the SHAPE is public and versioned with this package, the
+ * Maps that hold the components are private to the shell and may be rewritten at will.
+ */
+export {};

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@rigee/plugin-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The contract a Rigee plugin is written against.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./data": {
+      "types": "./dist/data.d.ts",
+      "default": "./dist/data.js"
+    },
+    "./context": {
+      "types": "./dist/context.d.ts",
+      "default": "./dist/context.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "cordis": ">=4.0.0-rc.10",
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "cordis": { "optional": true },
+    "react": { "optional": true }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Qyuan-Tech/rigee.git",
+    "directory": "packages/plugin-api"
+  }
+}