@rahdar/plugin-sdk 0.0.0 → 2026.10.51

package/types/ui/table/HeaderCell.d.ts

@@ -0,0 +1,25 @@
+import type { PointerEvent } from 'react';
+import type { Column } from './columns.ts';
+import type { HeaderSorting } from './sort.ts';
+interface HeaderCellProps<T> {
+    /** A `div` with the `columnheader` role in the grid, a native `th` in the static table. */
+    as: 'div' | 'th';
+    column: Column<T>;
+    /** Null when the column cannot sort here. */
+    sorting: HeaderSorting | null;
+    onSort: () => void;
+    /** The grid's resize handle and its fit-to-content double-click; the static table has neither. */
+    resize?: {
+        onStart: (e: PointerEvent<HTMLElement>) => void;
+        onFit: () => void;
+    };
+    /** Where the cell is in the grid's focus model, and its 1-based `aria-colindex`. */
+    grid?: {
+        col: number;
+        index: number;
+    };
+    className?: string;
+}
+/** A column's header cell, shared by both renderers: its name or sort button, and the border handle that resizes it. */
+export declare function HeaderCell<T>({ as: Tag, column, sorting, onSort, resize, grid, className, }: Readonly<HeaderCellProps<T>>): import("react").JSX.Element;
+export {};

package/types/ui/table/MiddleTruncate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * An identifier shortened in the middle: the start shrinks and the last characters stay, so names that
+ * share a prefix (`DLQ.orders.a1b2…`, `DLQ.orders.c3d4…`) stay distinguishable. The full value is the
+ * cell's `title` and its reveal panel, and the clipped start stays in the DOM, so it can still be
+ * selected and read.
+ *
+ * The two parts are hidden from assistive technology and from `getByText`, which read the whole value from
+ * one visually hidden span instead: read in pieces, the parts come out as two words with a space between.
+ *
+ * Outside a table, where no cell offers the full value, `tooltip` names it on hover and on keyboard focus:
+ * the shortened name takes a tab stop only while it is actually shortened.
+ *
+ * The ellipsis is the tail's own leading mark, shown only while the start is clipped. `text-overflow`
+ * would put it right after the last whole character of the start and leave the rest of the start's box
+ * empty between it and the tail: a gap of up to one character. Here the start's box ends exactly where
+ * the ellipsis begins, so the start, the ellipsis and the tail abut.
+ */
+export declare function MiddleTruncate({ text, tooltip }: Readonly<{
+    text: string;
+    tooltip?: boolean;
+}>): import("react").JSX.Element;

package/types/ui/table/StaticTable.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+import type { TableModel } from './DataTable.tsx';
+/**
+ * The small, read-only renderer of `DataTable` (ADR-0160): a native `<table>` through Mantine's
+ * `Table`, with tabular figures, a header that sticks to the page, and the same column model and
+ * solver as the grid. The layout is fixed, so the solved widths hold and an identifier or code value
+ * is shortened by its kind (middle or end) instead of widening its column. Not virtualised, so cells
+ * hold natively focusable controls and the keyboard needs no grid model. `DataTable` switches to the
+ * grid above 200 rows.
+ */
+export declare function StaticTable<T>({ model, caption }: Readonly<{
+    model: TableModel<T>;
+    caption?: ReactNode;
+}>): import("react").JSX.Element;

package/types/ui/table/TableStates.d.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+/** How many placeholder rows a table that is loading shows. */
+export declare const SKELETON_ROWS = 8;
+/**
+ * The grid's loading rows: placeholders under the header, in the same tracks and at the density's
+ * row height, so the page does not move when the rows arrive. Hidden from assistive technology and
+ * outside `role="grid"`; `LoadingLabel` says what is loading.
+ */
+export declare function SkeletonRows({ tracks }: Readonly<{
+    tracks: number;
+}>): import("react").JSX.Element;
+/** The static table's loading rows. */
+export declare function SkeletonTableRows({ columns }: Readonly<{
+    columns: number;
+}>): import("react").JSX.Element;
+/** What a screen reader hears while the placeholders show. */
+export declare function LoadingLabel({ label }: Readonly<{
+    label: string;
+}>): import("react").JSX.Element;
+/**
+ * The thin bar over a table whose rows stay visible while they are fetched again. Its track is
+ * always there, so the table does not move when a refetch starts.
+ */
+export declare function RefetchBar({ active }: Readonly<{
+    active: boolean;
+}>): import("react").JSX.Element;
+/**
+ * The empty or error content, a sibling of the grid and never a child of it. `reserveRows` keeps it at
+ * least that many rows tall, less the gap the frame puts above it: the height the loading rows had, so
+ * a failure in place of them moves nothing below.
+ */
+export declare function StateSlot({ children, reserveRows }: Readonly<{
+    children: ReactNode;
+    reserveRows?: number;
+}>): import("react").JSX.Element;

package/types/ui/table/columns.d.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react';
+/** What a column holds. It sets the column's bounds, font and how an overlong value is shortened. */
+export type ColumnKind = 'text' | 'identifier' | 'code' | 'number' | 'time' | 'status';
+/**
+ * How much a column matters when the table is too narrow for all of them. `essential` is never hidden;
+ * `low` goes before `high`. The first data column and any column that names the node a row came from
+ * are `essential`.
+ */
+export type ColumnPriority = 'essential' | 'high' | 'low';
+export interface Column<T> {
+    id: string;
+    header: string;
+    /**
+     * What the header cell draws when `header` is too long for the column, which is then as wide as its
+     * figures. `header` stays the column's name: the Columns menu, the announcements and assistive
+     * technology use it, and `description` says what the short label stands for.
+     */
+    short?: string;
+    /** The plain value of the cell: what is measured, copied, revealed and put in its `title`. */
+    accessor: (row: T) => unknown;
+    cell?: (row: T) => ReactNode;
+    kind: ColumnKind;
+    priority: ColumnPriority;
+    /** Bounds in `ch`, overriding the kind's. */
+    min?: number;
+    max?: number;
+    /** Whether the column shares spare width, overriding the kind's. */
+    grow?: boolean;
+    /**
+     * The cell is drawn as a `StatusBadge`, whose padding and border widen it beyond its text, so the
+     * Measurer sizes it with them. Plain-word `status` columns (a type, "yes"/"no") are not badges.
+     */
+    badge?: boolean;
+    /** Static table only: wrap the value instead of shortening it. */
+    wrap?: boolean;
+    /** The `sort` query value this column sorts by, if sortable. */
+    sortKey?: string;
+    description?: string;
+}
+interface KindPreset {
+    /** Bounds in `ch`; a kind without them is as wide as its content. */
+    min?: number;
+    max?: number;
+    grow: boolean;
+    truncate: 'end' | 'middle' | 'none';
+    mono: boolean;
+}
+export declare const KIND_PRESETS: Record<ColumnKind, KindPreset>;
+export {};

package/types/ui/table/density.d.ts

@@ -0,0 +1,13 @@
+export type Density = 'compact' | 'comfortable';
+/** The browser-storage key `public/boot-prefs.js` reads before the first paint (ADR-0162). */
+export declare const DENSITY_KEY = "as:density";
+/** The density a control would switch to, named for what it does, shared by the user menu and the palette. */
+export declare function densityToggleLabel(density: Density): string;
+/**
+ * The viewer's table density, for every table (ADR-0162): a per-browser preference, not part of the URL.
+ *
+ * Storage is read synchronously, so the first render already uses it; `boot-prefs.js` has put the same
+ * value on `<html data-density>` before React ran, and the hook keeps that attribute in step afterwards.
+ * A consumer that sizes rows in JavaScript reads the height from the theme's `other.density[density]`.
+ */
+export declare function useDensity(): [Density, (density: Density) => void];

package/types/ui/table/gridFind.d.ts

@@ -0,0 +1,7 @@
+import type { Column } from './columns.ts';
+/** The zero-based positions of the rows with a shown cell that contains the query, ignoring case. */
+export declare function findRows<T>(columns: readonly Column<T>[], data: readonly T[], query: string): number[];
+/** The match after or before the current one, wrapping at both ends; -1 where there are none. */
+export declare function stepMatch(current: number, count: number, by: 1 | -1): number;
+/** What the find says about its result, for the eye and for a screen reader. */
+export declare function findSummary(query: string, count: number, current: number): string;

package/types/ui/table/index.d.ts

@@ -0,0 +1,5 @@
+export { DataTable, STATIC_ROW_LIMIT, type DataTableProps, type TableToolbar } from './DataTable.tsx';
+export { KIND_PRESETS, type Column, type ColumnKind, type ColumnPriority } from './columns.ts';
+export { DENSITY_KEY, densityToggleLabel, useDensity, type Density } from './density.ts';
+export type { RowMenu, RowMenuContext } from './GridTable.tsx';
+export { MiddleTruncate } from './MiddleTruncate.tsx';

package/types/ui/table/layout.d.ts

@@ -0,0 +1,48 @@
+import type { ColumnPriority } from './columns.ts';
+/** A column as the solver sees it: every width in px. */
+export interface SolverColumn {
+    id: string;
+    /** The measured width of the column's content. */
+    intrinsic: number;
+    min: number;
+    max: number;
+    grow: boolean;
+    /** Whether its values can be shortened, so the column may go down to `min`. */
+    truncates: boolean;
+    priority: ColumnPriority;
+    /** A width the operator set. It is kept exactly: never clamped and never shrunk. */
+    userWidth?: number;
+    /** The operator chose to show this column, so it is never hidden. */
+    userShown?: boolean;
+    /** Never hidden, whatever its priority (a node-attribution column). */
+    essential?: boolean;
+}
+export interface SolveResult {
+    /** `grid-template-columns` for the visible data columns, in order. The select and actions columns are the renderer's. */
+    template: string;
+    /** The px width each visible column gets once the grid is laid out, keyed by column id. */
+    widths: Record<string, number>;
+    /** The ids of the hidden columns, in column order. */
+    hidden: string[];
+    /** Even the shortest widths do not fit: the table scrolls sideways. */
+    overflow: boolean;
+}
+/**
+ * Lays the columns out in `W` px, the grid's inline size; `fixed` is the px of the select and actions
+ * columns the renderer adds beside them. Pure, and the only place the table decides what fits.
+ *
+ * 1. A width the operator set is a hard track.
+ * 2. When everything fits, grow columns get `minmax(base, 1fr)` and the rest their base.
+ * 3. Otherwise truncatable columns shrink toward their minimum.
+ * 4. Otherwise `low`, then `high`, columns are hidden, inline end first. `prev` supplies the
+ *    hysteresis. Essential columns, the first data column and columns the operator chose to show stay.
+ * 5. Otherwise the minimums are used and the table overflows.
+ *
+ * `W === 0` (no layout yet, as in jsdom) shows every column at its base.
+ */
+export declare function solveColumns(input: {
+    W: number;
+    cols: SolverColumn[];
+    prev?: SolveResult;
+    fixed?: number;
+}): SolveResult;

package/types/ui/table/measure.d.ts

@@ -0,0 +1,16 @@
+import { type RefObject } from 'react';
+import type { MeasureColumn } from './measurement.ts';
+interface MeasurerProps {
+    fields: MeasureColumn[];
+    sample: string[][];
+    rootRef: RefObject<HTMLDivElement | null>;
+}
+/**
+ * Where column widths come from (ADR-0161): an `inert`, `aria-hidden`, zero-size box, clipped so it
+ * can never widen the page, holding a `max-content` grid of the header and a sample of the values.
+ * Each cell is in its kind's font and bounded in `ch`, so a track's width is already clamped, and
+ * because the grid does not depend on the table's own width, what it reports cannot lock a column at
+ * the width it was stretched to.
+ */
+export declare const Measurer: import("react").NamedExoticComponent<Readonly<MeasurerProps>>;
+export {};

package/types/ui/table/measurement.d.ts

@@ -0,0 +1,92 @@
+import { type RefObject } from 'react';
+import { type Column } from './columns.ts';
+/** What a column is, once its kind's preset and its own overrides are resolved. */
+export interface ColumnSpec {
+    /** Bounds in `ch`; a column without them is as wide as its content. */
+    min?: number;
+    max?: number;
+    grow: boolean;
+    /** Whether the solver may take it below its content width, by shortening or wrapping the value. */
+    truncates: boolean;
+    truncate: 'end' | 'middle' | 'none';
+    mono: boolean;
+    /** Text-like kinds are the ones whose longest values are sampled. */
+    textLike: boolean;
+    /** Figures and times: tabular digits. */
+    tabular: boolean;
+    alignEnd: boolean;
+    /** Drawn as a `StatusBadge`: its padding and border are measured with the text. */
+    badge: boolean;
+}
+export declare function columnSpec<T>(column: Column<T>): ColumnSpec;
+/** The text of a cell whose column draws nothing of its own: the value, or nothing for none. */
+export declare function cellText(value: unknown): string;
+/**
+ * What the Measurer renders: the text of the first rows of the page, then the longest values of each
+ * text-like column beyond them, one row each with the other cells empty. One string per column.
+ */
+export declare function sampleRows<T>(columns: Column<T>[], data: readonly T[]): string[][];
+/** The px of the things a `ch` or a `rem` stands for, which the solver needs and only layout knows. */
+export interface Metrics {
+    /** One `ch` of the UI typeface and of the monospace one. */
+    ch: number;
+    mono: number;
+    /** A cell's padding on both sides. */
+    pad: number;
+    /** The select and actions columns. */
+    select: number;
+    actions: number;
+}
+interface Measurement {
+    metrics: Metrics;
+    /** The px each column's content needs, padding included and already clamped to its bounds. */
+    intrinsic: Record<string, number>;
+}
+/** Reads the Measurer's layout: the probes, then the header row, which is where each track's width shows. */
+export declare function readMeasurement(root: HTMLElement | null, ids: readonly string[]): Measurement | null;
+/** What the Measurer draws for one column. */
+export interface MeasureColumn {
+    id: string;
+    header: string;
+    sortable: boolean;
+    spec: ColumnSpec;
+}
+interface MeasurementInput<T> {
+    columns: Column<T>[];
+    data: readonly T[];
+    density: string;
+    /** Whether the viewer is in the table, so live growth must wait. */
+    isBusy: () => boolean;
+    /**
+     * Whether the table has a width, so its Measurer has a layout to read. A table inside a hidden tab
+     * has none; it is measured when it is first shown, never from a read that saw nothing.
+     */
+    shown: boolean;
+}
+interface MeasurementResult {
+    measurement: Measurement;
+    /** The props of the Measurer, which the table renders inside its frame so it inherits the table's type. */
+    measurerProps: {
+        fields: MeasureColumn[];
+        sample: string[][];
+        rootRef: RefObject<HTMLDivElement | null>;
+    };
+    /** Measures again, at once and from scratch (a double-click on a column border). */
+    refit: () => void;
+    /** Applies growth that was held back, once the viewer has left the table. */
+    resume: () => void;
+}
+/**
+ * Measures the columns when, and only when, ADR-0161 says to, in a layout effect so it is before
+ * paint: the first non-empty data, a change to the column set, fonts finishing loading, a density
+ * change, and an explicit refit. Rows that arrive later can only widen columns, at most every
+ * 2 seconds, and never while the viewer is reading the table.
+ */
+export declare function useMeasurement<T>({ columns, data, density, isBusy, shown, }: Readonly<MeasurementInput<T>>): MeasurementResult;
+/**
+ * Reports the inline size of an element now and whenever it changes, from one ResizeObserver that
+ * is throttled to a frame. Never from scroll. Reads `clientWidth`, so where there is no layout
+ * (jsdom) it is 0, which the solver takes as "show every column at its base".
+ */
+export declare function useInlineSize(ref: RefObject<HTMLElement | null>, onSize: (px: number) => void): void;
+export {};

package/types/ui/table/menuAnchor.d.ts

@@ -0,0 +1,12 @@
+/** A viewport point the menu opens from: the pointer, or just under the control that opened it. */
+export interface MenuAnchor {
+    x: number;
+    y: number;
+}
+/** The anchor just under an element, at its inline start, for a menu opened from the keyboard. */
+export declare function anchorBelow(element: Element): MenuAnchor;
+/**
+ * Keeps an anchor inside the viewport. A point outside it counts as a hidden reference, and the
+ * positioning engine then hides the menu outright rather than showing it at the edge.
+ */
+export declare function clampToViewport(anchor: MenuAnchor): MenuAnchor;

package/types/ui/table/rovingGrid.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The keyboard model of a data grid (ADR-0108): one tab stop, and the WAI-ARIA APG grid keys to
+ * move between cells. Pure, so the moves are tested apart from any rendering.
+ *
+ * <p>Row 0 is the header row; body rows are 1…`rows`. Columns are 0…`cols - 1` in visual order.
+ */
+export interface GridPos {
+    row: number;
+    col: number;
+}
+interface GridShape {
+    /** Body rows; the header row is added on top as row 0. */
+    rows: number;
+    cols: number;
+    /** Rows a Page Up / Page Down moves by. */
+    page: number;
+    /** In a right-to-left page, ArrowLeft moves toward the end of the row. */
+    rtl?: boolean;
+}
+interface GridKey {
+    key: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+}
+/**
+ * Where a key moves focus from `pos`, or null when the key is not a movement key. A move past an
+ * edge stays at the edge rather than wrapping: a grid is not a ring, and wrapping from the last
+ * row to the header would read as the view having jumped.
+ */
+export declare function nextCell(pos: GridPos, input: GridKey, shape: GridShape): GridPos | null;
+/**
+ * The row index a remembered row key resolves to after the data changed: its new index when it is
+ * still there, otherwise the nearest surviving neighbour of where it was, so that removing the
+ * focused row hands focus to the row that took its place.
+ */
+export declare function resolveRow(keys: readonly string[], key: string | null, lastIndex: number): number;
+export {};

package/types/ui/table/sort.d.ts

@@ -0,0 +1,14 @@
+/** How a sortable column stands: whether the table is sorted by it, and which way. */
+export interface HeaderSorting {
+    active: boolean;
+    desc: boolean;
+}
+/** A `sort` query value as the column key it names and whether it descends (a leading `-`). */
+export declare function parseSort(sort: string | undefined): {
+    field: string | undefined;
+    desc: boolean;
+};
+/** The sort a click on `key`'s header asks for: ascending, then descending, then none. */
+export declare function nextSort(sort: string | undefined, key: string): string | undefined;
+/** How a column with `sortKey` stands under `sort`, or null when it cannot sort here. */
+export declare function sortingOf(sort: string | undefined, sortKey: string | undefined, enabled: boolean): HeaderSorting | null;

package/types/ui/table/tableState.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What a viewer has done to one table (ADR-0161): the widths they set, the columns they hid or chose
+ * to show, and their order. Stored per browser, never in the URL. It is the shape a saved view would
+ * persist.
+ */
+export interface TableState {
+    v: 1;
+    /** Widths in px a viewer set. Each is a hard track: fitting never shrinks it. */
+    widths: Record<string, number>;
+    /** Columns the viewer hid. */
+    hidden: string[];
+    /** Columns the viewer chose to show, which the solver never hides for lack of room. */
+    shown: string[];
+    /** Column ids in the order the viewer wants; ids it does not list follow in their own order. */
+    order: string[];
+}
+export declare const EMPTY_TABLE_STATE: TableState;
+/** The narrowest a viewer can make a column. */
+export declare const MIN_COLUMN_WIDTH = 48;
+/** The state a stored string holds, or the empty one when it is missing, not JSON, or from another shape. */
+export declare function parseTableState(raw: string | null): TableState;
+/** The stored state for a table, or the empty one when it has no key or storage is unavailable. */
+export declare function readTableState(storageKey: string | undefined): TableState;
+/** The state with `id` set to `width` px, within what a column can be. */
+export declare function withWidth(state: TableState, id: string, width: number): TableState;
+/** The state with `id` back to fitting. */
+export declare function withoutWidth(state: TableState, id: string): TableState;
+/** The state with every width back to fitting. */
+export declare function withoutWidths(state: TableState): TableState;
+/** The state with `id` shown (and kept shown) or hidden. */
+export declare function withVisibility(state: TableState, id: string, visible: boolean): TableState;
+/**
+ * The columns in the order a viewer chose: those it lists first, in its order, then the rest as
+ * declared. An id the table no longer has is ignored. The first declared column identifies a row and
+ * stays first, whatever the stored order says.
+ */
+export declare function orderColumns<C extends {
+    id: string;
+}>(columns: C[], order: string[]): C[];
+/**
+ * The state with `id` moved one place earlier (`-1`) or later (`1`) among `ids`, which are every
+ * column's id in the order now shown. The first column stays first, so nothing moves before it, and a
+ * move past either end leaves the state as it was.
+ */
+export declare function withMovedColumn(state: TableState, ids: string[], id: string, by: -1 | 1): TableState;
+/**
+ * A table's state, read from `as.table.<storageKey>` and read again whenever the key changes (a view
+ * that serves several resource kinds keeps each kind's widths apart). Without a key the state lasts
+ * as long as the table is shown. `update` writes through to storage.
+ */
+export declare function useTableState(storageKey: string | undefined): [TableState, (change: (state: TableState) => TableState) => void];

package/types/ui/table/useGridFind.d.ts

@@ -0,0 +1,18 @@
+import type { Column } from './columns.ts';
+/** The find bar's state; `epoch` changes each time it is opened, so its input is focused anew. */
+export interface FindState {
+    query: string;
+    cursor: number;
+    epoch: number;
+}
+/**
+ * The grid's own find (the browser's cannot see rows the virtualizer has not rendered): the bar's state,
+ * the matching rows, and the row the find stands on, which `scrollTo` brings into view.
+ */
+export declare function useGridFind<T>(columns: readonly Column<T>[], data: readonly T[], scrollTo: (row: number) => void): {
+    find: FindState | null;
+    setFind: import("react").Dispatch<import("react").SetStateAction<FindState | null>>;
+    matches: number[];
+    cursor: number;
+    foundRow: number;
+};

package/types/ui/trustedTypes.d.ts

@@ -0,0 +1,16 @@
+/** Installed once, before anything renders. Where Trusted Types is not enforced it changes nothing. */
+export declare function installDefaultPolicy(): void;
+/**
+ * A script URL for `new Worker(...)`: refused unless it is on this page's origin. Without Trusted
+ * Types (tests, older browsers) it is the string itself.
+ */
+export declare function workerScriptUrl(url: string): string;
+/**
+ * The markup the code highlighter produced, cleaned. Syntax-highlighted code is the one place Rahdar
+ * renders HTML (Mantine sets it with `dangerouslySetInnerHTML`), and its text comes from broker data:
+ * message bodies, headers, configuration. The highlighter escapes it, and this is the second line: only
+ * `<span>` elements with a class and a style survive, whatever the input, and where Trusted Types is
+ * available the result is a `TrustedHTML` the sink accepts. Typed as a string because that is what
+ * Mantine's adapter contract says; React hands it to the sink untouched.
+ */
+export declare function highlightedMarkup(html: string): string;

package/types/ui/useTruncated.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether the element's text is cut off by an ellipsis right now, so a `title` is added only when it
+ * tells the reader something the row does not already show. `text` re-measures when the words change.
+ */
+export declare function useTruncated<T extends HTMLElement>(text: string): {
+    ref: import("react").RefObject<T | null>;
+    truncated: boolean;
+};

package/vite.d.ts

@@ -0,0 +1,14 @@
+import type { PluginOption } from 'vite';
+
+/** Options for {@link rahdarPlugin}. */
+export interface RahdarPluginOptions {
+  /** The plugin's id, exactly as its `plugin.json` declares it. */
+  id: string;
+  /** The module whose default export is the plugin (`definePlugin(...)`). Default `./src/feature.tsx`. */
+  entry?: string;
+  /** Where the bundle goes. Default `target/classes/META-INF/rahdar/ui`, inside the plugin jar. */
+  outDir?: string;
+}
+
+/** Vite configuration for a plugin's UI: a Module Federation remote that shares Rahdar's libraries. */
+export function rahdarPlugin(options: RahdarPluginOptions): PluginOption[];

package/vite.js

@@ -0,0 +1,62 @@
+import { federation } from '@module-federation/vite';
+
+import { SDK, SHARED_LIBRARIES, packageOf } from './shared.js';
+import peers from './peers.json' with { type: 'json' };
+
+/**
+ * Vite configuration for a plugin's UI (ADR-0100): a Module Federation remote named after the
+ * plugin, exposing `./feature`, that takes React, Mantine, TanStack and this SDK from the running
+ * Rahdar (`import: false`), with a relative base so it is served from wherever Rahdar mounts it,
+ * built into the jar's `META-INF/rahdar/ui/`.
+ *
+ * The build fails on an import Rahdar does not share — `@mantine/notifications`, say, or
+ * Mantine's CSS — since a plugin's own copy would load beside Rahdar's and silently misbehave.
+ *
+ * @param {{ id: string, entry?: string, outDir?: string }} options
+ * @returns {import('vite').PluginOption[]}
+ */
+export function rahdarPlugin({ id, entry = './src/feature.tsx', outDir = 'target/classes/META-INF/rahdar/ui' }) {
+  if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)+$/.test(id)) {
+    throw new Error(
+      `rahdarPlugin: "${id}" is not a plugin id (lowercase kebab-case, at least two segments, as in plugin.json)`,
+    );
+  }
+  const shared = Object.fromEntries([
+    ...SHARED_LIBRARIES.map((name) => [
+      name,
+      { singleton: true, import: false, requiredVersion: peers[packageOf(name)] },
+    ]),
+    [SDK, { singleton: true, import: false, requiredVersion: false }],
+  ]);
+  const allowed = new Set([...SHARED_LIBRARIES.map(packageOf), SDK]);
+
+  return [
+    {
+      name: 'rahdar-plugin',
+      // A remote has no index.html: the exposed module is the build's input, remoteEntry.js its entry.
+      config: () => ({
+        base: './',
+        build: { outDir, emptyOutDir: true, target: 'esnext', rolldownOptions: { input: entry } },
+      }),
+      resolveId(source, importer) {
+        if (!importer || !source.startsWith('@mantine/')) return null;
+        if (allowed.has(packageOf(source)) && !source.endsWith('.css')) return null;
+        this.error(
+          `${source} is not shared by Rahdar, so a plugin would load its own copy beside Rahdar's. ` +
+            (source.startsWith('@mantine/notifications')
+              ? 'Use notify from @rahdar/plugin-sdk instead.'
+              : source.endsWith('.css')
+                ? "Rahdar already loads Mantine's styles; remove this import."
+                : 'Use @mantine/core and @mantine/hooks only.'),
+        );
+      },
+    },
+    federation({
+      name: `plugin_${id.replace(/-/g, '_')}`,
+      filename: 'remoteEntry.js',
+      exposes: { './feature': entry },
+      shared,
+      dts: false,
+    }),
+  ];
+}