Build Sculptor Extension

The host API and SDK — read sdk.d.ts

The full typed contract — ExtensionHostApi, every registration option shape, every hook signature, and their doc comments — is in the generated sdk.d.ts next to this file. It is authoritative; read it rather than trusting any summary. What it contains, in one breath:

• api.registerPanel / registerSettings / registerOverlay / registerWorkspaceWidget / registerHomeView — each returns an undo function; registering twice with the same id replaces the previous contribution; every component renders inside a per-extension error boundary and receives no props.
• Hooks: useCurrentWorkspace (selector form available), useWorkspaces, useWorkspaceTasks, useNavigateToWorkspace, useOpenNewWorkspaceModal, useExtensionSetting, useExtensionSettings, useSetExtensionSetting.
• Components and actions: Markdown, PanelHeader, openExternal.

Semantics that matter beyond the types:

• Workspace scope: panels and workspace widgets are mounted per-workspace, so workspace-scoped hooks work directly. Overlays, home views, and settings components are app-global — useWorkspaceTasks is unavailable there, and useCurrentWorkspace reflects whichever workspace the current route shows (or null).
• Overlays render in a pointer-events: none layer — interactive elements must set pointer-events: auto themselves.
• useExtensionSetting persists per-extension strings in localStorage (sculptor-extension:<id>:<key>). Values are plaintext — treat anything the user puts there (e.g. an API token) as visible to anyone with devtools access, and JSON-encode yourself if you need structure.
• Prefer the selector form of useCurrentWorkspace (e.g. (w) => w?.branch ?? null) to avoid re-rendering on unrelated workspace changes.

Host-provided modules — never bundle these

The host import map provides exactly these bare specifiers; mark them as externals in any build, and never ship your own copy (a second React instance breaks hooks):

react   react/jsx-runtime   react-dom   react-dom/client
jotai   @tanstack/react-query   @radix-ui/themes   lucide-react
@sculptor/extension-sdk

Notes: @tanstack/react-query deliberately does not expose QueryClient / QueryClientProvider — extensions share the host's query cache; namespace your query keys with your extension id (e.g. ["my-extension", "issue", id]). Importing a name a module doesn't export silently yields undefined at runtime, so verify in the UI rather than trusting the build.

Two flavors: no-build vs. built

No-build (start here): hand-written ESM. Raw DOM (as in the quick start), or React without JSX via createElement:

import { createElement as h, useState } from "react";
import { useExtensionSetting } from "@sculptor/extension-sdk";

const Badge = () => {
  const [label, setLabel] = useExtensionSetting("label");
  return h("div", { style: { pointerEvents: "auto", position: "fixed", top: 8, right: 8 } },
    h("input", { value: label, onChange: (e) => setLabel(e.target.value) }));
};

export default function activate(api) {
  return api.registerOverlay({ id: "badge", component: Badge });
}

Built (when you want JSX/TypeScript/dependencies): any bundler that emits a single ESM file with the host modules external. Minimal Vite setup:

// vite.config.ts — devDependencies: vite, @vitejs/plugin-react
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  define: { "process.env.NODE_ENV": JSON.stringify("production") },
  build: {
    lib: { entry: "src/index.tsx", formats: ["es"], fileName: () => "main.js" },
    rollupOptions: {
      external: [
        "react", "react/jsx-runtime", "react-dom", "react-dom/client",
        "jotai", "@tanstack/react-query", "@radix-ui/themes", "lucide-react",
        "@sculptor/extension-sdk",
      ],
    },
  },
});

The SDK is not published to npm. For TypeScript, copy the sdk.d.ts shipped next to this skill into your project and alias it in tsconfig.json: "paths": { "@sculptor/extension-sdk": ["./sdk.d.ts"] } (you'll want @types/react installed for full fidelity). After building, place manifest.json next to the bundle ("entry": "main.js") and sculpt extension load <dist-dir> — loading the output directory keeps the upload small.

Gotchas

• load/reload report the settled status, but errors thrown after activation (event handlers, component renders) don't reach the CLI — when something registered but misbehaves, check inspect and the UI's per-extension error boundary.
• Disposers are synchronous; clean up injected styles/listeners/timers, not just DOM nodes.
• Overlays: remember pointer-events: auto on interactive elements.
• Settings are plaintext localStorage; inspect reports key names only.
• Use Radix theme CSS variables (e.g. var(--gray-12), var(--accent-9)) so the extension follows the host theme, and @radix-ui/themes components for native-feeling UI.
• One extension id wins per source priority (local > url > builtin); a shadowed duplicate loads its manifest but never activates.

Going deeper with the Sculptor source (optional)

None of this is required — the contract above is complete — but if you have a checkout of github.com/imbue-ai/sculptor (or are already working in it), you can go deeper:

• SDK source: sculptor/frontend/src/extensions/types.ts (host API contract) and sculptor/frontend/src/extensions/sdk/ (hooks, components, actions) — the sdk.d.ts next to this skill is generated from these (just generate-extension-sdk-dts).
• Reference extensions: sculptor/frontend/public/extensions/sculpty/ (no-build raw DOM), sculptor/frontend/public/extensions/pomodoro/ (no-build React overlay with persisted settings), and sculptor/frontend/extensions/linear-issue/ (full TypeScript/Vite panel + settings + widget + home view).
• Bundled extensions: extensions shipped with the app are built by the host's Vite config (sculptor/frontend/vite-plugins/bundled-extensions.ts); adding an id to COMPILED_EXTENSION_IDS there builds extensions/<id>/src/ automatically.
• In-repo skills: when working inside the Sculptor repo you can run a dev build of the app and use the auto-qa-changes skill to drive the UI in a headless browser for visual verification, instead of relying on the user's live instance.