@nubase/terminal 0.0.0-stage → 0.1.0

package/out/renderer/assets/yaml-7gp9FQUG.js

@@ -0,0 +1,224 @@
+import { c as languages } from "./editor.api-zF37fz_e.js";
+//#region node_modules/monaco-editor/esm/vs/languages/definitions/yaml/yaml.js
+var conf = {
+	comments: { lineComment: "#" },
+	brackets: [
+		["{", "}"],
+		["[", "]"],
+		["(", ")"]
+	],
+	autoClosingPairs: [
+		{
+			open: "{",
+			close: "}"
+		},
+		{
+			open: "[",
+			close: "]"
+		},
+		{
+			open: "(",
+			close: ")"
+		},
+		{
+			open: "\"",
+			close: "\""
+		},
+		{
+			open: "'",
+			close: "'"
+		}
+	],
+	surroundingPairs: [
+		{
+			open: "{",
+			close: "}"
+		},
+		{
+			open: "[",
+			close: "]"
+		},
+		{
+			open: "(",
+			close: ")"
+		},
+		{
+			open: "\"",
+			close: "\""
+		},
+		{
+			open: "'",
+			close: "'"
+		}
+	],
+	folding: { offSide: true },
+	onEnterRules: [{
+		beforeText: /:\s*$/,
+		action: { indentAction: languages.IndentAction.Indent }
+	}]
+};
+var language = {
+	tokenPostfix: ".yaml",
+	brackets: [{
+		token: "delimiter.bracket",
+		open: "{",
+		close: "}"
+	}, {
+		token: "delimiter.square",
+		open: "[",
+		close: "]"
+	}],
+	keywords: [
+		"true",
+		"True",
+		"TRUE",
+		"false",
+		"False",
+		"FALSE",
+		"null",
+		"Null",
+		"Null",
+		"~"
+	],
+	numberInteger: /(?:0|[+-]?[0-9]+)/,
+	numberFloat: /(?:0|[+-]?[0-9]+)(?:\.[0-9]+)?(?:e[-+][1-9][0-9]*)?/,
+	numberOctal: /0o[0-7]+/,
+	numberHex: /0x[0-9a-fA-F]+/,
+	numberInfinity: /[+-]?\.(?:inf|Inf|INF)/,
+	numberNaN: /\.(?:nan|Nan|NAN)/,
+	numberDate: /\d{4}-\d\d-\d\d([Tt ]\d\d:\d\d:\d\d(\.\d+)?(( ?[+-]\d\d?(:\d\d)?)|Z)?)?/,
+	escapes: /\\(?:[btnfr\\"']|[0-7][0-7]?|[0-3][0-7]{2})/,
+	tokenizer: {
+		root: [
+			{ include: "@whitespace" },
+			{ include: "@comment" },
+			[/%[^ ]+.*$/, "meta.directive"],
+			[/---/, "operators.directivesEnd"],
+			[/\.{3}/, "operators.documentEnd"],
+			[/[-?:](?= )/, "operators"],
+			{ include: "@anchor" },
+			{ include: "@tagHandle" },
+			{ include: "@flowCollections" },
+			{ include: "@blockStyle" },
+			[/@numberInteger(?![ \t]*\S+)/, "number"],
+			[/@numberFloat(?![ \t]*\S+)/, "number.float"],
+			[/@numberOctal(?![ \t]*\S+)/, "number.octal"],
+			[/@numberHex(?![ \t]*\S+)/, "number.hex"],
+			[/@numberInfinity(?![ \t]*\S+)/, "number.infinity"],
+			[/@numberNaN(?![ \t]*\S+)/, "number.nan"],
+			[/@numberDate(?![ \t]*\S+)/, "number.date"],
+			[/(".*?"|'.*?'|[^#'"]*?)([ \t]*)(:)( |$)/, [
+				"type",
+				"white",
+				"operators",
+				"white"
+			]],
+			{ include: "@flowScalars" },
+			[/.+?(?=(\s+#|$))/, { cases: {
+				"@keywords": "keyword",
+				"@default": "string"
+			} }]
+		],
+		object: [
+			{ include: "@whitespace" },
+			{ include: "@comment" },
+			[
+				/\}/,
+				"@brackets",
+				"@pop"
+			],
+			[/,/, "delimiter.comma"],
+			[/:(?= )/, "operators"],
+			[/(?:".*?"|'.*?'|[^,\{\[]+?)(?=: )/, "type"],
+			{ include: "@flowCollections" },
+			{ include: "@flowScalars" },
+			{ include: "@tagHandle" },
+			{ include: "@anchor" },
+			{ include: "@flowNumber" },
+			[/[^\},]+/, { cases: {
+				"@keywords": "keyword",
+				"@default": "string"
+			} }]
+		],
+		array: [
+			{ include: "@whitespace" },
+			{ include: "@comment" },
+			[
+				/\]/,
+				"@brackets",
+				"@pop"
+			],
+			[/,/, "delimiter.comma"],
+			{ include: "@flowCollections" },
+			{ include: "@flowScalars" },
+			{ include: "@tagHandle" },
+			{ include: "@anchor" },
+			{ include: "@flowNumber" },
+			[/[^\],]+/, { cases: {
+				"@keywords": "keyword",
+				"@default": "string"
+			} }]
+		],
+		multiString: [[
+			/^( +).+$/,
+			"string",
+			"@multiStringContinued.$1"
+		]],
+		multiStringContinued: [[/^( *).+$/, { cases: {
+			"$1==$S2": "string",
+			"@default": {
+				token: "@rematch",
+				next: "@popall"
+			}
+		} }]],
+		whitespace: [[/[ \t\r\n]+/, "white"]],
+		comment: [[/#.*$/, "comment"]],
+		flowCollections: [[
+			/\[/,
+			"@brackets",
+			"@array"
+		], [
+			/\{/,
+			"@brackets",
+			"@object"
+		]],
+		flowScalars: [
+			[/"([^"\\]|\\.)*$/, "string.invalid"],
+			[/'([^'\\]|\\.)*$/, "string.invalid"],
+			[/'[^']*'/, "string"],
+			[
+				/"/,
+				"string",
+				"@doubleQuotedString"
+			]
+		],
+		doubleQuotedString: [
+			[/[^\\"]+/, "string"],
+			[/@escapes/, "string.escape"],
+			[/\\./, "string.escape.invalid"],
+			[
+				/"/,
+				"string",
+				"@pop"
+			]
+		],
+		blockStyle: [[
+			/[>|][0-9]*[+-]?$/,
+			"operators",
+			"@multiString"
+		]],
+		flowNumber: [
+			[/@numberInteger(?=[ \t]*[,\]\}])/, "number"],
+			[/@numberFloat(?=[ \t]*[,\]\}])/, "number.float"],
+			[/@numberOctal(?=[ \t]*[,\]\}])/, "number.octal"],
+			[/@numberHex(?=[ \t]*[,\]\}])/, "number.hex"],
+			[/@numberInfinity(?=[ \t]*[,\]\}])/, "number.infinity"],
+			[/@numberNaN(?=[ \t]*[,\]\}])/, "number.nan"],
+			[/@numberDate(?=[ \t]*[,\]\}])/, "number.date"]
+		],
+		tagHandle: [[/\![^ ]*/, "tag"]],
+		anchor: [[/[&*][^ ]+/, "namespace"]]
+	}
+};
+//#endregion
+export { conf, language };

package/out/renderer/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en" data-theme="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Nubase</title>
+    <script type="module" crossorigin src="./assets/index-CQHlaLTi.js"></script>
+    <link rel="modulepreload" crossorigin href="./assets/fileTypes-nBt-Y6NI.js">
+    <link rel="stylesheet" crossorigin href="./assets/index-DBYJcRdn.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@nubase/terminal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Nubase: an AI harness with a real, self-extending UI",
+  "license": "MIT",
+  "type": "module",
+  "main": "./out/main/index.js",
+  "bin": {
+    "nubase": "bin/nubase.js"
+  },
+  "files": [
+    "bin",
+    "out",
+    "resources"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "electron-vite dev --watch",
+    "start": "electron-vite preview",
+    "build": "electron-vite build",
+    "postinstall": "electron-rebuild -f -o node-pty || true",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write --unsafe"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "1.5.2",
+    "@nubase/sdk": "*",
+    "@nubase/ui": "*",
+    "@tailwindcss/node": "^4.3.5",
+    "@tailwindcss/oxide": "^4.3.5",
+    "@types/node": "^22.19.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "electron": "^45.3.2",
+    "esbuild": "^0.27.7",
+    "lucide-react": "^0.577.0",
+    "node-pty": "^1.1.0",
+    "tailwindcss": "^4.3.1",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.9.3",
+    "yauzl": "^3.4.0"
+  },
+  "devDependencies": {
+    "@electron/rebuild": "^4.2.1",
+    "@tailwindcss/vite": "^4.3.5",
+    "@types/papaparse": "^5.5.2",
+    "@types/yauzl": "^3.4.0",
+    "@vitejs/plugin-react": "^6.0.3",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "docx-preview": "^0.4.1",
+    "electron-vite": "^6.0.0",
+    "monaco-editor": "^0.57.0",
+    "papaparse": "^5.7.1",
+    "pdfjs-dist": "^6.5.438",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "vite": "^8.1.0",
+    "vitest": "^4.1.9",
+    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
+  }
+}

package/resources/skills/nubase-extension-authoring/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: nubase-extension-authoring
+description: How to build Nubase extensions — widgets, commands, keybindings, themes and agent tools — that hot-load into the running Nubase UI. Read before creating or editing anything in the Nubase extensions folder.
+---
+
+# Writing Nubase extensions
+
+Nubase's UI is a dock of blocks. Each block shows a **widget**. Widgets,
+commands, keybindings, themes and agent tools come from **extensions**:
+small TypeScript projects in the Nubase extensions folder
+(`~/.nubase/extensions/<id>/`). Built-in widgets use exactly this API.
+
+Each top-level tab is a folder. `~/.nubase/extensions` is **global**: those
+extensions load in every folder. A folder can also have its own
+`<folder>/.nubase/extensions/<id>/`, which loads only in that folder's tab
+and replaces a global extension with the same id. Create global extensions
+unless the user asks for one specific to the current folder or project
+(`nubase_create_extension` with `scope: "folder"`). Both kinds have the same
+layout and API.
+
+## Workflow
+
+1. `nubase_create_extension` with a kebab-case `id` (set `withHost: true` if
+   you need secrets, HTTP without CORS, Node APIs, or agent tools).
+2. Edit `src/ui.tsx` (and `src/host.ts`). Never edit `dist/` or
+   `../tsconfig.base.json`.
+3. `nubase_build_extension` — fix **every** error it reports (esbuild,
+   TypeScript, Tailwind) and build again until it succeeds. The previous
+   working version stays loaded while a build is broken.
+4. `nubase_open_widget` with the widget id, then `nubase_screenshot` with the
+   returned block id to check how it looks. Iterate on visuals.
+5. Runtime errors: `nubase_extension_logs`. Bad change? `nubase_revert_extension`.
+
+Successful builds are committed to git automatically.
+
+## Layout of an extension
+
+```
+<id>/
+  package.json     { "nubase": { "id", "displayName", "description", "ui": "src/ui.tsx", "host": "src/host.ts" } }
+  tsconfig.json    { "extends": "../tsconfig.base.json", "include": ["src"] }
+  src/ui.tsx       renderer half (React)          — optional
+  src/host.ts      Node half (Electron main)       — optional
+```
+
+`nubase.id` must equal the folder name. Widget and command ids should be
+namespaced with the extension id: `jira.myTickets`, `jira.refresh`.
+
+## Available imports
+
+Provided by Nubase at runtime (do **not** npm install these):
+
+- `react`, `react-dom`, `react/jsx-runtime`
+- `@nubase/sdk` (ui half) and `@nubase/sdk/host` (host half)
+- `@nubase/ui` — components and utilities (below)
+- `lucide-react` — icons
+
+Any other npm package: run `npm install <pkg>` inside the extension folder;
+it is bundled at build time. Prefer `fetch` over HTTP client libraries.
+
+## UI half (`src/ui.tsx`)
+
+```tsx
+import { defineUiExtension, type WidgetProps } from "@nubase/sdk";
+import { Button, Card, CardContent, CardHeader, CardTitle } from "@nubase/ui";
+import { Ticket } from "lucide-react";
+
+type State = { filter: string };
+
+const TicketsWidget = ({ ctx, state, setState, setTitle, isFocused }: WidgetProps<State>) => {
+  // state: persisted per block (lives in the layout; survives reloads/restarts)
+  // setState(next): persist new state — keep it small & JSON-serializable
+  // setTitle("…"): block header title; ctx: the UiContext (see below)
+  return <div className="h-full overflow-auto p-3">…</div>;
+};
+
+export default defineUiExtension({
+  activate(ctx) {
+    ctx.widgets.register<State>({
+      id: "jira.myTickets",
+      title: "my tickets",          // short, lowercase reads best in the launcher
+      description: "Jira tickets assigned to me",
+      icon: Ticket,
+      defaultState: { filter: "" },
+      singleton: false,             // true → only one instance, reopening focuses it
+      component: TicketsWidget,
+    });
+    ctx.commands.register({
+      id: "jira.refresh",
+      title: "Refresh Tickets",
+      category: "Jira",
+      execute: async () => { /* … */ },
+    });
+    ctx.keybindings.register({ key: "meta+shift+j", command: "jira.refresh" });
+    // Optional: return extra Disposables (timers, listeners) to clean up on reload.
+  },
+});
+```
+
+Everything registered through `ctx` is removed automatically when the
+extension reloads. Widgets are remounted on every rebuild — keep anything
+that must survive in `state`, `ctx.storage` or the host half.
+
+### UiContext (`ctx`)
+
+| API | Purpose |
+| --- | --- |
+| `ctx.widgets.register(def)` | Add a widget type (shows in the launcher) |
+| `ctx.commands.register({id,title,category?,execute})` / `.execute(id,args)` | Commands appear in the ⌘K palette; the agent can run them too |
+| `ctx.keybindings.register({key, command, args?, when?})` | `key` like `meta+k`, chords `"ctrl+k ctrl+c"`; `when` e.g. `focusedWidget == jira.myTickets` |
+| `ctx.themes.register(theme)` / `.setActive(id)` / `.getAll()` / `.active()` | Contribute or switch color themes |
+| `ctx.layout.openWidget(id, {placement, state})` / `.closeBlock` / `.focusBlock` | Arrange the dock (`placement`: right, below, left, above, replace) |
+| `ctx.host.call<T>(method, ...args)` / `ctx.host.on(event, fn)` | Talk to **this extension's** host half |
+| `ctx.workspace` | The folder this tab is open on: `{ id, folder, title, isHome }`. Default to `ctx.workspace.folder` for anything path-related |
+| `ctx.fs` | `readText`, `writeText`, `stat`, `readDirectory`, `mkdir`, `delete`, `rename`, `watch`, `homeDir` (absolute paths); `resourceUrl(path)` — a URL for `<img>`/`<video>`/`<iframe>`/`fetch` (Range supported) that streams the file, for binary or large files; `thumbnail(path, size?)` — OS thumbnail data URL (macOS/Windows); `describe(path)` — a `PreviewFile` |
+| `ctx.previewers.register(def)` | Add a file viewer to the files widget (see below) |
+| `ctx.shell` | `openPath(path)` (default app), `showItemInFolder(path)`, `quickLook(path)` (macOS) |
+| `ctx.agent` | `prompt(text, images?)` (images: `{ data: base64, mimeType }[]`), `onEvent`, `getMessages`, `getState`, … — drive the AI agent |
+| `ctx.storage.get/set(key, value)` | Small persisted JSON per extension |
+| `ctx.dialogs.confirm/input/select` | Native-looking modal dialogs (promise-based) |
+| `ctx.notify(message, "info" \| "error")` | Toast |
+| `ctx.openExternal(url)` | Open in the user's browser |
+
+### File previewers
+
+The files widget shows each file with the highest-priority previewer that
+accepts it; the others appear in its "view as" menu. Add one for a format
+the user cares about (parquet, sqlite, GeoJSON, …) instead of a new widget:
+
+```tsx
+import { definePreviewer, type PreviewerProps } from "@nubase/sdk";
+import { lazy } from "react";
+
+const GeoJsonMap = ({ file, ctx }: PreviewerProps) => {
+  // file: { path, name, extension, size, mtimeMs, url, isBinary }
+  // file.url streams the bytes and changes when the file changes: depend on it in effects.
+  // fetch(file.url).then((r) => r.json()) …, or <img src={file.url} />
+  return <div className="h-full overflow-auto p-3">…</div>;
+};
+
+// in activate(ctx):
+ctx.previewers.register(
+  definePreviewer({
+    id: "geo.map",
+    title: "Map",                       // label in the "view as" menu
+    extensions: ["geojson"],            // lowercase, no dot
+    match: (file) => file.size < 50e6,  // optional extra test
+    priority: 100,                      // built-ins: viewers 100, text editor 10, hex -50, info -100
+    component: GeoJsonMap,              // React.lazy(() => import("./heavy")) for big libraries
+  }),
+);
+```
+
+Registering an id a built-in already uses (e.g. `nubase.preview.pdf`)
+replaces that viewer. To show a file to the user, run the
+`files.preview` command: `ctx.commands.execute("files.preview", { path, placement: "right" })`.
+
+## Host half (`src/host.ts`)
+
+Runs in Node inside Nubase. Use it for secrets, network calls (no CORS),
+the file system, child processes, and agent tools.
+
+```ts
+import { defineHostExtension } from "@nubase/sdk/host";
+
+export default defineHostExtension({
+  activate(ctx) {
+    const token = async () =>
+      (await ctx.secrets.get("token")) ??
+      (await ctx.secrets.prompt("token", "Jira API token (id.atlassian.com → Security)"));
+
+    const search = async (jql: string) => {
+      const res = await fetch(`https://example.atlassian.net/rest/api/3/search?jql=${encodeURIComponent(jql)}`, {
+        headers: { Authorization: `Bearer ${await token()}`, Accept: "application/json" },
+      });
+      if (!res.ok) throw new Error(`Jira ${res.status}: ${await res.text()}`);
+      return (await res.json()).issues as { key: string; fields: { summary: string } }[];
+    };
+
+    return [
+      ctx.rpc.handle("myTickets", () => search("assignee = currentUser() AND resolution = Unresolved")),
+      ctx.agent.registerTool({
+        name: "jira_search",                 // snake_case, globally unique
+        description: "Search Jira issues with JQL. Returns key and summary.",
+        parameters: {                        // JSON Schema
+          type: "object",
+          properties: { jql: { type: "string" } },
+          required: ["jql"],
+        },
+        execute: async ({ jql }: { jql: string }) =>
+          (await search(jql)).map((i) => `${i.key}: ${i.fields.summary}`).join("\n") || "No issues.",
+      }),
+    ];
+  },
+});
+```
+
+| API | Purpose |
+| --- | --- |
+| `ctx.rpc.handle(method, fn)` | Expose a method to this extension's widgets (`ctx.host.call`) |
+| `ctx.rpc.emit(event, payload)` | Push events to widgets (`ctx.host.on`) |
+| `ctx.secrets.get/set/delete(key)`, `ctx.secrets.prompt(key, title)` | Encrypted secrets; `prompt` asks the user in a masked dialog. **Never** ask for secrets in chat or put them in code |
+| `ctx.storage.get/set` | Same store as the ui half's `ctx.storage` |
+| `ctx.agent.registerTool({...})` | Give the AI agent a new tool (available from its next turn) |
+| `ctx.workspace` | The folder this activation belongs to. A host half is activated **once per open folder tab**, so keep per-folder state inside `activate` |
+| `ctx.fs`, `ctx.log.info/warn/error` | File system; logs visible via `nubase_extension_logs` |
+
+Calling the host from a widget, with loading and error states:
+
+```tsx
+const [issues, setIssues] = useState<Issue[]>();
+const [error, setError] = useState<string>();
+useEffect(() => {
+  ctx.host.call<Issue[]>("myTickets").then(setIssues, (e) => setError(String(e)));
+}, [ctx]);
+if (error) return <Callout variant="danger" className="m-3">{error}</Callout>;
+if (!issues) return <div className="flex h-full items-center justify-center"><ActivityIndicator /></div>;
+```
+
+## Look and feel
+
+Widgets must look native. Use Tailwind classes with **theme tokens only** —
+never hard-coded colors — so every theme works:
+
+- Surfaces: `bg-background`, `bg-card`, `bg-muted`, `bg-secondary`, `bg-accent`
+- Text: `text-foreground`, `text-muted-foreground`, `text-primary`, `text-destructive`
+- Borders: `border` (uses `border-border`), `border-input`, `ring-ring`
+- Accents for data: `text-chart-1` … `text-chart-5`, `bg-chart-2/15` (opacity modifiers work)
+- Radius: `rounded-md`, `rounded-lg`; type scale `text-xs`/`text-sm` for dense UI
+
+The widget fills its block: make the root `h-full` and let content scroll
+with `overflow-auto`. Use `text-sm` by default, `p-3` padding, `gap-2`.
+
+Nubase is compact like an editor, and its density comes from theme tokens:
+the root font size, Tailwind's spacing unit and `--radius`. Size things with
+the Tailwind scale (`text-xs`, `p-2`, `h-8`, `rounded-md`) so they follow it.
+Never use pixel font sizes (`text-[13px]`, `style={{ fontSize: 13 }}`). For
+renderers that need pixels (canvas, Monaco, xterm), read the tokens with
+`readCssPixels("--code-font-size", 12)` from `@nubase/ui` (also
+`--code-line-height`).
+Mark copyable text with the `selectable` class (the app disables text
+selection by default).
+
+`@nubase/ui` components:
+
+- `Button` (`variant`: default, secondary, outline, ghost, destructive; `size`: default, sm, icon, icon-sm; `isLoading`)
+- `ActivityIndicator` (`size`: xs…xl) — use for every loading state, never a custom spinner
+- `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, `CardAction`
+- `Callout` (`variant`: info, danger)
+- `TextInput`, `SearchTextInput`, `Select` (`options: {value,label}[]`, `value`, `onChange`), `Checkbox`, `Switch`, `Label`, `FormControl` (`label`, `hint`, `error`)
+- `InputGroup` + `InputGroupInput` / `InputGroupTextarea` + `InputGroupAddon` — a field with icons or buttons inside (search box, chat composer). Add `className="h-auto"` to the group around a textarea so it grows
+- `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
+- `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuSeparator`, …
+- `Toggle`, `ButtonBar`, `cn(...classes)` for conditional classes
+- `showToast(message, "default" | "error")`
+
+## Rules
+
+- **Never write a raw `<input>`, `<textarea>` or `<select>`.** Use the
+  `@nubase/ui` field components above. They all share one definition of the
+  field surface and focus style, so a hand-styled field always looks out of
+  place. Built-in widgets are linted for this. Change size with `className`
+  (e.g. `h-6 text-xs` in a toolbar), never the border, background or focus
+  styles.
+
+- Export the extension with `export default defineUiExtension(...)` /
+  `export default defineHostExtension(...)`.
+- Keep widget state JSON-serializable and small; cache bulky data in the host
+  half or `ctx.storage`.
+- Clean up intervals and subscriptions in `useEffect` cleanups.
+- Handle errors visibly in the widget (Callout) — don't fail silently.
+- Polling: at most every 30s unless the user asks otherwise.
+- After building, always screenshot the widget and fix visual problems.

package/resources/templates/extension/package.json.template

@@ -0,0 +1,13 @@
+{
+  "name": "nubase-extension-__ID__",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "nubase": {
+    "id": "__ID__",
+    "displayName": "__DISPLAY_NAME__",
+    "description": "__DESCRIPTION__",
+    "ui": "src/ui.tsx",
+    "host": "src/host.ts"
+  }
+}

package/resources/templates/extension/src/host.ts.template

@@ -0,0 +1,12 @@
+import { defineHostExtension } from "@nubase/sdk/host";
+
+// Runs in Node (Electron main process). Use it for secrets, HTTP calls
+// without CORS, the file system, and tools for the agent.
+export default defineHostExtension({
+  activate(ctx) {
+    return [
+      // Widgets call this with: ctx.host.call<string>("hello", "world")
+      ctx.rpc.handle("hello", (name: string) => `Hello, ${name}!`),
+    ];
+  },
+});

package/resources/templates/extension/src/ui.tsx.template

@@ -0,0 +1,26 @@
+import { defineUiExtension, type WidgetProps } from "@nubase/sdk";
+import { Button } from "@nubase/ui";
+import { Sparkles } from "lucide-react";
+
+type State = { count: number };
+
+const MainWidget = ({ state, setState }: WidgetProps<State>) => (
+  <div className="flex h-full flex-col items-center justify-center gap-3 p-4">
+    <p className="text-muted-foreground text-sm">__DISPLAY_NAME__</p>
+    <p className="font-semibold text-3xl">{state.count}</p>
+    <Button onClick={() => setState({ count: state.count + 1 })}>Increment</Button>
+  </div>
+);
+
+export default defineUiExtension({
+  activate(ctx) {
+    ctx.widgets.register<State>({
+      id: "__WIDGET_ID__",
+      title: "__DISPLAY_NAME__",
+      description: "__DESCRIPTION__",
+      icon: Sparkles,
+      defaultState: { count: 0 },
+      component: MainWidget,
+    });
+  },
+});

package/resources/templates/extension/tsconfig.json.template

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.