@artemis-studio/plugin-sdk 2026.9.37

package/README.md

@@ -0,0 +1,38 @@
+# @artemis-studio/plugin-sdk
+
+Build the UI of an [Artemis Studio](https://github.com/sudoitir/artemis-studio) plugin.
+
+- **Typings** for everything a plugin's UI may use from Studio: routes under Studio's own roots, slots,
+  navigation, the API client, permission checks and shared components. At runtime Studio provides
+  the SDK itself, so a plugin's bundle never contains a copy.
+- **A Vite preset** that builds the UI as a Module Federation remote taking React, Mantine and
+  TanStack from Studio.
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { studioPlugin } from '@artemis-studio/plugin-sdk/vite';
+
+export default defineConfig({ plugins: [react(), studioPlugin({ id: 'acme-notes' })] });
+```
+
+```tsx
+// src/feature.tsx
+import { createRoute } from '@tanstack/react-router';
+import { CONTRACT, clusterRoute, definePlugin, pluginPath, pluginView } from '@artemis-studio/plugin-sdk';
+
+const notes = createRoute({
+  getParentRoute: () => clusterRoute,
+  path: pluginPath('acme-notes', 'notes'),
+  component: pluginView('acme-notes', NotesView),
+});
+
+export default definePlugin({ contract: CONTRACT, id: 'acme-notes', routes: { cluster: [notes] } });
+```
+
+The SDK's version is the Studio version it was built from, and its peer dependencies are the exact
+React, Mantine and TanStack versions that Studio ships. Build against the SDK of the oldest Studio
+your plugin supports (`studio.since` in `plugin.json`).
+
+The guide: <https://sudoitir.github.io/artemis-studio/guide/plugins>.

package/index.js

@@ -0,0 +1,25 @@
+// Generated by build.mjs. Artemis Studio provides this module at runtime; these names exist so a
+// plugin's build knows what it imports. Running a plugin outside Studio fails here, loudly.
+const outsideStudio = (name) => () => {
+  throw new Error(`${name}: @artemis-studio/plugin-sdk is provided by Artemis Studio at runtime; load this plugin in Studio.`);
+};
+export const ApiError = outsideStudio('ApiError');
+export const CONTRACT = outsideStudio('CONTRACT');
+export const ConfirmByTyping = outsideStudio('ConfirmByTyping');
+export const NAV_GROUPS = outsideStudio('NAV_GROUPS');
+export const NodeOutcomeSummary = outsideStudio('NodeOutcomeSummary');
+export const OutcomeSummary = outsideStudio('OutcomeSummary');
+export const Pager = outsideStudio('Pager');
+export const SETTINGS_GROUPS = outsideStudio('SETTINGS_GROUPS');
+export const VirtualTable = outsideStudio('VirtualTable');
+export const clusterKey = outsideStudio('clusterKey');
+export const clusterRoute = outsideStudio('clusterRoute');
+export const definePlugin = outsideStudio('definePlugin');
+export const notify = outsideStudio('notify');
+export const pluginApi = outsideStudio('pluginApi');
+export const pluginPath = outsideStudio('pluginPath');
+export const pluginView = outsideStudio('pluginView');
+export const request = outsideStudio('request');
+export const rootRoute = outsideStudio('rootRoute');
+export const useCan = outsideStudio('useCan');
+export const useMe = outsideStudio('useMe');

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@artemis-studio/plugin-sdk",
+  "version": "2026.9.37",
+  "description": "Build the UI of an Artemis Studio plugin: typings for the Studio APIs a plugin may use, and a Vite preset.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sudoitir/artemis-studio.git",
+    "directory": "web/packages/plugin-sdk"
+  },
+  "homepage": "https://sudoitir.github.io/artemis-studio/guide/plugins",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/sdk/index.d.ts",
+      "default": "./index.js"
+    },
+    "./vite": {
+      "types": "./vite.d.ts",
+      "default": "./vite.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "shared.js",
+    "shared.d.ts",
+    "vite.js",
+    "vite.d.ts",
+    "peers.json",
+    "types",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "@mantine/core": "9.6.1",
+    "@mantine/hooks": "9.6.1",
+    "@tanstack/react-query": "5.103.1",
+    "@tanstack/react-router": "1.170.38",
+    "vite": ">=8"
+  },
+  "dependencies": {
+    "@module-federation/vite": "1.22.1"
+  }
+}

package/peers.json

@@ -0,0 +1,8 @@
+{
+  "react": "19.3.0",
+  "react-dom": "19.3.0",
+  "@mantine/core": "9.6.1",
+  "@mantine/hooks": "9.6.1",
+  "@tanstack/react-query": "5.103.1",
+  "@tanstack/react-router": "1.170.38"
+}

package/shared.d.ts

@@ -0,0 +1,3 @@
+export const SHARED_LIBRARIES: string[];
+export const SDK: string;
+export function packageOf(specifier: string): string;

package/shared.js

@@ -0,0 +1,24 @@
+/**
+ * The libraries a plugin's UI takes from Studio instead of bundling (ADR-0100): the ones holding
+ * React context or module state, where a second copy breaks hooks, routing, theming or the query
+ * cache. Studio's own build (web/vite.config.ts) shares exactly these, so the list lives here, once.
+ */
+export const SHARED_LIBRARIES = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@mantine/core',
+  '@mantine/hooks',
+  '@tanstack/react-query',
+  '@tanstack/react-router',
+];
+
+/** The SDK itself: always the running Studio's copy. */
+export const SDK = '@artemis-studio/plugin-sdk';
+
+/** The package a shared specifier belongs to: `react-dom/client` → `react-dom`. */
+export function packageOf(specifier) {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}

package/types/branding.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Single source of every user-visible product name on the web side.
+ * Mirror of `Branding.java`. See `docs/adr/0001-project-name-and-trademark-risk.md`.
+ *
+ * A rename is: this file, `Branding.java`, the Maven `artifactId`, the image
+ * coordinates, and `index.html` <title>. Nothing else.
+ */
+export declare const branding: {
+    readonly productName: "Artemis Studio";
+    readonly productShortName: "Studio";
+    readonly tagline: "Cluster-wide management and observability for Apache ActiveMQ Artemis";
+    readonly trademarkNotice: string;
+    readonly projectUrl: "https://github.com/sudoitir/artemis-studio";
+};

package/types/kernel/api/polling.d.ts

@@ -0,0 +1,50 @@
+import type { Query, QueryClient } from '@tanstack/react-query';
+/**
+ * `refetchInterval` for a hook that should stop polling while paused.
+ *
+ * Returning `false` suspends the interval; TanStack Query calls this again on the
+ * next cycle, so resuming needs no remount.
+ *
+ * ponytail: the interval is re-resolved when the *current* timer fires, so one
+ * further poll can land up to `ms` after pausing. Closing that gap means
+ * cancelling in-flight fetches, which throws away work the operator did not ask
+ * to discard and can leave a screen mid-update. Accepted and recorded in
+ * ADR-0055; revisit only if an operator can actually observe it.
+ */
+export declare function poll(ms: number | false): () => number | false;
+/**
+ * `refetchOnMount` for the QueryClient default, so pausing covers opening a view
+ * and not only the intervals.
+ *
+ * Pausing intervals but not mounts means an operator who pauses and then
+ * navigates has silently unpaused — every query the new screen observes is stale
+ * (the stream marks them so) and refetches on mount.
+ *
+ * A query that has never resolved is exempt: suspending its first fetch would hand
+ * the operator an empty screen. They paused a screen showing data to stop it
+ * moving, not to stop data existing.
+ */
+export declare function mountRefetch(): (query: Query) => boolean;
+export declare function isPollingPaused(): boolean;
+export declare function setPollingPaused(next: boolean): void;
+/** Record that the server said something changed while refreshing was paused. */
+export declare function markPendingChange(): void;
+export declare function usePollingPaused(): boolean;
+export declare function usePendingChange(): boolean;
+/**
+ * Refetch everything the current screen is observing, and resolve when it is done.
+ *
+ * `refetchType: 'active'` is the point: it refetches what is on the display and
+ * leaves the rest of the cache alone — the same scope the freshness indicator
+ * reports on, so the button and the label can never disagree.
+ *
+ * `cancelRefetch: false` is the other point. TanStack's default aborts the
+ * in-flight fetch and starts another, which is right after a mutation (the
+ * in-flight response is known-stale) and wrong for a refresh control (the
+ * in-flight response is exactly what was asked for). With it, a second activation
+ * joins the first instead of restarting it.
+ *
+ * The returned promise is what lets the control show *the operator's* refresh
+ * rather than every background poll.
+ */
+export declare function refreshActiveQueries(qc: QueryClient): Promise<void>;

package/types/kernel/api/request.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Transport to the Artemis Studio API: `request<T>()` and the RFC 9457 `ApiError`.
+ *
+ * DTO types come from `schema.d.ts`, generated by `openapi-typescript` from the
+ * backend's committed OpenAPI snapshot (`web/openapi.json`) — ADR-0019. Each
+ * feature's `api.ts` names the DTOs it uses and holds its own hooks and query
+ * keys, every cluster-scoped key under {@link clusterKey}.
+ */
+export declare const BASE = "/api/v1";
+/** A parsed `application/problem+json` body. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly title: string;
+    readonly brokerErrorKind?: string;
+    readonly fieldErrors: {
+        field: string;
+        message: string;
+    }[];
+    /**
+     * The whole `problem+json` body. Handlers attach extra properties to a problem
+     * — the offending token on a syntax error, the estimate and ceiling on a
+     * refused query — and a message with the number left out is not something an
+     * operator can act on.
+     */
+    readonly problem: Record<string, unknown>;
+    constructor(status: number, body: Record<string, unknown>);
+}
+export declare function request<T>(path: string, init?: RequestInit): Promise<T>;
+/** The root every cluster-scoped query key starts from, so invalidating a cluster reaches all of it. */
+export declare const clusterKey: (id: string, ...parts: unknown[]) => readonly ["clusters", string, ...unknown[]];
+/** The path a cluster-wide command is issued under. */
+export declare const lifecycleBase: (clusterId: string) => string;
+/**
+ * A lifecycle command names the cluster, not a node, and comes back as a
+ * per-node outcome. `dryRun` previews without touching any broker; `override`
+ * clears the bulk cap on a destroy, which is the only kind the cap applies to.
+ * A defined `dryRun` is always sent, `false` included: a real run must never be
+ * left to the server's default.
+ */
+export interface LifecycleVars {
+    dryRun?: boolean;
+    override?: boolean;
+}
+export declare function lifecycleQuery(dryRun?: boolean, override?: boolean): string;