Finalize 0.4.5 SDK compatibility

Author: tomismeta

README.md

@@ -48,7 +48,7 @@ After install, open Paperclip and use the `Focus` entry in the sidebar.
 
 ## Troubleshooting
 
-- If the sidebar shows a bordered placeholder instead of a native `Focus` entry, upgrade to Paperclip `2026.517.0` or newer and reinstall this plugin. `0.4.5` declares a host-rendered sidebar launcher instead of a custom sidebar slot.
+- If the sidebar shows a bordered placeholder instead of the `Focus` entry, upgrade to Paperclip `2026.525.0` or newer and reinstall this plugin. `0.4.5` preserves the original Focus sidebar icon and uses the current host invocation scope.
 - `paperclipApiBase` is only needed for approval overlays. Use the Paperclip origin such as `https://HOST` or `http://127.0.0.1:3100`; leaving it empty disables approval overlay reads without disabling Focus.
 - On Windows, `spawn npm ENOENT` during `npx paperclipai plugin install @tomismeta/paperclip-aperture` comes from the Paperclip host installer failing to spawn npm. This package does not spawn npm during install. Make sure the Paperclip process can resolve `npm.cmd`, or upgrade Paperclip once the Windows installer fix is available.
 
@@ -132,7 +132,7 @@ For `0.4.x`, the boundary works like this:
 - `activity.logged` document events invalidate stale reconciled state so document-backed review blockers refresh promptly without a full browser-side merge layer
 - Focus exports the live Core snapshot, the reconciled/plugin-composed display snapshot, and bounded Core traces so replay/debug flows can inspect both the engine substrate and the final operator view
 
-The plugin requires Paperclip `2026.517.0` or newer and has been validated against [`@tomismeta/aperture-core@0.7.0`](https://www.npmjs.com/package/@tomismeta/aperture-core) and [`@paperclipai/plugin-sdk@2026.517.0`](https://www.npmjs.com/package/@paperclipai/plugin-sdk).
+The plugin requires Paperclip `2026.525.0` or newer and has been validated against [`@tomismeta/aperture-core@0.7.0`](https://www.npmjs.com/package/@tomismeta/aperture-core) and [`@paperclipai/plugin-sdk@2026.525.0`](https://www.npmjs.com/package/@paperclipai/plugin-sdk).
 
 Approval overlay transport is opt-in until the Paperclip plugin SDK exposes a first-class approval client. Set the plugin config field `paperclipApiBase` when the worker can reach the host approval API; leave it empty to run Focus without approval overlays in hosted or restricted-network environments.
 

docs/RELEASE-0.4.5.md

@@ -5,14 +5,16 @@ uses the newer host attention contracts where they improve Focus judgment.
 
 ## Highlights
 
-- upgraded `@paperclipai/plugin-sdk` from `2026.428.0` to `2026.517.0`
-- declares Paperclip `2026.517.0` as the minimum host version
+- upgraded `@paperclipai/plugin-sdk` from `2026.428.0` to `2026.525.0`
+- declares Paperclip `2026.525.0` as the minimum host version
 - surfaces Paperclip Blocked Inbox attention as first-class Focus evidence
 - surfaces active Paperclip recovery actions directly in Focus
 - keeps planning-mode blockers calmer unless the host marks them urgent
 - preserves document lock metadata in review handoff copy and diagnostics
 - excludes plugin-operation issues from host reconciliation scans
-- uses a host-rendered sidebar launcher for the Focus entry
+- preserves the original Focus sidebar icon
+- preserves UI bundle import syntax so Paperclip's host-side plugin loader can rewrite React and SDK imports reliably
+- relies on the existing polling refresh path instead of opening the optional UI stream bridge on hosts where streams are not enabled
 - makes agent run failure cards acknowledgeable and clears issue-linked failures when the issue moves on
 - documents the Windows `spawn npm ENOENT` Paperclip installer failure mode
 
@@ -29,4 +31,4 @@ uses the newer host attention contracts where they improve Focus judgment.
 
 ## Validation
 
-- `pnpm verify`
+- `pnpm release:check`

esbuild.config.ts

@@ -9,20 +9,23 @@ if (!worker || !manifest || !ui) {
   throw new Error("Plugin bundler presets are missing required esbuild targets.");
 }
 
-function buildOptions(options: esbuild.BuildOptions): esbuild.BuildOptions {
+function buildOptions(
+  options: esbuild.BuildOptions,
+  buildTarget: "manifest" | "ui" | "worker",
+): esbuild.BuildOptions {
   if (watch) return options;
 
   return {
     ...options,
     legalComments: "none",
-    minify: true,
+    minify: buildTarget !== "ui",
     sourcemap: false,
   };
 }
 
-const workerContext = await esbuild.context(buildOptions(worker));
-const manifestContext = await esbuild.context(buildOptions(manifest));
-const uiContext = await esbuild.context(buildOptions(ui));
+const workerContext = await esbuild.context(buildOptions(worker, "worker"));
+const manifestContext = await esbuild.context(buildOptions(manifest, "manifest"));
+const uiContext = await esbuild.context(buildOptions(ui, "ui"));
 
 if (watch) {
   await Promise.all([

package.json

@@ -54,7 +54,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@paperclipai/plugin-sdk": "2026.517.0",
+    "@paperclipai/plugin-sdk": "2026.525.0",
     "@tomismeta/aperture-core": "0.7.0"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -4,7 +4,7 @@ const manifest: PaperclipPluginManifestV1 = {
   id: "tomismeta.paperclip-aperture",
   apiVersion: 1,
   version: "0.4.5",
-  minimumHostVersion: "2026.517.0",
+  minimumHostVersion: "2026.525.0",
   displayName: "Paperclip Aperture",
   description: "The live attention layer for Paperclip, combining Aperture Core continuity with Paperclip-native operator policy.",
   author: "@tomismeta",
@@ -62,29 +62,18 @@ const manifest: PaperclipPluginManifestV1 = {
         exportName: "AttentionPage",
         routePath: "aperture"
       },
+      {
+        type: "sidebar",
+        id: "attention-sidebar-link",
+        displayName: "Focus",
+        exportName: "AttentionSidebarLink"
+      },
       {
         type: "dashboardWidget",
         id: "attention-widget",
         displayName: "Focus",
         exportName: "DashboardWidget"
       }
-    ],
-    launchers: [
-      {
-        id: "focus-sidebar",
-        displayName: "Focus",
-        description: "Open the Paperclip Aperture Focus surface.",
-        placementZone: "sidebar",
-        order: 40,
-        action: {
-          type: "navigate",
-          target: "/aperture"
-        },
-        render: {
-          environment: "hostRoute",
-          bounds: "full"
-        }
-      }
     ]
   }
 };

src/manifest.ts

@@ -1,9 +1,7 @@
-import { usePluginData, usePluginStream } from "@paperclipai/plugin-sdk/ui";
+import { usePluginData } from "@paperclipai/plugin-sdk/ui";
 import { useEffect, useMemo, useRef, useState } from "react";
 import type { AttentionDisplayPayload, AttentionReviewState, AttentionSnapshot, StoredAttentionFrame } from "../aperture/types.js";
 
-const ATTENTION_UPDATES_STREAM = "attention-updates";
-
 export type QueueMovement = "up" | "down";
 
 export type Posture = {
@@ -175,18 +173,9 @@ export function useAttentionModel(companyId: string | null | undefined): {
   refresh: () => void;
 } {
   const displayQuery = usePluginData<AttentionDisplayPayload>("attention-display", companyId ? { companyId } : undefined);
-  const updates = usePluginStream<{ updatedAt: string; eventType: string }>(
-    ATTENTION_UPDATES_STREAM,
-    companyId ? { companyId } : undefined,
-  );
 
   useAttentionPolling(companyId, [displayQuery.refresh]);
 
-  useEffect(() => {
-    if (!companyId || !updates.lastEvent) return;
-    displayQuery.refresh();
-  }, [companyId, updates.lastEvent?.updatedAt, updates.lastEvent?.eventType]);
-
   return useMemo(() => ({
     snapshot: displayQuery.data?.snapshot ?? null,
     review: displayQuery.data?.reviewState ?? null,

src/ui/focus-model.tsx

@@ -1,5 +1,6 @@
 import {
   type PluginPageProps,
+  type PluginSidebarProps,
   type PluginWidgetProps,
 } from "@paperclipai/plugin-sdk/ui";
 import { useEffect, useMemo, useState } from "react";
@@ -16,6 +17,7 @@ import {
   GENERIC_QUEUED_JUDGMENT,
 } from "../aperture/attention-language.js";
 import {
+  ACCENT_BG_STYLE,
   ACCENT_BORDER,
   ACCENT_COLOR,
   Accent,
@@ -33,6 +35,7 @@ import {
   useWideLayout,
 } from "./chrome.js";
 import {
+  actionableCount,
   actionableLabel,
   currentSurfaceBrand,
   formatRelativeTime,
@@ -44,6 +47,7 @@ import {
   type SurfaceBrand,
   useAttentionModel,
   useQueueMovement,
+  unreadCount,
 } from "./focus-model.js";
 import {
   approvalIdForFrame,
@@ -760,6 +764,73 @@ export function DashboardWidget(props: PluginWidgetProps) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Sidebar link — Paperclip launcher chrome with the original Focus glyph
+// ---------------------------------------------------------------------------
+
+export function AttentionSidebarLink({ context }: PluginSidebarProps) {
+  const companyId = context.companyId;
+  const brand = currentSurfaceBrand();
+  const href = pluginPagePath(context.companyPrefix);
+  const isActive = typeof window !== "undefined" && window.location.pathname === href;
+  const model = useAttentionModel(companyId);
+  const merged = model.snapshot;
+  const actionable = merged ? actionableCount(merged) : 0;
+  const unread = unreadCount(merged);
+
+  return (
+    <a
+      href={href}
+      aria-current={isActive ? "page" : undefined}
+      className={cn(
+        "flex items-center gap-2.5 px-3 py-2 text-[13px] font-medium transition-colors",
+        isActive
+          ? "bg-accent text-foreground"
+          : "text-foreground/80 hover:bg-accent/50 hover:text-foreground",
+      )}
+    >
+      <span className="relative shrink-0" aria-hidden="true">
+        <svg
+          viewBox="0 0 24 24"
+          className="h-4 w-4"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.9"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <circle cx="12" cy="12" r="9" />
+          <path d="m14.3 8 5.2 9" />
+          <path d="M9.7 8h10.4" />
+          <path d="m7.4 12 5.2-9" />
+          <path d="m9.7 16-5.2-9" />
+          <path d="M14.3 16H3.9" />
+          <path d="m16.6 12-5.2 9" />
+        </svg>
+        {unread > 0 ? (
+          <span
+            className="absolute -right-1 -top-1 h-2 w-2 rounded-full"
+            style={{ backgroundColor: ACCENT_COLOR }}
+          />
+        ) : null}
+      </span>
+      <span className="flex-1 truncate">{brand.wordmark}</span>
+      {actionable > 0 ? (
+        <span className="inline-flex items-center justify-center rounded-full px-1.5 py-0.5 text-xs leading-none font-medium text-white" style={ACCENT_BG_STYLE}>
+          {actionable}
+        </span>
+      ) : unread > 0 ? (
+        <span
+          className="inline-flex items-center justify-center rounded-full border px-1.5 py-0.5 text-xs leading-none font-medium"
+          style={{ color: ACCENT_COLOR, borderColor: ACCENT_BORDER, backgroundColor: "transparent" }}
+        >
+          {unread}
+        </span>
+      ) : null}
+    </a>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Attention page — single-column, calm operator surface
 // ---------------------------------------------------------------------------

src/ui/index.tsx

@@ -260,19 +260,16 @@ function mockApprovalApi(
 }
 
 describe("paperclip aperture", () => {
-  it("declares a host-rendered Focus sidebar launcher", () => {
-    expect(manifest.ui?.slots?.some((slot) => slot.type === "sidebar")).toBe(false);
-    expect(manifest.ui?.launchers).toEqual(expect.arrayContaining([
+  it("declares the Focus sidebar entry with its custom UI", () => {
+    expect(manifest.ui?.slots).toEqual(expect.arrayContaining([
       expect.objectContaining({
-        id: "focus-sidebar",
+        type: "sidebar",
+        id: "attention-sidebar-link",
         displayName: "Focus",
-        placementZone: "sidebar",
-        action: expect.objectContaining({
-          type: "navigate",
-          target: "/aperture",
-        }),
+        exportName: "AttentionSidebarLink",
       }),
     ]));
+    expect(manifest.ui?.launchers ?? []).toHaveLength(0);
   });
 
   it("maps approval events into attention state and clears them on acknowledgement", async () => {