Skip to content

The open-source app everyone uses to manage agents at work

Expand kitchen sink plugin demos

Dottacb5d7e76fba7
diff --git a/packages/plugins/examples/plugin-kitchen-sink-example/src/constants.ts b/packages/plugins/examples/plugin-kitchen-sink-example/src/constants.ts
index 4479d4a57b..9c18f610b3 100644
--- a/packages/plugins/examples/plugin-kitchen-sink-example/src/constants.ts
+++ b/packages/plugins/examples/plugin-kitchen-sink-example/src/constants.ts
@@ -2,6 +2,7 @@ import type { PluginLauncherRegistration } from "@paperclipai/plugin-sdk";
export const PLUGIN_ID = "paperclip-kitchen-sink-example";
export const PLUGIN_VERSION = "0.1.0";
+export const PAGE_ROUTE = "kitchensink";
export const SLOT_IDS = {
page: "kitchen-sink-page",
diff --git a/packages/plugins/examples/plugin-kitchen-sink-example/src/manifest.ts b/packages/plugins/examples/plugin-kitchen-sink-example/src/manifest.ts
index c7c761095f..b3348a8c76 100644
--- a/packages/plugins/examples/plugin-kitchen-sink-example/src/manifest.ts
+++ b/packages/plugins/examples/plugin-kitchen-sink-example/src/manifest.ts
@@ -3,6 +3,7 @@ import {
DEFAULT_CONFIG,
EXPORT_NAMES,
JOB_KEYS,
+ PAGE_ROUTE,
PLUGIN_ID,
PLUGIN_VERSION,
SLOT_IDS,
@@ -186,6 +187,7 @@ const manifest: PaperclipPluginManifestV1 = {
id: SLOT_IDS.page,
displayName: "Kitchen Sink",
exportName: EXPORT_NAMES.page,
+ routePath: PAGE_ROUTE,
},
{
type: "settingsPage",
diff --git a/packages/plugins/examples/plugin-kitchen-sink-example/src/ui/AsciiArtAnimation.tsx b/packages/plugins/examples/plugin-kitchen-sink-example/src/ui/AsciiArtAnimation.tsx
new file mode 100644
index 0000000000..01cad1be6f
--- /dev/null
+++ b/packages/plugins/examples/plugin-kitchen-sink-example/src/ui/AsciiArtAnimation.tsx
@@ -0,0 +1,363 @@
+import { useEffect, useRef } from "react";
+
+const CHARS = [" ", ".", "·", "▪", "▫", "○"] as const;
+const TARGET_FPS = 24;
+const FRAME_INTERVAL_MS = 1000 / TARGET_FPS;
+
+const PAPERCLIP_SPRITES = [
+ [
+ " ╭────╮ ",
+ " ╭╯╭──╮│ ",
+ " │ │ ││ ",
+ " │ │ ││ ",
+ " │ │ ││ ",
+ " │ │ ││ ",
+ " │ ╰──╯│ ",
+ " ╰─────╯ ",
+ ],
+ [
+ " ╭─────╮ ",
+ " │╭──╮╰╮ ",
+ " ││ │ │ ",
+ " ││ │ │ ",
+ " ││ │ │ ",
+ " ││ │ │ ",
+ " │╰──╯ │ ",
+ " ╰────╯ ",
+ ],
+] as const;
+
+type PaperclipSprite = (typeof PAPERCLIP_SPRITES)[number];
+
+interface Clip {
+ x: number;
+ y: number;
+ vx: number;
+ vy: number;
+ life: number;
+ maxLife: number;
+ drift: number;
+ sprite: PaperclipSprite;
+ width: number;
+ height: number;
+}
+
+function measureChar(container: HTMLElement): { w: number; h: number } {
+ const span = document.createElement("span");
+ span.textContent = "M";
+ span.style.cssText =
+ "position:absolute;visibility:hidden;white-space:pre;font-size:11px;font-family:monospace;line-height:1;";
+ container.appendChild(span);
+ const rect = span.getBoundingClientRect();
+ container.removeChild(span);
+ return { w: rect.width, h: rect.height };
+}
+
+function spriteSize(sprite: PaperclipSprite): { width: number; height: number } {
+ let width = 0;
+ for (const row of sprite) width = Math.max(width, row.length);
+ return { width, height: sprite.length };
+}
+
+export function AsciiArtAnimation() {
+ const preRef = useRef<HTMLPreElement>(null);
+ const frameRef = useRef<number | null>(null);
+
+ useEffect(() => {
+ if (!preRef.current) return;
+ const preEl: HTMLPreElement = preRef.current;
+ const motionMedia = window.matchMedia("(prefers-reduced-motion: reduce)");
+ let isVisible = document.visibilityState !== "hidden";
+ let loopActive = false;
+ let lastRenderAt = 0;
+ let tick = 0;
+ let cols = 0;
+ let rows = 0;
+ let charW = 7;
+ let charH = 11;
+ let trail = new Float32Array(0);
+ let colWave = new Float32Array(0);
+ let rowWave = new Float32Array(0);
+ let clipMask = new Uint16Array(0);
+ let clips: Clip[] = [];
+ let lastOutput = "";
+
+ function toGlyph(value: number): string {
+ const clamped = Math.max(0, Math.min(0.999, value));
+ const idx = Math.floor(clamped * CHARS.length);
+ return CHARS[idx] ?? " ";
+ }
+
+ function rebuildGrid() {
+ const nextCols = Math.max(0, Math.ceil(preEl.clientWidth / Math.max(1, charW)));
+ const nextRows = Math.max(0, Math.ceil(preEl.clientHeight / Math.max(1, charH)));
+ if (nextCols === cols && nextRows === rows) return;
+
+ cols = nextCols;
+ rows = nextRows;
+ const cellCount = cols * rows;
+ trail = new Float32Array(cellCount);
+ colWave = new Float32Array(cols);
+ rowWave = new Float32Array(rows);
+ clipMask = new Uint16Array(cellCount);
+ clips = clips.filter((clip) => {
+ return (
+ clip.x > -clip.width - 2 &&
+ clip.x < cols + 2 &&
+ clip.y > -clip.height - 2 &&
+ clip.y < rows + 2
+ );
+ });
+ lastOutput = "";
+ }
+
+ function drawStaticFrame() {
+ if (cols <= 0 || rows <= 0) {
+ preEl.textContent = "";
+ return;
+ }
+
+ const grid = Array.from({ length: rows }, () => Array.from({ length: cols }, () => " "));
+ for (let r = 0; r < rows; r++) {
+ for (let c = 0; c < cols; c++) {
+ const ambient = (Math.sin(c * 0.11 + r * 0.04) + Math.cos(r * 0.08 - c * 0.02)) * 0.18 + 0.22;
+ grid[r]![c] = toGlyph(ambient);
+ }
+ }
+
+ const gapX = 18;
+ const gapY = 13;
+ for (let baseRow = 1; baseRow < rows - 9; baseRow += gapY) {
+ const startX = Math.floor(baseRow / gapY) % 2 === 0 ? 2 : 10;
+ for (let baseCol = startX; baseCol < cols - 10; baseCol += gapX) {
+ const sprite = PAPERCLIP_SPRITES[(baseCol + baseRow) % PAPERCLIP_SPRITES.length]!;
+ for (let sr = 0; sr < sprite.length; sr++) {
+ const line = sprite[sr]!;
+ for (let sc = 0; sc < line.length; sc++) {
+ const ch = line[sc] ?? " ";
+ if (ch === " ") continue;
+ const row = baseRow + sr;
+ const col = baseCol + sc;
+ if (row < 0 || row >= rows || col < 0 || col >= cols) continue;
+ grid[row]![col] = ch;
+ }
+ }
+ }
+ }
+
+ const output = grid.map((line) => line.join("")).join("\n");
+ preEl.textContent = output;
+ lastOutput = output;
+ }
+
+ function spawnClip() {
+ const sprite = PAPERCLIP_SPRITES[Math.floor(Math.random() * PAPERCLIP_SPRITES.length)]!;
+ const size = spriteSize(sprite);
+ const edge = Math.random();
+ let x = 0;
+ let y = 0;
+ let vx = 0;
+ let vy = 0;
+
+ if (edge < 0.68) {
+ x = Math.random() < 0.5 ? -size.width - 1 : cols + 1;
+ y = Math.random() * Math.max(1, rows - size.height);
+ vx = x < 0 ? 0.04 + Math.random() * 0.05 : -(0.04 + Math.random() * 0.05);
+ vy = (Math.random() - 0.5) * 0.014;
+ } else {
+ x = Math.random() * Math.max(1, cols - size.width);
+ y = Math.random() < 0.5 ? -size.height - 1 : rows + 1;
+ vx = (Math.random() - 0.5) * 0.014;
+ vy = y < 0 ? 0.028 + Math.random() * 0.034 : -(0.028 + Math.random() * 0.034);
+ }
+
+ clips.push({
+ x,
+ y,
+ vx,
+ vy,
+ life: 0,
+ maxLife: 260 + Math.random() * 220,
+ drift: (Math.random() - 0.5) * 1.2,
+ sprite,
+ width: size.width,
+ height: size.height,
+ });
+ }
+
+ function stampClip(clip: Clip, alpha: number) {
+ const baseCol = Math.round(clip.x);
+ const baseRow = Math.round(clip.y);
+ for (let sr = 0; sr < clip.sprite.length; sr++) {
+ const line = clip.sprite[sr]!;
+ const row = baseRow + sr;
+ if (row < 0 || row >= rows) continue;
+ for (let sc = 0; sc < line.length; sc++) {
+ const ch = line[sc] ?? " ";
+ if (ch === " ") continue;
+ const col = baseCol + sc;
+ if (col < 0 || col >= cols) continue;
+ const idx = row * cols + col;
+ const stroke = ch === "│" || ch === "─" ? 0.8 : 0.92;
+ trail[idx] = Math.max(trail[idx] ?? 0, alpha * stroke);
+ clipMask[idx] = ch.charCodeAt(0);
+ }
+ }
+ }
+
+ function step(time: number) {
+ if (!loopActive) return;
+ frameRef.current = requestAnimationFrame(step);
+ if (time - lastRenderAt < FRAME_INTERVAL_MS || cols <= 0 || rows <= 0) return;
+
+ const delta = Math.min(2, lastRenderAt === 0 ? 1 : (time - lastRenderAt) / 16.6667);
+ lastRenderAt = time;
+ tick += delta;
+
+ const cellCount = cols * rows;
+ const targetCount = Math.max(3, Math.floor(cellCount / 2200));
+ while (clips.length < targetCount) spawnClip();
+
+ for (let i = 0; i < trail.length; i++) trail[i] *= 0.92;
+ clipMask.fill(0);
+
+ for (let i = clips.length - 1; i >= 0; i--) {
+ const clip = clips[i]!;
+ clip.life += delta;
+
+ const wobbleX = Math.sin((clip.y + clip.drift + tick * 0.12) * 0.09) * 0.0018;
+ const wobbleY = Math.cos((clip.x - clip.drift - tick * 0.09) * 0.08) * 0.0014;
+ clip.vx = (clip.vx + wobbleX) * 0.998;
+ clip.vy = (clip.vy + wobbleY) * 0.998;
+
+ clip.x += clip.vx * delta;
+ clip.y += clip.vy * delta;
+
+ if (
+ clip.life >= clip.maxLife ||
+ clip.x < -clip.width - 2 ||
+ clip.x > cols + 2 ||
+ clip.y < -clip.height - 2 ||
+ clip.y > rows + 2
+ ) {
+ clips.splice(i, 1);
+ continue;
+ }
+
+ const life = clip.life / clip.maxLife;
+ const alpha = life < 0.12 ? life / 0.12 : life > 0.88 ? (1 - life) / 0.12 : 1;
+ stampClip(clip, alpha);
+ }
+
+ for (let c = 0; c < cols; c++) colWave[c] = Math.sin(c * 0.08 + tick * 0.06);
+ for (let r = 0; r < rows; r++) rowWave[r] = Math.cos(r * 0.1 - tick * 0.05);
+
+ let output = "";
+ for (let r = 0; r < rows; r++) {
+ for (let c = 0; c < cols; c++) {
+ const idx = r * cols + c;
+ const clipChar = clipMask[idx];
+ if (clipChar > 0) {
+ output += String.fromCharCode(clipChar);
+ continue;
+ }
+
+ const ambient = 0.2 + colWave[c]! * 0.08 + rowWave[r]! * 0.06 + Math.sin((c + r) * 0.1 + tick * 0.035) * 0.05;
+ output += toGlyph((trail[idx] ?? 0) + ambient);
+ }
+ if (r < rows - 1) output += "\n";
+ }
+
+ if (output !== lastOutput) {
+ preEl.textContent = output;
+ lastOutput = output;
+ }
+ }
+
+ const resizeObserver = new ResizeObserver(() => {
+ const measured = measureChar(preEl);
+ charW = measured.w || 7;
+ charH = measured.h || 11;
+ rebuildGrid();
+ if (motionMedia.matches || !isVisible) {
+ drawStaticFrame();
+ }
+ });
+
+ function startLoop() {
+ if (loopActive) return;
+ loopActive = true;
+ lastRenderAt = 0;
+ frameRef.current = requestAnimationFrame(step);
+ }
+
+ function stopLoop() {
+ loopActive = false;
+ if (frameRef.current !== null) {
+ cancelAnimationFrame(frameRef.current);
+ frameRef.current = null;
+ }
+ }
+
+ function syncMode() {
+ if (motionMedia.matches || !isVisible) {
+ stopLoop();
+ drawStaticFrame();
+ } else {
+ startLoop();
+ }
+ }
+
+ function handleVisibility() {
+ isVisible = document.visibilityState !== "hidden";
+ syncMode();
+ }
+
+ const measured = measureChar(preEl);
+ charW = measured.w || 7;
+ charH = measured.h || 11;
+ rebuildGrid();
+ resizeObserver.observe(preEl);
+ motionMedia.addEventListener("change", syncMode);
+ document.addEventListener("visibilitychange", handleVisibility);
+ syncMode();
+
+ return () => {
+ stopLoop();
+ resizeObserver.disconnect();
+ motionMedia.removeEventListener("change", syncMode);
+ document.removeEventListener("visibilitychange", handleVisibility);
+ };
+ }, []);
+
+ return (
+ <div
+ style={{
+ height: "320px",
+ minHeight: "320px",
+ maxHeight: "350px",
+ background: "#1d1d1d",
+ color: "#f2efe6",
+ overflow: "hidden",
+ borderRadius: "12px",
+ border: "1px solid color-mix(in srgb, var(--border) 75%, transparent)",
+ }}
+ >
+ <pre
+ ref={preRef}
+ aria-hidden="true"
+ style={{
+ margin: 0,
+ width: "100%",
+ height: "100%",
+ padding: "14px",
+ fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, monospace",
+ fontSize: "11px",
+ lineHeight: 1,
+ whiteSpace: "pre",
+ userSelect: "none",
+ }}
+ />
+ </div>
+ );
+}
diff --git a/packages/plugins/examples/plugin-kitchen-sink-example/src/ui/index.tsx b/packages/plugins/examples/plugin-kitchen-sink-example/src/ui/index.tsx
index b8fc914ccf..53bf0b9ef9 100644
--- a/packages/plugins/examples/plugin-kitchen-sink-example/src/ui/index.tsx
+++ b/packages/plugins/examples/plugin-kitchen-sink-example/src/ui/index.tsx
@@ -4,6 +4,7 @@ import {
usePluginAction,
usePluginData,
usePluginStream,
+ usePluginToast,
type PluginCommentAnnotationProps,
type PluginCommentContextMenuItemProps,
type PluginDetailTabProps,
@@ -16,6 +17,7 @@ import {
import {
DEFAULT_CONFIG,
JOB_KEYS,
+ PAGE_ROUTE,
PLUGIN_ID,
SAFE_COMMANDS,
SLOT_IDS,
@@ -23,12 +25,34 @@ import {
TOOL_NAMES,
WEBHOOK_KEYS,
} from "../constants.js";
+import { AsciiArtAnimation } from "./AsciiArtAnimation.js";
-type CompanyRecord = { id: string; name: string; issuePrefix?: string | null };
+type CompanyRecord = { id: string; name: string; issuePrefix?: string | null; status?: string | null };
type ProjectRecord = { id: string; name: string; status?: string; path?: string | null };
type IssueRecord = { id: string; title: string; status: string; projectId?: string | null };
type GoalRecord = { id: string; title: string; status: string };
type AgentRecord = { id: string; name: string; status: string };
+type HostIssueRecord = {
+ id: string;
+ title: string;
+ status: string;
+ priority?: string | null;
+ createdAt?: string;
+};
+type HostHeartbeatRunRecord = {
+ id: string;
+ status: string;
+ invocationSource?: string | null;
+ triggerDetail?: string | null;
+ createdAt?: string;
+ startedAt?: string | null;
+ finishedAt?: string | null;
+ agentId?: string | null;
+};
+type HostLiveRunRecord = HostHeartbeatRunRecord & {
+ agentName?: string | null;
+ issueId?: string | null;
+};
type OverviewData = {
pluginId: string;
@@ -158,6 +182,31 @@ const primaryButtonStyle: CSSProperties = {
borderColor: "var(--foreground)",
};
+function toneButtonStyle(tone: "success" | "warn" | "info"): CSSProperties {
+ if (tone === "success") {
+ return {
+ ...buttonStyle,
+ background: "color-mix(in srgb, #16a34a 18%, transparent)",
+ borderColor: "color-mix(in srgb, #16a34a 60%, var(--border))",
+ color: "#86efac",
+ };
+ }
+ if (tone === "warn") {
+ return {
+ ...buttonStyle,
+ background: "color-mix(in srgb, #d97706 18%, transparent)",
+ borderColor: "color-mix(in srgb, #d97706 60%, var(--border))",
+ color: "#fcd34d",
+ };
+ }
+ return {
+ ...buttonStyle,
+ background: "color-mix(in srgb, #2563eb 18%, transparent)",
+ borderColor: "color-mix(in srgb, #2563eb 60%, var(--border))",
+ color: "#93c5fd",
+ };
+}
+
const inputStyle: CSSProperties = {
width: "100%",
border: "1px solid var(--border)",
@@ -204,6 +253,30 @@ function hostPath(companyPrefix: string | null | undefined, suffix: string): str
return companyPrefix ? `/${companyPrefix}${suffix}` : suffix;
}
+function pluginPagePath(companyPrefix: string | null | undefined): string {
+ return hostPath(companyPrefix, `/${PAGE_ROUTE}`);
+}
+
+function getErrorMessage(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+
+function getObjectString(value: unknown, key: string): string | null {
+ if (!value || typeof value !== "object") return null;
+ const next = (value as Record<string, unknown>)[key];
+ return typeof next === "string" ? next : null;
+}
+
+function getObjectNumber(value: unknown, key: string): number | null {
+ if (!value || typeof value !== "object") return null;
+ const next = (value as Record<string, unknown>)[key];
+ return typeof next === "number" && Number.isFinite(next) ? next : null;
+}
+
+function isKitchenSinkDemoCompany(company: CompanyRecord): boolean {
+ return company.name.startsWith("Kitchen Sink Demo");
+}
+
function JsonBlock({ value }: { value: unknown }) {
return <pre style={codeStyle}>{JSON.stringify(value, null, 2)}</pre>;
}
@@ -294,6 +367,41 @@ function StatusLine({ label, value }: { label: string; value: ReactNode }) {
);
}
+function PaginatedDomainCard({
+ title,
+ items,
+ totalCount,
+ empty,
+ onLoadMore,
+ render,
+}: {
+ title: string;
+ items: unknown[];
+ totalCount: number | null;
+ empty: string;
+ onLoadMore: () => void;
+ render: (item: unknown, index: number) => ReactNode;
+}) {
+ const hasMore = totalCount !== null ? items.length < totalCount : false;
+
+ return (
+ <div style={subtleCardStyle}>
+ <div style={sectionHeaderStyle}>
+ <strong>{title}</strong>
+ {totalCount !== null ? <span style={mutedTextStyle}>{items.length} / {totalCount}</span> : null}
+ </div>
+ <MiniList items={items} empty={empty} render={render} />
+ {hasMore ? (
+ <div style={{ marginTop: "10px" }}>
+ <button type="button" style={buttonStyle} onClick={onLoadMore}>
+ Load 20 more
+ </button>
+ </div>
+ ) : null}
+ </div>
+ );
+}
+
function usePluginOverview(companyId: string | null) {
return usePluginData<OverviewData>("overview", companyId ? { companyId } : {});
}
@@ -392,6 +500,9 @@ function CompactSurfaceSummary({ label, entityType }: { label: string; entityTyp
<strong>{label}</strong>
{resolvedEntityType ? <Pill label={resolvedEntityType} /> : null}
</div>
+ <div style={mutedTextStyle}>
+ This surface demo shows the host context for the current mount point. The metric button records a demo counter so you can verify plugin metrics wiring from a contextual surface.
+ </div>
<JsonBlock value={context} />
<button
type="button"
@@ -401,7 +512,7 @@ function CompactSurfaceSummary({ label, entityType }: { label: string; entityTyp
void writeMetric({ name: "surface_click", value: 1, companyId }).catch(console.error);
}}
>
- Write surface metric
+ Record demo metric
</button>
{entityQuery.data ? <JsonBlock value={entityQuery.data} /> : null}
</div>
@@ -410,6 +521,7 @@ function CompactSurfaceSummary({ label, entityType }: { label: string; entityTyp
function KitchenSinkPageWidgets({ context }: { context: PluginPageProps["context"] }) {
const overview = usePluginOverview(context.companyId);
+ const toast = usePluginToast();
const emitDemoEvent = usePluginAction("emit-demo-event");
const startProgressStream = usePluginAction("start-progress-stream");
const writeMetric = usePluginAction("write-metric");
@@ -417,8 +529,21 @@ function KitchenSinkPageWidgets({ context }: { context: PluginPageProps["context
STREAM_CHANNELS.progress,
{ companyId: context.companyId ?? undefined },
);
+ const [quickActionStatus, setQuickActionStatus] = useState<{
+ title: string;
+ body: string;
+ tone: "info" | "success" | "warn" | "error";
+ } | null>(null);
- const companyPath = hostPath(context.companyPrefix, `/plugins/${PLUGIN_ID}`);
+ useEffect(() => {
+ const latest = progressStream.events.at(-1);
+ if (!latest) return;
+ setQuickActionStatus({
+ title: "Progress stream update",
+ body: latest.message ?? `Step ${latest.step ?? "?"}`,
+ tone: "info",
+ });
+ }, [progressStream.events]);
return (
<div style={widgetGridStyle}>
@@ -432,13 +557,82 @@ function KitchenSinkPageWidgets({ context }: { context: PluginPageProps["context
</MiniWidget>
<MiniWidget title="Quick Actions" eyebrow="Try It">
+ <div style={rowStyle}>
+ <button
+ type="button"
+ style={toneButtonStyle("success")}
+ onClick={() =>
+ toast({
+ title: "Kitchen Sink success toast",
+ body: "This is rendered by the host toast system from plugin UI.",
+ tone: "success",
+ })}
+ >
+ Success toast
+ </button>
+ <button
+ type="button"
+ style={toneButtonStyle("warn")}
+ onClick={() =>
+ toast({
+ title: "Kitchen Sink warning toast",
+ body: "Use this pattern for user-facing plugin feedback.",
+ tone: "warn",
+ })}
+ >
+ Warning toast
+ </button>
+ <button
+ type="button"
+ style={toneButtonStyle("info")}
+ onClick={() =>
+ toast({
+ title: "Open dashboard",
+ body: "Toasts can link back into host pages.",
+ tone: "info",
+ action: {
+ label: "Go",
+ href: hostPath(context.companyPrefix, "/dashboard"),
+ },
+ })}
+ >
+ Action toast
+ </button>
+ </div>
<div style={rowStyle}>
<button
type="button"
style={buttonStyle}
onClick={() => {
if (!context.companyId) return;
- void emitDemoEvent({ companyId: context.companyId, message: "Triggered from Kitchen Sink page" }).catch(console.error);
+ void emitDemoEvent({ companyId: context.companyId, message: "Triggered from Kitchen Sink page" })
+ .then((next) => {
+ overview.refresh();
+ const message = getObjectString(next, "message") ?? "Demo event emitted";
+ setQuickActionStatus({
+ title: "Event emitted",
+ body: message,
+ tone: "success",
+ });
+ toast({
+ title: "Event emitted",
+ body: message,
+ tone: "success",
+ });
+ })
+ .catch((error) => {
+ const message = getErrorMessage(error);
+ setQuickActionStatus({
+ title: "Event failed",
+ body: message,
+ tone: "error",
+ });
+ toast({
+ title: "Event failed",
+ body: message,
+ tone: "error",
+ });
+ });
}}
>
Emit event
@@ -448,7 +642,32 @@ function KitchenSinkPageWidgets({ context }: { context: PluginPageProps["context
style={buttonStyle}
onClick={() => {
if (!context.companyId) return;
- void startProgressStream({ companyId: context.companyId, steps: 4 }).catch(console.error);
+ void startProgressStream({ companyId: context.companyId, steps: 4 })
+ .then(() => {
+ setQuickActionStatus({
+ title: "Stream started",
+ body: "Watch the live progress updates below.",
+ tone: "info",
+ });
+ toast({
+ title: "Progress stream started",
+ body: "Live updates will appear in the quick action panel.",
+ tone: "info",
+ });
+ })
+ .catch((error) => {
+ const message = getErrorMessage(error);
+ setQuickActionStatus({
+ title: "Stream failed",
+ body: message,
+ tone: "error",
+ });
+ toast({
+ title: "Progress stream failed",
+ body: message,
+ tone: "error",
+ });
+ });
}}
>
Start stream
@@ -458,14 +677,65 @@ function KitchenSinkPageWidgets({ context }: { context: PluginPageProps["context
style={buttonStyle}
onClick={() => {
if (!context.companyId) return;
- void writeMetric({ companyId: context.companyId, name: "page_quick_action", value: 1 }).catch(console.error);
+ void writeMetric({ companyId: context.companyId, name: "page_quick_action", value: 1 })
+ .then((next) => {
+ overview.refresh();
+ const value = getObjectNumber(next, "value") ?? 1;
+ const body = `Recorded demo.page_quick_action = ${value}`;
+ setQuickActionStatus({
+ title: "Metric recorded",
+ body,
+ tone: "success",
+ });
+ toast({
+ title: "Metric recorded",
+ body,
+ tone: "success",
+ });
+ })
+ .catch((error) => {
+ const message = getErrorMessage(error);
+ setQuickActionStatus({
+ title: "Metric failed",
+ body: message,
+ tone: "error",
+ });
+ toast({
+ title: "Metric failed",
+ body: message,
+ tone: "error",
+ });
+ });
}}
>
Write metric
</button>
</div>
- <div style={mutedTextStyle}>
- Recent progress events: {progressStream.events.length}
+ <div style={{ display: "grid", gap: "6px" }}>
+ <div style={mutedTextStyle}>
+ Recent progress events: {progressStream.events.length}
+ </div>
+ {quickActionStatus ? (
+ <div
+ style={{
+ ...subtleCardStyle,
+ borderColor:
+ quickActionStatus.tone === "error"
+ ? "color-mix(in srgb, #dc2626 45%, var(--border))"
+ : quickActionStatus.tone === "warn"
+ ? "color-mix(in srgb, #d97706 45%, var(--border))"
+ : quickActionStatus.tone === "success"
+ ? "color-mix(in srgb, #16a34a 45%, var(--border))"
+ : "color-mix(in srgb, #2563eb 45%, var(--border))",
+ }}
+ >
+ <div style={{ fontSize: "12px", fontWeight: 600 }}>{quickActionStatus.title}</div>
+ <div style={mutedTextStyle}>{quickActionStatus.body}</div>
+ </div>
+ ) : null}
+ {progressStream.events.length > 0 ? (
+ <JsonBlock value={progressStream.events.slice(-3)} />
+ ) : null}
</div>
</MiniWidget>
@@ -502,14 +772,538 @@ function KitchenSinkPageWidgets({ context }: { context: PluginPageProps["context
/>
</MiniWidget>
- <MiniWidget title="Plugin Page Route" eyebrow="Navigation">
+ </div>
+ );
+}
+
+function KitchenSinkIssueCrudDemo({ context }: { context: PluginPageProps["context"] }) {
+ const toast = usePluginToast();
+ const [issues, setIssues] = useState<HostIssueRecord[]>([]);
+ const [drafts, setDrafts] = useState<Record<string, { title: string; status: string }>>({});
+ const [createTitle, setCreateTitle] = useState("Kitchen Sink demo issue");
+ const [createDescription, setCreateDescription] = useState("Created from the Kitchen Sink embedded page.");
+ const [loading, setLoading] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+
+ async function loadIssues() {
+ if (!context.companyId) return;
+ setLoading(true);
+ try {
+ const result = await hostFetchJson<HostIssueRecord[]>(`/api/companies/${context.companyId}/issues`);
+ const nextIssues = result.slice(0, 8);
+ setIssues(nextIssues);
+ setDrafts(
+ Object.fromEntries(
+ nextIssues.map((issue) => [issue.id, { title: issue.title, status: issue.status }]),
+ ),
+ );
+ setError(null);
+ } catch (nextError) {
+ setError(getErrorMessage(nextError));
+ } finally {
+ setLoading(false);
+ }
+ }
+
+ useEffect(() => {
+ void loadIssues();
+ }, [context.companyId]);
+
+ async function handleCreate() {
+ if (!context.companyId || !createTitle.trim()) return;
+ try {
+ await hostFetchJson(`/api/companies/${context.companyId}/issues`, {
+ method: "POST",
+ body: JSON.stringify({
+ title: createTitle.trim(),
+ description: createDescription.trim() || undefined,
+ status: "todo",
+ priority: "medium",
+ }),
+ });
+ toast({ title: "Issue created", body: createTitle.trim(), tone: "success" });
+ setCreateTitle("Kitchen Sink demo issue");
+ setCreateDescription("Created from the Kitchen Sink embedded page.");
+ await loadIssues();
+ } catch (nextError) {
+ toast({ title: "Issue create failed", body: getErrorMessage(nextError), tone: "error" });
+ }
+ }
+
+ async function handleSave(issueId: string) {
+ const draft = drafts[issueId];
+ if (!draft) return;
+ try {
+ await hostFetchJson(`/api/issues/${issueId}`, {
+ method: "PATCH",
+ body: JSON.stringify({
+ title: draft.title.trim(),
+ status: draft.status,
+ }),
+ });
+ toast({ title: "Issue updated", body: draft.title.trim(), tone: "success" });
+ await loadIssues();
+ } catch (nextError) {
+ toast({ title: "Issue update failed", body: getErrorMessage(nextError), tone: "error" });
+ }
+ }
+
+ async function handleDelete(issueId: string) {
+ try {
+ await hostFetchJson(`/api/issues/${issueId}`, { method: "DELETE" });
+ toast({ title: "Issue deleted", tone: "info" });
+ await loadIssues();
+ } catch (nextError) {
+ toast({ title: "Issue delete failed", body: getErrorMessage(nextError), tone: "error" });
+ }
+ }
+
+ return (
+ <Section title="Issue CRUD">
+ <div style={mutedTextStyle}>
+ This is a regular embedded React page inside Paperclip calling the board API directly. It creates, updates, and deletes issues for the current company.
+ </div>
+ {!context.companyId ? (
+ <div style={mutedTextStyle}>Select a company to use issue demos.</div>
+ ) : (
+ <>
+ <div style={{ display: "grid", gap: "10px", gridTemplateColumns: "minmax(0, 1.4fr) minmax(0, 1fr) auto" }}>
+ <input style={inputStyle} value={createTitle} onChange={(event) => setCreateTitle(event.target.value)} placeholder="Issue title" />
+ <input style={inputStyle} value={createDescription} onChange={(event) => setCreateDescription(event.target.value)} placeholder="Issue description" />
+ <button type="button" style={primaryButtonStyle} onClick={() => void handleCreate()}>
+ Create issue
+ </button>
+ </div>
+ {loading ? <div style={mutedTextStyle}>Loading issues…</div> : null}
+ {error ? <div style={{ ...mutedTextStyle, color: "var(--destructive, #dc2626)" }}>{error}</div> : null}
+ <div style={{ display: "grid", gap: "10px" }}>
+ {issues.map((issue) => {
+ const draft = drafts[issue.id] ?? { title: issue.title, status: issue.status };
+ return (
+ <div key={issue.id} style={subtleCardStyle}>
+ <div style={{ display: "grid", gap: "10px", gridTemplateColumns: "minmax(0, 1.6fr) 140px auto auto" }}>
+ <input
+ style={inputStyle}
+ value={draft.title}
+ onChange={(event) =>
+ setDrafts((current) => ({
+ ...current,
+ [issue.id]: { ...draft, title: event.target.value },
+ }))}
+ />
+ <select
+ style={inputStyle}
+ value={draft.status}
+ onChange={(event) =>
+ setDrafts((current) => ({
+ ...current,
+ [issue.id]: { ...draft, status: event.target.value },
+ }))}
+ >
+ <option value="backlog">backlog</option>
+ <option value="todo">todo</option>
+ <option value="in_progress">in_progress</option>
+ <option value="in_review">in_review</option>
+ <option value="done">done</option>
+ <option value="blocked">blocked</option>
+ <option value="cancelled">cancelled</option>
+ </select>
+ <button type="button" style={buttonStyle} onClick={() => void handleSave(issue.id)}>
+ Save
+ </button>
+ <button type="button" style={buttonStyle} onClick={() => void handleDelete(issue.id)}>
+ Delete
+ </button>
+ </div>
+ </div>
+ );
+ })}
+ {!loading && issues.length === 0 ? <div style={mutedTextStyle}>No issues yet for this company.</div> : null}
+ </div>
+ </>
+ )}
+ </Section>
+ );
+}
+
+function KitchenSinkCompanyCrudDemo({ context }: { context: PluginPageProps["context"] }) {
+ const toast = usePluginToast();
+ const [companies, setCompanies] = useState<CompanyRecord[]>([]);
+ const [drafts, setDrafts] = useState<Record<string, { name: string; status: string }>>({});
+ const [newCompanyName, setNewCompanyName] = useState(`Kitchen Sink Demo ${new Date().toLocaleTimeString()}`);
+ const [loading, setLoading] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+
+ async function loadCompanies() {
+ setLoading(true);
+ try {
+ const result = await hostFetchJson<Array<CompanyRecord & { status?: string }>>("/api/companies");
+ setCompanies(result);
+ setDrafts(
+ Object.fromEntries(
+ result.map((company) => [company.id, { name: company.name, status: company.status ?? "active" }]),
+ ),
+ );
+ setError(null);
+ } catch (nextError) {
+ setError(getErrorMessage(nextError));
+ } finally {
+ setLoading(false);
+ }
+ }
+
+ useEffect(() => {
+ void loadCompanies();
+ }, []);
+
+ async function handleCreate() {
+ const trimmed = newCompanyName.trim();
+ if (!trimmed) return;
+ const name = trimmed.startsWith("Kitchen Sink Demo") ? trimmed : `Kitchen Sink Demo ${trimmed}`;
+ try {
+ await hostFetchJson("/api/companies", {
+ method: "POST",
+ body: JSON.stringify({
+ name,
+ description: "Created from the Kitchen Sink example plugin page.",
+ }),
+ });
+ toast({ title: "Demo company created", body: name, tone: "success" });
+ setNewCompanyName(`Kitchen Sink Demo ${Date.now()}`);
+ await loadCompanies();
+ } catch (nextError) {
+ toast({ title: "Company create failed", body: getErrorMessage(nextError), tone: "error" });
+ }
+ }
+
+ async function handleSave(companyId: string) {
+ const draft = drafts[companyId];
+ if (!draft) return;
+ try {
+ await hostFetchJson(`/api/companies/${companyId}`, {
+ method: "PATCH",
+ body: JSON.stringify({
+ name: draft.name.trim(),
+ status: draft.status,
+ }),
+ });
+ toast({ title: "Company updated", body: draft.name.trim(), tone: "success" });
+ await loadCompanies();
+ } catch (nextError) {
+ toast({ title: "Company update failed", body: getErrorMessage(nextError), tone: "error" });
+ }
+ }
+
+ async function handleDelete(company: CompanyRecord) {
+ try {
+ await hostFetchJson(`/api/companies/${company.id}`, { method: "DELETE" });
+ toast({ title: "Demo company deleted", body: company.name, tone: "info" });
+ await loadCompanies();
+ } catch (nextError) {
+ toast({ title: "Company delete failed", body: getErrorMessage(nextError), tone: "error" });
+ }
+ }
+
+ const currentCompany = companies.find((company) => company.id === context.companyId) ?? null;
+ const demoCompanies = companies.filter(isKitchenSinkDemoCompany);
+
+ return (
+ <Section title="Company CRUD">
+ <div style={mutedTextStyle}>
+ The worker SDK currently exposes company reads. This page shows a pragmatic embedded-app pattern for broader board actions by calling the host REST API directly.
+ </div>
+ <div style={subtleCardStyle}>
+ <div style={rowStyle}>
+ <strong>Current Company</strong>
+ {currentCompany ? <Pill label={currentCompany.issuePrefix ?? "no-prefix"} /> : null}
+ </div>
+ <div style={{ fontSize: "12px" }}>{currentCompany?.name ?? "No current company selected"}</div>
+ </div>
+ <div style={{ display: "grid", gap: "10px", gridTemplateColumns: "minmax(0, 1fr) auto" }}>
+ <input
+ style={inputStyle}
+ value={newCompanyName}
+ onChange={(event) => setNewCompanyName(event.target.value)}
+ placeholder="Kitchen Sink Demo Company"
+ />
+ <button type="button" style={primaryButtonStyle} onClick={() => void handleCreate()}>
+ Create demo company
+ </button>
+ </div>
+ {loading ? <div style={mutedTextStyle}>Loading companies…</div> : null}
+ {error ? <div style={{ ...mutedTextStyle, color: "var(--destructive, #dc2626)" }}>{error}</div> : null}
+ <div style={{ display: "grid", gap: "10px" }}>
+ {demoCompanies.map((company) => {
+ const draft = drafts[company.id] ?? { name: company.name, status: "active" };
+ const isCurrent = company.id === context.companyId;
+ return (
+ <div key={company.id} style={subtleCardStyle}>
+ <div style={{ display: "grid", gap: "10px", gridTemplateColumns: "minmax(0, 1.5fr) 120px auto auto" }}>
+ <input
+ style={inputStyle}
+ value={draft.name}
+ onChange={(event) =>
+ setDrafts((current) => ({
+ ...current,
+ [company.id]: { ...draft, name: event.target.value },
+ }))}
+ />
+ <select
+ style={inputStyle}
+ value={draft.status}
+ onChange={(event) =>
+ setDrafts((current) => ({
+ ...current,
+ [company.id]: { ...draft, status: event.target.value },
+ }))}
+ >
+ <option value="active">active</option>
+ <option value="paused">paused</option>
+ <option value="archived">archived</option>
+ </select>
+ <button type="button" style={buttonStyle} onClick={() => void handleSave(company.id)}>
+ Save
+ </button>
+ <button type="button" style={buttonStyle} onClick={() => void handleDelete(company)} disabled={isCurrent}>
+ Delete
+ </button>
+ </div>
+ {isCurrent ? <div style={{ ...mutedTextStyle, marginTop: "8px" }}>Current company cannot be deleted from this demo.</div> : null}
+ </div>
+ );
+ })}
+ {!loading && demoCompanies.length === 0 ? (
+ <div style={mutedTextStyle}>No demo companies yet. Create one above and manage it from this page.</div>
+ ) : null}
+ </div>
+ </Section>
+ );
+}
+
+function KitchenSinkTopRow({ context }: { context: PluginPageProps["context"] }) {
+ return (
+ <div
+ style={{
+ display: "grid",
+ gap: "14px",
+ gridTemplateColumns: "repeat(auto-fit, minmax(320px, 1fr))",
+ alignItems: "stretch",
+ }}
+ >
+ <Section title="Embedded App Demo">
+ <div style={{ fontSize: "13px", lineHeight: 1.5 }}>
+ Plugins can host their own React page and behave like a native company page. Kitchen Sink now uses this route as a practical demo app, then keeps the lower-level worker console below for the rest of the SDK surface.
+ </div>
+ </Section>
+ <div style={{ display: "grid", gap: "14px" }}>
+ <Section title="Plugin Page Route">
+ <div style={mutedTextStyle}>
+ The company sidebar entry opens this route directly, so the plugin feels like a first-class company page instead of a settings subpage.
+ </div>
+ <a href={pluginPagePath(context.companyPrefix)} style={{ fontSize: "12px" }}>
+ {pluginPagePath(context.companyPrefix)}
+ </a>
+ </Section>
+ <Section title="Paperclip Animation">
+ <div style={mutedTextStyle}>
+ This is the same Paperclip ASCII treatment used in onboarding, copied into the example plugin so the package stays self-contained.
+ </div>
+ <AsciiArtAnimation />
+ </Section>
+ </div>
+ </div>
+ );
+}
+
+function KitchenSinkStorageDemo({ context }: { context: PluginPageProps["context"] }) {
+ const toast = usePluginToast();
+ const stateKey = "revenue_clicker";
+ const revenueState = usePluginData<StateValueData>(
+ "state-value",
+ context.companyId
+ ? { scopeKind: "company", scopeId: context.companyId, stateKey }
+ : {},
+ );
+ const writeScopedState = usePluginAction("write-scoped-state");
+ const deleteScopedState = usePluginAction("delete-scoped-state");
+
+ const currentValue = useMemo(() => {
+ const raw = revenueState.data?.value;
+ if (typeof raw === "number") return raw;
+ const parsed = Number(raw ?? 0);
+ return Number.isFinite(parsed) ? parsed : 0;
+ }, [revenueState.data?.value]);
+
+ async function adjust(delta: number) {
+ if (!context.companyId) return;
+ try {
+ await writeScopedState({
+ scopeKind: "company",
+ scopeId: context.companyId,
+ stateKey,
+ value: currentValue + delta,
+ });
+ revenueState.refresh();
+ } catch (nextError) {
+ toast({ title: "Storage write failed", body: getErrorMessage(nextError), tone: "error" });
+ }
+ }
+
+ async function reset() {
+ if (!context.companyId) return;
+ try {
+ await deleteScopedState({
+ scopeKind: "company",
+ scopeId: context.companyId,
+ stateKey,
+ });
+ toast({ title: "Revenue counter reset", tone: "info" });
+ revenueState.refresh();
+ } catch (nextError) {
+ toast({ title: "Storage reset failed", body: getErrorMessage(nextError), tone: "error" });
+ }
+ }
+
+ return (
+ <Section title="Plugin Storage">
+ <div style={mutedTextStyle}>
+ This clicker persists into plugin-scoped company storage. A real revenue plugin could store counters, sync cursors, or cached external IDs the same way.
+ </div>
+ {!context.companyId ? (
+ <div style={mutedTextStyle}>Select a company to use company-scoped plugin storage.</div>
+ ) : (
+ <>
+ <div style={{ display: "grid", gap: "4px" }}>
+ <div style={{ fontSize: "26px", fontWeight: 700 }}>{currentValue}</div>
+ <div style={mutedTextStyle}>Stored at `company/{context.companyId}/{stateKey}`</div>
+ </div>
+ <div style={rowStyle}>
+ {[-10, -1, 1, 10].map((delta) => (
+ <button key={delta} type="button" style={buttonStyle} onClick={() => void adjust(delta)}>
+ {delta > 0 ? `+${delta}` : delta}
+ </button>
+ ))}
+ <button type="button" style={buttonStyle} onClick={() => void reset()}>
+ Reset
+ </button>
+ </div>
+ <JsonBlock value={revenueState.data ?? { scopeKind: "company", stateKey, value: 0 }} />
+ </>
+ )}
+ </Section>
+ );
+}
+
+function KitchenSinkHostIntegrationDemo({ context }: { context: PluginPageProps["context"] }) {
+ const [liveRuns, setLiveRuns] = useState<HostLiveRunRecord[]>([]);
+ const [recentRuns, setRecentRuns] = useState<HostHeartbeatRunRecord[]>([]);
+ const [loading, setLoading] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+
+ async function loadRuns() {
+ if (!context.companyId) return;
+ setLoading(true);
+ try {
+ const [nextLiveRuns, nextRecentRuns] = await Promise.all([
+ hostFetchJson<HostLiveRunRecord[]>(`/api/companies/${context.companyId}/live-runs?minCount=5`),
+ hostFetchJson<HostHeartbeatRunRecord[]>(`/api/companies/${context.companyId}/heartbeat-runs?limit=5`),
+ ]);
+ setLiveRuns(nextLiveRuns);
+ setRecentRuns(nextRecentRuns);
+ setError(null);
+ } catch (nextError) {
+ setError(getErrorMessage(nextError));
+ } finally {
+ setLoading(false);
+ }
+ }
+
+ useEffect(() => {
+ void loadRuns();
+ }, [context.companyId]);
+
+ return (
+ <Section title="Host Integrations">
+ <div style={mutedTextStyle}>
+ Plugin pages can feel like native Paperclip pages. This section demonstrates host toasts, company-scoped routing, and reading live heartbeat data from the embedded page.
+ </div>
+ <div style={subtleCardStyle}>
+ <div style={rowStyle}>
+ <strong>Company Route</strong>
+ <Pill label={pluginPagePath(context.companyPrefix)} />
+ </div>
<div style={mutedTextStyle}>
- The sidebar entry opens this page directly. Use it as the main kitchen-sink control surface.
+ This page is mounted as a real company route instead of living only under `/plugins/:pluginId`.
</div>
- <a href={companyPath} style={{ fontSize: "12px" }}>
- {companyPath}
- </a>
- </MiniWidget>
+ </div>
+ {!context.companyId ? (
+ <div style={mutedTextStyle}>Select a company to read run data.</div>
+ ) : (
+ <div style={{ display: "grid", gap: "12px", gridTemplateColumns: "repeat(auto-fit, minmax(260px, 1fr))" }}>
+ <div style={subtleCardStyle}>
+ <div style={sectionHeaderStyle}>
+ <strong>Live Runs</strong>
+ <button type="button" style={buttonStyle} onClick={() => void loadRuns()}>
+ Refresh
+ </button>
+ </div>
+ {loading ? <div style={mutedTextStyle}>Loading run data…</div> : null}
+ {error ? <div style={{ ...mutedTextStyle, color: "var(--destructive, #dc2626)" }}>{error}</div> : null}
+ <MiniList
+ items={liveRuns}
+ empty="No live runs right now."
+ render={(item) => {
+ const run = item as HostLiveRunRecord;
+ return (
+ <div style={{ display: "grid", gap: "6px", fontSize: "12px" }}>
+ <div style={rowStyle}>
+ <strong>{run.status}</strong>
+ {run.agentName ? <Pill label={run.agentName} /> : null}
+ </div>
+ <div>{run.id}</div>
+ {run.agentId ? (
+ <a href={hostPath(context.companyPrefix, `/agents/${run.agentId}/runs/${run.id}`)}>
+ Open run
+ </a>
+ ) : null}
+ </div>
+ );
+ }}
+ />
+ </div>
+ <div style={subtleCardStyle}>
+ <strong>Recent Heartbeats</strong>
+ <MiniList
+ items={recentRuns}
+ empty="No recent heartbeat runs."
+ render={(item) => {
+ const run = item as HostHeartbeatRunRecord;
+ return (
+ <div style={{ display: "grid", gap: "6px", fontSize: "12px" }}>
+ <div style={rowStyle}>
+ <strong>{run.status}</strong>
+ {run.invocationSource ? <Pill label={run.invocationSource} /> : null}
+ </div>
+ <div>{run.id}</div>
+ </div>
+ );
+ }}
+ />
+ </div>
+ </div>
+ )}
+ </Section>
+ );
+}
+
+function KitchenSinkEmbeddedApp({ context }: { context: PluginPageProps["context"] }) {
+ return (
+ <div style={{ display: "grid", gap: "14px" }}>
+ <KitchenSinkTopRow context={context} />
+ <KitchenSinkStorageDemo context={context} />
+ <KitchenSinkIssueCrudDemo context={context} />
+ <KitchenSinkCompanyCrudDemo context={context} />
+ <KitchenSinkHostIntegrationDemo context={context} />
</div>
);
}
@@ -517,10 +1311,14 @@ function KitchenSinkPageWidgets({ context }: { context: PluginPageProps["context
function KitchenSinkConsole({ context }: { context: { companyId: string | null; companyPrefix?: string | null; projectId?: string | null; entityId?: string | null; entityType?: string | null } }) {
const companyId = context.companyId;
const overview = usePluginOverview(companyId);
- const companies = usePluginData<CompanyRecord[]>("companies");
- const projects = usePluginData<ProjectRecord[]>("projects", companyId ? { companyId } : {});
- const issues = usePluginData<IssueRecord[]>("issues", companyId ? { companyId } : {});
- const goals = usePluginData<GoalRecord[]>("goals", companyId ? { companyId } : {});
+ const [companiesLimit, setCompaniesLimit] = useState(20);
+ const [projectsLimit, setProjectsLimit] = useState(20);
+ const [issuesLimit, setIssuesLimit] = useState(20);
+ const [goalsLimit, setGoalsLimit] = useState(20);
+ const companies = usePluginData<CompanyRecord[]>("companies", { limit: companiesLimit });
+ const projects = usePluginData<ProjectRecord[]>("projects", companyId ? { companyId, limit: projectsLimit } : {});
+ const issues = usePluginData<IssueRecord[]>("issues", companyId ? { companyId, limit: issuesLimit } : {});
+ const goals = usePluginData<GoalRecord[]>("goals", companyId ? { companyId, limit: goalsLimit } : {});
const agents = usePluginData<AgentRecord[]>("agents", companyId ? { companyId } : {});
const [issueTitle, setIssueTitle] = useState("Kitchen Sink demo issue");
@@ -600,6 +1398,12 @@ function KitchenSinkConsole({ context }: { context: { companyId: string | null;
const resumeAgent = usePluginAction("resume-agent");
const askAgent = usePluginAction("ask-agent");
+ useEffect(() => {
+ setProjectsLimit(20);
+ setIssuesLimit(20);
+ setGoalsLimit(20);
+ }, [companyId]);
+
useEffect(() => {
if (!selectedProjectId && projects.data?.[0]?.id) setSelectedProjectId(projects.data[0].id);
}, [projects.data, selectedProjectId]);
@@ -731,7 +1535,7 @@ function KitchenSinkConsole({ context }: { context: { companyId: string | null;
<Section title="UI Surfaces">
<div style={rowStyle}>
- <a href={hostPath(context.companyPrefix, `/plugins/${PLUGIN_ID}`)} style={{ fontSize: "12px" }}>Open plugin page</a>
+ <a href={pluginPagePath(context.companyPrefix)} style={{ fontSize: "12px" }}>Open plugin page</a>
{projectRef ? (
<a
href={hostPath(context.companyPrefix, `/projects/${projectRef}?tab=plugin:${PLUGIN_ID}:${SLOT_IDS.projectTab}`)}
@@ -754,50 +1558,50 @@ function KitchenSinkConsole({ context }: { context: { companyId: string | null;
<Section title="Paperclip Domain APIs">
<div style={{ display: "grid", gap: "12px", gridTemplateColumns: "repeat(auto-fit, minmax(220px, 1fr))" }}>
- <div style={subtleCardStyle}>
- <strong>Companies</strong>
- <MiniList
- items={companies.data ?? []}
- empty="No companies."
- render={(item) => {
- const company = item as CompanyRecord;
- return <div>{company.name} <span style={{ opacity: 0.6 }}>({company.id.slice(0, 8)})</span></div>;
- }}
- />
- </div>
- <div style={subtleCardStyle}>
- <strong>Projects</strong>
- <MiniList
- items={projects.data ?? []}
- empty="No projects."
- render={(item) => {
- const project = item as ProjectRecord;
- return <div>{project.name} <span style={{ opacity: 0.6 }}>({project.status ?? "unknown"})</span></div>;
- }}
- />
- </div>
- <div style={subtleCardStyle}>
- <strong>Issues</strong>
- <MiniList
- items={issues.data ?? []}
- empty="No issues."
- render={(item) => {
- const issue = item as IssueRecord;
- return <div>{issue.title} <span style={{ opacity: 0.6 }}>({issue.status})</span></div>;
- }}
- />
- </div>
- <div style={subtleCardStyle}>
- <strong>Goals</strong>
- <MiniList
- items={goals.data ?? []}
- empty="No goals."
- render={(item) => {
- const goal = item as GoalRecord;
- return <div>{goal.title} <span style={{ opacity: 0.6 }}>({goal.status})</span></div>;
- }}
- />
- </div>
+ <PaginatedDomainCard
+ title="Companies"
+ items={companies.data ?? []}
+ totalCount={overview.data?.counts.companies ?? null}
+ empty="No companies."
+ onLoadMore={() => setCompaniesLimit((current) => current + 20)}
+ render={(item) => {
+ const company = item as CompanyRecord;
+ return <div>{company.name} <span style={{ opacity: 0.6 }}>({company.id.slice(0, 8)})</span></div>;
+ }}
+ />
+ <PaginatedDomainCard
+ title="Projects"
+ items={projects.data ?? []}
+ totalCount={overview.data?.counts.projects ?? null}
+ empty="No projects."
+ onLoadMore={() => setProjectsLimit((current) => current + 20)}
+ render={(item) => {
+ const project = item as ProjectRecord;
+ return <div>{project.name} <span style={{ opacity: 0.6 }}>({project.status ?? "unknown"})</span></div>;
+ }}
+ />
+ <PaginatedDomainCard
+ title="Issues"
+ items={issues.data ?? []}
+ totalCount={overview.data?.counts.issues ?? null}
+ empty="No issues."
+ onLoadMore={() => setIssuesLimit((current) => current + 20)}
+ render={(item) => {
+ const issue = item as IssueRecord;
+ return <div>{issue.title} <span style={{ opacity: 0.6 }}>({issue.status})</span></div>;
+ }}
+ />
+ <PaginatedDomainCard
+ title="Goals"
+ items={goals.data ?? []}
+ totalCount={overview.data?.counts.goals ?? null}
+ empty="No goals."
+ onLoadMore={() => setGoalsLimit((current) => current + 20)}
+ render={(item) => {
+ const goal = item as GoalRecord;
+ return <div>{goal.title} <span style={{ opacity: 0.6 }}>({goal.status})</span></div>;
+ }}
+ />
</div>
</Section>
@@ -1272,12 +2076,8 @@ function KitchenSinkConsole({ context }: { context: { companyId: string | null;
export function KitchenSinkPage({ context }: PluginPageProps) {
return (
<div style={layoutStack}>
- <Section title="Kitchen Sink Plugin Page">
- <div style={{ fontSize: "13px", lineHeight: 1.5 }}>
- This page is the primary demo console for the Kitchen Sink example plugin. It is intentionally broad and exposes the current Paperclip plugin surface area in one place.
- </div>
- </Section>
<KitchenSinkPageWidgets context={context} />
+ <KitchenSinkEmbeddedApp context={context} />
<KitchenSinkConsole context={context} />
</div>
);
@@ -1437,7 +2237,7 @@ export function KitchenSinkDashboardWidget({ context }: PluginWidgetProps) {
<div>Issues: {overview.data?.counts.issues ?? 0}</div>
</div>
<div style={rowStyle}>
- <a href={hostPath(context.companyPrefix, `/plugins/${PLUGIN_ID}`)} style={{ fontSize: "12px" }}>Open page</a>
+ <a href={pluginPagePath(context.companyPrefix)} style={{ fontSize: "12px" }}>Open page</a>
<button
type="button"
style={buttonStyle}
@@ -1456,7 +2256,7 @@ export function KitchenSinkDashboardWidget({ context }: PluginWidgetProps) {
export function KitchenSinkSidebarLink({ context }: PluginSidebarProps) {
const config = usePluginConfigData();
if (config.data && config.data.showSidebarEntry === false) return null;
- const href = hostPath(context.companyPrefix, `/plugins/${PLUGIN_ID}`);
+ const href = pluginPagePath(context.companyPrefix);
const isActive = typeof window !== "undefined" && window.location.pathname === href;
return (
<a
@@ -1494,7 +2294,7 @@ export function KitchenSinkSidebarPanel() {
<div style={{ ...layoutStack, ...subtleCardStyle, fontSize: "12px" }}>
<strong>Kitchen Sink Panel</strong>
<div>Recent plugin records: {overview.data?.recentRecords.length ?? 0}</div>
- <a href={hostPath(context.companyPrefix, `/plugins/${PLUGIN_ID}`)}>Open plugin page</a>
+ <a href={pluginPagePath(context.companyPrefix)}>Open plugin page</a>
</div>
);
}
diff --git a/packages/plugins/examples/plugin-kitchen-sink-example/src/worker.ts b/packages/plugins/examples/plugin-kitchen-sink-example/src/worker.ts
index fd0e9eff9d..37c8b861be 100644
--- a/packages/plugins/examples/plugin-kitchen-sink-example/src/worker.ts
+++ b/packages/plugins/examples/plugin-kitchen-sink-example/src/worker.ts
@@ -225,12 +225,18 @@ function getCurrentCompanyId(params: Record<string, unknown>): string {
return companyId;
}
-async function listIssuesForCompany(ctx: PluginContext, companyId: string): Promise<Issue[]> {
- return await ctx.issues.list({ companyId, limit: 20, offset: 0 });
+function getListLimit(params: Record<string, unknown>, fallback = 50): number {
+ const value = typeof params.limit === "number" ? params.limit : Number(params.limit ?? fallback);
+ if (!Number.isFinite(value)) return fallback;
+ return Math.max(1, Math.min(200, Math.floor(value)));
}
-async function listGoalsForCompany(ctx: PluginContext, companyId: string): Promise<Goal[]> {
- return await ctx.goals.list({ companyId, limit: 20, offset: 0 });
+async function listIssuesForCompany(ctx: PluginContext, companyId: string, limit = 50): Promise<Issue[]> {
+ return await ctx.issues.list({ companyId, limit, offset: 0 });
+}
+
+async function listGoalsForCompany(ctx: PluginContext, companyId: string, limit = 50): Promise<Goal[]> {
+ return await ctx.goals.list({ companyId, limit, offset: 0 });
}
function recentRecordsSnapshot(): DemoRecord[] {
@@ -249,11 +255,11 @@ async function registerDataHandlers(ctx: PluginContext): Promise<void> {
ctx.data.register("overview", async (params) => {
const companyId = typeof params.companyId === "string" ? params.companyId : "";
const config = await getConfig(ctx);
- const companies = await ctx.companies.list({ limit: 20, offset: 0 });
- const projects = companyId ? await ctx.projects.list({ companyId, limit: 20, offset: 0 }) : [];
- const issues = companyId ? await listIssuesForCompany(ctx, companyId) : [];
- const goals = companyId ? await listGoalsForCompany(ctx, companyId) : [];
- const agents = companyId ? await ctx.agents.list({ companyId, limit: 20, offset: 0 }) : [];
+ const companies = await ctx.companies.list({ limit: 200, offset: 0 });
+ const projects = companyId ? await ctx.projects.list({ companyId, limit: 200, offset: 0 }) : [];
+ const issues = companyId ? await listIssuesForCompany(ctx, companyId, 200) : [];
+ const goals = companyId ? await listGoalsForCompany(ctx, companyId, 200) : [];
+ const agents = companyId ? await ctx.agents.list({ companyId, limit: 200, offset: 0 }) : [];
const lastJob = await readInstanceState(ctx, "last-job-run");
const lastWebhook = await readInstanceState(ctx, "last-webhook");
const lastAsset = await readInstanceState(ctx, "last-asset");
@@ -287,28 +293,28 @@ async function registerDataHandlers(ctx: PluginContext): Promise<void> {
};
});
- ctx.data.register("companies", async () => {
- return await ctx.companies.list({ limit: 50, offset: 0 });
+ ctx.data.register("companies", async (params) => {
+ return await ctx.companies.list({ limit: getListLimit(params), offset: 0 });
});
ctx.data.register("projects", async (params) => {
const companyId = getCurrentCompanyId(params);
- return await ctx.projects.list({ companyId, limit: 50, offset: 0 });
+ return await ctx.projects.list({ companyId, limit: getListLimit(params), offset: 0 });
});
ctx.data.register("issues", async (params) => {
const companyId = getCurrentCompanyId(params);
- return await listIssuesForCompany(ctx, companyId);
+ return await listIssuesForCompany(ctx, companyId, getListLimit(params));
});
ctx.data.register("goals", async (params) => {
const companyId = getCurrentCompanyId(params);
- return await listGoalsForCompany(ctx, companyId);
+ return await listGoalsForCompany(ctx, companyId, getListLimit(params));
});
ctx.data.register("agents", async (params) => {
const companyId = getCurrentCompanyId(params);
- return await ctx.agents.list({ companyId, limit: 50, offset: 0 });
+ return await ctx.agents.list({ companyId, limit: getListLimit(params), offset: 0 });
});
ctx.data.register("workspaces", async (params) => {
diff --git a/packages/plugins/sdk/src/ui/hooks.ts b/packages/plugins/sdk/src/ui/hooks.ts
index fdba2fe39e..7710e80f28 100644
--- a/packages/plugins/sdk/src/ui/hooks.ts
+++ b/packages/plugins/sdk/src/ui/hooks.ts
@@ -1,4 +1,10 @@
-import type { PluginDataResult, PluginActionFn, PluginHostContext, PluginStreamResult } from "./types.js";
+import type {
+ PluginDataResult,
+ PluginActionFn,
+ PluginHostContext,
+ PluginStreamResult,
+ PluginToastFn,
+} from "./types.js";
import { getSdkUiRuntimeValue } from "./runtime.js";
// ---------------------------------------------------------------------------
@@ -151,3 +157,18 @@ export function usePluginStream<T = unknown>(
>("usePluginStream");
return impl(channel, options);
}
+
+// ---------------------------------------------------------------------------
+// usePluginToast
+// ---------------------------------------------------------------------------
+
+/**
+ * Trigger a host toast notification from plugin UI.
+ *
+ * This lets plugin pages and widgets surface user-facing feedback through the
+ * same toast system as the host app without reaching into host internals.
+ */
+export function usePluginToast(): PluginToastFn {
+ const impl = getSdkUiRuntimeValue<() => PluginToastFn>("usePluginToast");
+ return impl();
+}
diff --git a/packages/plugins/sdk/src/ui/index.ts b/packages/plugins/sdk/src/ui/index.ts
index 05fdad6319..f6daf328d1 100644
--- a/packages/plugins/sdk/src/ui/index.ts
+++ b/packages/plugins/sdk/src/ui/index.ts
@@ -56,6 +56,7 @@ export {
usePluginAction,
useHostContext,
usePluginStream,
+ usePluginToast,
} from "./hooks.js";
// Bridge error and host context types
@@ -73,6 +74,10 @@ export type {
PluginDataResult,
PluginActionFn,
PluginStreamResult,
+ PluginToastTone,
+ PluginToastAction,
+ PluginToastInput,
+ PluginToastFn,
} from "./types.js";
// Slot component prop interfaces
diff --git a/packages/plugins/sdk/src/ui/types.ts b/packages/plugins/sdk/src/ui/types.ts
index 267b10b5ad..b1eddea5a2 100644
--- a/packages/plugins/sdk/src/ui/types.ts
+++ b/packages/plugins/sdk/src/ui/types.ts
@@ -300,6 +300,29 @@ export interface PluginDataResult<T = unknown> {
refresh(): void;
}
+// ---------------------------------------------------------------------------
+// usePluginToast hook types
+// ---------------------------------------------------------------------------
+
+export type PluginToastTone = "info" | "success" | "warn" | "error";
+
+export interface PluginToastAction {
+ label: string;
+ href: string;
+}
+
+export interface PluginToastInput {
+ id?: string;
+ dedupeKey?: string;
+ title: string;
+ body?: string;
+ tone?: PluginToastTone;
+ ttlMs?: number;
+ action?: PluginToastAction;
+}
+
+export type PluginToastFn = (input: PluginToastInput) => string | null;
+
// ---------------------------------------------------------------------------
// usePluginAction hook return type
// ---------------------------------------------------------------------------
diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.ts
index 9aa3a00275..253bfaae24 100644
--- a/packages/shared/src/constants.ts
+++ b/packages/shared/src/constants.ts
@@ -380,6 +380,33 @@ export const PLUGIN_UI_SLOT_TYPES = [
] as const;
export type PluginUiSlotType = (typeof PLUGIN_UI_SLOT_TYPES)[number];
+/**
+ * Reserved company-scoped route segments that plugin page routes may not claim.
+ *
+ * These map to first-class host pages under `/:companyPrefix/...`.
+ */
+export const PLUGIN_RESERVED_COMPANY_ROUTE_SEGMENTS = [
+ "dashboard",
+ "onboarding",
+ "companies",
+ "company",
+ "settings",
+ "plugins",
+ "org",
+ "agents",
+ "projects",
+ "issues",
+ "goals",
+ "approvals",
+ "costs",
+ "activity",
+ "inbox",
+ "design-guide",
+ "tests",
+] as const;
+export type PluginReservedCompanyRouteSegment =
+ (typeof PLUGIN_RESERVED_COMPANY_ROUTE_SEGMENTS)[number];
+
/**
* Launcher placement zones describe where a plugin-owned launcher can appear
* in the host UI. These are intentionally aligned with current slot surfaces
diff --git a/packages/shared/src/types/plugin.ts b/packages/shared/src/types/plugin.ts
index 1db68a0710..5117b501ff 100644
--- a/packages/shared/src/types/plugin.ts
+++ b/packages/shared/src/types/plugin.ts
@@ -94,6 +94,11 @@ export interface PluginUiSlotDeclaration {
* Required for `detailTab`, `taskDetailView`, and `contextMenuItem`.
*/
entityTypes?: PluginUiSlotEntityType[];
+ /**
+ * Optional company-scoped route segment for page slots.
+ * Example: `kitchensink` becomes `/:companyPrefix/kitchensink`.
+ */
+ routePath?: string;
/**
* Optional ordering hint within a slot surface. Lower numbers appear first.
* Defaults to host-defined ordering if omitted.
diff --git a/packages/shared/src/validators/plugin.ts b/packages/shared/src/validators/plugin.ts
index 149c686a15..92438fb9c0 100644
--- a/packages/shared/src/validators/plugin.ts
+++ b/packages/shared/src/validators/plugin.ts
@@ -5,6 +5,7 @@ import {
PLUGIN_CAPABILITIES,
PLUGIN_UI_SLOT_TYPES,
PLUGIN_UI_SLOT_ENTITY_TYPES,
+ PLUGIN_RESERVED_COMPANY_ROUTE_SEGMENTS,
PLUGIN_LAUNCHER_PLACEMENT_ZONES,
PLUGIN_LAUNCHER_ACTIONS,
PLUGIN_LAUNCHER_BOUNDS,
@@ -117,6 +118,9 @@ export const pluginUiSlotDeclarationSchema = z.object({
displayName: z.string().min(1),
exportName: z.string().min(1),
entityTypes: z.array(z.enum(PLUGIN_UI_SLOT_ENTITY_TYPES)).optional(),
+ routePath: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, {
+ message: "routePath must be a lowercase single-segment slug (letters, numbers, hyphens)",
+ }).optional(),
order: z.number().int().optional(),
}).superRefine((value, ctx) => {
// context-sensitive slots require explicit entity targeting.
@@ -155,6 +159,20 @@ export const pluginUiSlotDeclarationSchema = z.object({
path: ["entityTypes"],
});
}
+ if (value.routePath && value.type !== "page") {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "routePath is only supported for page slots",
+ path: ["routePath"],
+ });
+ }
+ if (value.routePath && PLUGIN_RESERVED_COMPANY_ROUTE_SEGMENTS.includes(value.routePath as (typeof PLUGIN_RESERVED_COMPANY_ROUTE_SEGMENTS)[number])) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: `routePath "${value.routePath}" is reserved by the host`,
+ path: ["routePath"],
+ });
+ }
});
export type PluginUiSlotDeclarationInput = z.infer<typeof pluginUiSlotDeclarationSchema>;
diff --git a/server/src/services/plugin-dev-watcher.ts b/server/src/services/plugin-dev-watcher.ts
index 156b236818..50080ade4d 100644
--- a/server/src/services/plugin-dev-watcher.ts
+++ b/server/src/services/plugin-dev-watcher.ts
@@ -101,6 +101,14 @@ export function createPluginDevWatcher(
);
});
+ watcher.on("error", (err) => {
+ log.warn(
+ { pluginId, packagePath: absPath, err: err instanceof Error ? err.message : String(err) },
+ "plugin-dev-watcher: watcher error, stopping watch for this plugin",
+ );
+ unwatchPlugin(pluginId);
+ });
+
watchers.set(pluginId, watcher);
log.info(
{ pluginId, packagePath: absPath },
diff --git a/server/src/services/plugin-host-services.ts b/server/src/services/plugin-host-services.ts
index 194a6116e6..bfd6f6cb51 100644
--- a/server/src/services/plugin-host-services.ts
+++ b/server/src/services/plugin-host-services.ts
@@ -465,6 +465,26 @@ export function buildHostServices(
return companyId;
};
+ const parseWindowValue = (value: unknown): number | null => {
+ if (typeof value === "number" && Number.isFinite(value)) {
+ return Math.max(0, Math.floor(value));
+ }
+ if (typeof value === "string" && value.trim().length > 0) {
+ const parsed = Number(value);
+ if (Number.isFinite(parsed)) {
+ return Math.max(0, Math.floor(parsed));
+ }
+ }
+ return null;
+ };
+
+ const applyWindow = <T>(rows: T[], params?: { limit?: unknown; offset?: unknown }): T[] => {
+ const offset = parseWindowValue(params?.offset) ?? 0;
+ const limit = parseWindowValue(params?.limit);
+ if (limit == null) return rows.slice(offset);
+ return rows.slice(offset, offset + limit);
+ };
+
/**
* Plugins are instance-wide in the current runtime. Company IDs are still
* required for company-scoped data access, but there is no per-company
@@ -648,8 +668,8 @@ export function buildHostServices(
},
companies: {
- async list(_params) {
- return (await companies.list()) as Company[];
+ async list(params) {
+ return applyWindow((await companies.list()) as Company[], params);
},
async get(params) {
await ensurePluginAvailableForCompany(params.companyId);
@@ -661,7 +681,7 @@ export function buildHostServices(
async list(params) {
const companyId = ensureCompanyId(params.companyId);
await ensurePluginAvailableForCompany(companyId);
- return (await projects.list(companyId)) as Project[];
+ return applyWindow((await projects.list(companyId)) as Project[], params);
},
async get(params) {
const companyId = ensureCompanyId(params.companyId);
@@ -738,7 +758,7 @@ export function buildHostServices(
async list(params) {
const companyId = ensureCompanyId(params.companyId);
await ensurePluginAvailableForCompany(companyId);
- return (await issues.list(companyId, params as any)) as Issue[];
+ return applyWindow((await issues.list(companyId, params as any)) as Issue[], params);
},
async get(params) {
const companyId = ensureCompanyId(params.companyId);
@@ -780,7 +800,10 @@ export function buildHostServices(
const companyId = ensureCompanyId(params.companyId);
await ensurePluginAvailableForCompany(companyId);
const rows = await agents.list(companyId);
- return rows.filter((agent) => !params.status || agent.status === params.status) as Agent[];
+ return applyWindow(
+ rows.filter((agent) => !params.status || agent.status === params.status) as Agent[],
+ params,
+ );
},
async get(params) {
const companyId = ensureCompanyId(params.companyId);
@@ -825,10 +848,13 @@ export function buildHostServices(
const companyId = ensureCompanyId(params.companyId);
await ensurePluginAvailableForCompany(companyId);
const rows = await goals.list(companyId);
- return rows.filter((goal) =>
- (!params.level || goal.level === params.level) &&
- (!params.status || goal.status === params.status),
- ) as Goal[];
+ return applyWindow(
+ rows.filter((goal) =>
+ (!params.level || goal.level === params.level) &&
+ (!params.status || goal.status === params.status),
+ ) as Goal[],
+ params,
+ );
},
async get(params) {
const companyId = ensureCompanyId(params.companyId);
diff --git a/server/src/services/plugin-loader.ts b/server/src/services/plugin-loader.ts
index bd8067c826..82494bf076 100644
--- a/server/src/services/plugin-loader.ts
+++ b/server/src/services/plugin-loader.ts
@@ -127,6 +127,12 @@ export interface PluginDiscoveryResult {
sources: PluginSource[];
}
+function getDeclaredPageRoutePaths(manifest: PaperclipPluginManifestV1): string[] {
+ return (manifest.ui?.slots ?? [])
+ .filter((slot): slot is PluginUiSlotDeclaration => slot.type === "page" && typeof slot.routePath === "string" && slot.routePath.length > 0)
+ .map((slot) => slot.routePath!);
+}
+
// ---------------------------------------------------------------------------
// Loader options
// ---------------------------------------------------------------------------
@@ -739,6 +745,30 @@ export function pluginLoader(
const log = logger.child({ service: "plugin-loader" });
const hostVersion = runtimeServices?.instanceInfo.hostVersion;
+ async function assertPageRoutePathsAvailable(manifest: PaperclipPluginManifestV1): Promise<void> {
+ const requestedRoutePaths = getDeclaredPageRoutePaths(manifest);
+ if (requestedRoutePaths.length === 0) return;
+
+ const uniqueRequested = new Set(requestedRoutePaths);
+ if (uniqueRequested.size !== requestedRoutePaths.length) {
+ throw new Error(`Plugin ${manifest.id} declares duplicate page routePath values`);
+ }
+
+ const installedPlugins = await registry.listInstalled();
+ for (const plugin of installedPlugins) {
+ if (plugin.pluginKey === manifest.id) continue;
+ const installedManifest = plugin.manifestJson as PaperclipPluginManifestV1 | null;
+ if (!installedManifest) continue;
+ const installedRoutePaths = new Set(getDeclaredPageRoutePaths(installedManifest));
+ const conflictingRoute = requestedRoutePaths.find((routePath) => installedRoutePaths.has(routePath));
+ if (conflictingRoute) {
+ throw new Error(
+ `Plugin ${manifest.id} routePath "${conflictingRoute}" conflicts with installed plugin ${plugin.pluginKey}`,
+ );
+ }
+ }
+ }
+
// -------------------------------------------------------------------------
// Internal helpers
// -------------------------------------------------------------------------
@@ -861,6 +891,8 @@ export function pluginLoader(
);
}
+ await assertPageRoutePathsAvailable(manifest);
+
// Step 6: Reject plugins that require a newer host than the running server
const minimumHostVersion = getMinimumHostVersion(manifest);
if (minimumHostVersion && hostVersion) {
diff --git a/ui/src/App.tsx b/ui/src/App.tsx
index a05bbcec76..b8d77f4473 100644
--- a/ui/src/App.tsx
+++ b/ui/src/App.tsx
@@ -155,6 +155,7 @@ function boardRoutes() {
<Route path="inbox/new" element={<Navigate to="/inbox/recent" replace />} />
<Route path="design-guide" element={<DesignGuide />} />
<Route path="tests/ux/runs" element={<RunTranscriptUxLab />} />
+ <Route path=":pluginRoutePath" element={<PluginPage />} />
<Route path="*" element={<NotFoundPage scope="board" />} />
</>
);
diff --git a/ui/src/pages/PluginPage.tsx b/ui/src/pages/PluginPage.tsx
index 345579f751..dde96f3529 100644
--- a/ui/src/pages/PluginPage.tsx
+++ b/ui/src/pages/PluginPage.tsx
@@ -18,9 +18,10 @@ import { ArrowLeft } from "lucide-react";
* @see doc/plugins/PLUGIN_SPEC.md §24.4 — Company-Context Plugin Page
*/
export function PluginPage() {
- const { companyPrefix: routeCompanyPrefix, pluginId } = useParams<{
+ const { companyPrefix: routeCompanyPrefix, pluginId, pluginRoutePath } = useParams<{
companyPrefix?: string;
- pluginId: string;
+ pluginId?: string;
+ pluginRoutePath?: string;
}>();
const { companies, selectedCompanyId } = useCompany();
const { setBreadcrumbs } = useBreadcrumbs();
@@ -39,23 +40,39 @@ export function PluginPage() {
const { data: contributions } = useQuery({
queryKey: queryKeys.plugins.uiContributions,
queryFn: () => pluginsApi.listUiContributions(),
- enabled: !!resolvedCompanyId && !!pluginId,
+ enabled: !!resolvedCompanyId && (!!pluginId || !!pluginRoutePath),
});
const pageSlot = useMemo(() => {
- if (!pluginId || !contributions) return null;
- const contribution = contributions.find((c) => c.pluginId === pluginId);
- if (!contribution) return null;
- const slot = contribution.slots.find((s) => s.type === "page");
- if (!slot) return null;
- return {
- ...slot,
- pluginId: contribution.pluginId,
- pluginKey: contribution.pluginKey,
- pluginDisplayName: contribution.displayName,
- pluginVersion: contribution.version,
- };
- }, [pluginId, contributions]);
+ if (!contributions) return null;
+ if (pluginId) {
+ const contribution = contributions.find((c) => c.pluginId === pluginId);
+ if (!contribution) return null;
+ const slot = contribution.slots.find((s) => s.type === "page");
+ if (!slot) return null;
+ return {
+ ...slot,
+ pluginId: contribution.pluginId,
+ pluginKey: contribution.pluginKey,
+ pluginDisplayName: contribution.displayName,
+ pluginVersion: contribution.version,
+ };
+ }
+ if (!pluginRoutePath) return null;
+ const matches = contributions.flatMap((contribution) => {
+ const slot = contribution.slots.find((entry) => entry.type === "page" && entry.routePath === pluginRoutePath);
+ if (!slot) return [];
+ return [{
+ ...slot,
+ pluginId: contribution.pluginId,
+ pluginKey: contribution.pluginKey,
+ pluginDisplayName: contribution.displayName,
+ pluginVersion: contribution.version,
+ }];
+ });
+ if (matches.length !== 1) return null;
+ return matches[0] ?? null;
+ }, [pluginId, pluginRoutePath, contributions]);
const context = useMemo(
() => ({
@@ -86,9 +103,22 @@ export function PluginPage() {
return <div className="text-sm text-muted-foreground">Loading…</div>;
}
+ if (!pluginId && pluginRoutePath) {
+ const duplicateMatches = contributions.filter((contribution) =>
+ contribution.slots.some((slot) => slot.type === "page" && slot.routePath === pluginRoutePath),
+ );
+ if (duplicateMatches.length > 1) {
+ return (
+ <div className="rounded-md border border-destructive/30 bg-destructive/5 px-3 py-2 text-sm text-destructive">
+ Multiple plugins declare the route <code>{pluginRoutePath}</code>. Use the plugin-id route until the conflict is resolved.
+ </div>
+ );
+ }
+ }
+
if (!pageSlot) {
// No page slot: redirect to plugin settings where plugin info is always shown
- const settingsPath = `/instance/settings/plugins/${pluginId}`;
+ const settingsPath = pluginId ? `/instance/settings/plugins/${pluginId}` : "/instance/settings/plugins";
return <Navigate to={settingsPath} replace />;
}
diff --git a/ui/src/plugins/bridge-init.ts b/ui/src/plugins/bridge-init.ts
index 6b0eb2bedd..d5d5b21b68 100644
--- a/ui/src/plugins/bridge-init.ts
+++ b/ui/src/plugins/bridge-init.ts
@@ -17,6 +17,8 @@ import {
usePluginData,
usePluginAction,
useHostContext,
+ usePluginStream,
+ usePluginToast,
} from "./bridge.js";
// ---------------------------------------------------------------------------
@@ -62,6 +64,8 @@ export function initPluginBridge(
usePluginData,
usePluginAction,
useHostContext,
+ usePluginStream,
+ usePluginToast,
// Placeholder shared UI components — plugins that use these will get
// functional stubs. Full implementations matching the host's design
diff --git a/ui/src/plugins/bridge.ts b/ui/src/plugins/bridge.ts
index f5f1b30e6f..846df45b8c 100644
--- a/ui/src/plugins/bridge.ts
+++ b/ui/src/plugins/bridge.ts
@@ -34,6 +34,7 @@ import type {
} from "@paperclipai/shared";
import { pluginsApi } from "@/api/plugins";
import { ApiError } from "@/api/client";
+import { useToast, type ToastInput } from "@/context/ToastContext";
// ---------------------------------------------------------------------------
// Bridge error type (mirrors the SDK's PluginBridgeError)
@@ -59,6 +60,9 @@ export interface PluginDataResult<T = unknown> {
refresh(): void;
}
+export type PluginToastInput = ToastInput;
+export type PluginToastFn = (input: PluginToastInput) => string | null;
+
// ---------------------------------------------------------------------------
// Host context type (mirrors the SDK's PluginHostContext)
// ---------------------------------------------------------------------------
@@ -359,3 +363,113 @@ export function useHostContext(): PluginHostContext {
const { hostContext } = usePluginBridgeContext();
return hostContext;
}
+
+// ---------------------------------------------------------------------------
+// usePluginToast — concrete implementation
+// ---------------------------------------------------------------------------
+
+export function usePluginToast(): PluginToastFn {
+ const { pushToast } = useToast();
+ return useCallback(
+ (input: PluginToastInput) => pushToast(input),
+ [pushToast],
+ );
+}
+
+// ---------------------------------------------------------------------------
+// usePluginStream — concrete implementation
+// ---------------------------------------------------------------------------
+
+export interface PluginStreamResult<T = unknown> {
+ events: T[];
+ lastEvent: T | null;
+ connecting: boolean;
+ connected: boolean;
+ error: Error | null;
+ close(): void;
+}
+
+export function usePluginStream<T = unknown>(
+ channel: string,
+ options?: { companyId?: string },
+): PluginStreamResult<T> {
+ const { pluginId, hostContext } = usePluginBridgeContext();
+ const effectiveCompanyId = options?.companyId ?? hostContext.companyId ?? undefined;
+ const [events, setEvents] = useState<T[]>([]);
+ const [lastEvent, setLastEvent] = useState<T | null>(null);
+ const [connecting, setConnecting] = useState<boolean>(Boolean(effectiveCompanyId));
+ const [connected, setConnected] = useState(false);
+ const [error, setError] = useState<Error | null>(null);
+ const sourceRef = useRef<EventSource | null>(null);
+
+ const close = useCallback(() => {
+ sourceRef.current?.close();
+ sourceRef.current = null;
+ setConnecting(false);
+ setConnected(false);
+ }, []);
+
+ useEffect(() => {
+ setEvents([]);
+ setLastEvent(null);
+ setError(null);
+
+ if (!effectiveCompanyId) {
+ close();
+ return;
+ }
+
+ const params = new URLSearchParams({ companyId: effectiveCompanyId });
+ const source = new EventSource(
+ `/api/plugins/${encodeURIComponent(pluginId)}/bridge/stream/${encodeURIComponent(channel)}?${params.toString()}`,
+ { withCredentials: true },
+ );
+ sourceRef.current = source;
+ setConnecting(true);
+ setConnected(false);
+
+ source.onopen = () => {
+ setConnecting(false);
+ setConnected(true);
+ setError(null);
+ };
+
+ source.onmessage = (event) => {
+ try {
+ const parsed = JSON.parse(event.data) as T;
+ setEvents((current) => [...current, parsed]);
+ setLastEvent(parsed);
+ } catch (nextError) {
+ setError(nextError instanceof Error ? nextError : new Error(String(nextError)));
+ }
+ };
+
+ source.addEventListener("close", () => {
+ source.close();
+ if (sourceRef.current === source) {
+ sourceRef.current = null;
+ }
+ setConnecting(false);
+ setConnected(false);
+ });
+
+ source.onerror = () => {
+ setConnecting(false);
+ setConnected(false);
+ setError(new Error(`Failed to connect to plugin stream "${channel}"`));
+ source.close();
+ if (sourceRef.current === source) {
+ sourceRef.current = null;
+ }
+ };
+
+ return () => {
+ source.close();
+ if (sourceRef.current === source) {
+ sourceRef.current = null;
+ }
+ };
+ }, [channel, close, effectiveCompanyId, pluginId]);
+
+ return { events, lastEvent, connecting, connected, error, close };
+}
diff --git a/ui/src/plugins/slots.tsx b/ui/src/plugins/slots.tsx
index d0e0551572..11559414aa 100644
--- a/ui/src/plugins/slots.tsx
+++ b/ui/src/plugins/slots.tsx
@@ -257,11 +257,11 @@ function getShimBlobUrl(specifier: "react" | "react-dom" | "react-dom/client" |
case "sdk-ui":
source = `
const SDK = globalThis.__paperclipPluginBridge__?.sdkUi ?? {};
- const { usePluginData, usePluginAction, useHostContext, usePluginStream,
+ const { usePluginData, usePluginAction, useHostContext, usePluginStream, usePluginToast,
MetricCard, StatusBadge, DataTable, TimeseriesChart,
MarkdownBlock, KeyValueList, ActionBar, LogView, JsonTree,
Spinner, ErrorBoundary } = SDK;
- export { usePluginData, usePluginAction, useHostContext, usePluginStream,
+ export { usePluginData, usePluginAction, useHostContext, usePluginStream, usePluginToast,
MetricCard, StatusBadge, DataTable, TimeseriesChart,
MarkdownBlock, KeyValueList, ActionBar, LogView, JsonTree,
Spinner, ErrorBoundary };