create-rigline-plugin 1.0.0-alpha.10 → 1.0.0-alpha.12

package/dist/index.js

@@ -82,7 +82,7 @@ export function nextSteps(result) {
         "",
         "Then reload the webview: Developer: Reload Webviews.",
         "",
-        `${join(here, "README.md")} has the rest, including the four rules worth reading first.`,
+        `${join(here, "README.md")} has the rest, including the rules worth reading first.`,
         "",
         "Read the plugin policy once — what Rigline promises Anthropic, and the part your plugin has",
         "to hold up. It applies whether or not you ever publish this:",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rigline-plugin",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.12",
   "description": "Scaffold a workspace for Claude Code VS Code extension plugins",
   "keywords": [
     "rigline",
@@ -32,7 +32,7 @@
     "create-rigline-plugin": "./dist/index.js"
   },
   "devDependencies": {
-    "@rigline/plugin-api": "1.0.0-alpha.10"
+    "@rigline/plugin-api": "1.0.0-alpha.12"
   },
   "scripts": {
     "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json",

package/template/README.md

@@ -37,6 +37,10 @@ which is the whole reason to declare rather than to reach.
 Put a dependency you can do without under `uses.optional`: it is checked the same way and costs the
 plugin that one decoration rather than the whole plugin.
 
+`elements` is the other half: what the plugin contributes, each with the places it may go and where
+it goes by default — or `null` for off. A place this extension version cannot provide costs that
+element and nothing else, and `check` says so.
+
 ## The plugin policy
 
 **This applies whether or not you ever publish.** A plugin you wrote for yourself and will never
@@ -48,8 +52,8 @@ takes a minute.
 Rigline modifies Anthropic's extension and publishes a compliance position saying what it does and
 does not do. Your plugin runs inside that modification, so the position has to hold for it too.
 
-Most of it is not left to you — the webview has no network egress, no filesystem, and no way into
-the extension host, so the usual ways to do harm are absent rather than forbidden. What the policy
+Most of it is not left to you — the webview has no network egress, no filesystem, and no way to run
+code in the extension host, so the usual ways to do harm are absent rather than forbidden. What the policy
 asks is the part the architecture cannot cover: do not deceive the person using it, do not reach for
 credentials, do not carry conversation content off the machine by a path the closed network does not
 cover, and keep any host patch to switching on a capability the extension already has.
@@ -115,6 +119,8 @@ what you bumped.
   you placed.
 - **Ask what a container does about its children before decorating it.** The composer footer
   measures its own element children and re-measures on any foreign change inside it; footer
-  decorations go beside `footerSpacer`, with `ctx.mountBefore`.
+  elements go before `footerSpacer`.
+- **Keep what you place steady.** An element in the footer whose text keeps changing makes the
+  footer re-measure each time, and one in `rigRow` whose height keeps changing re-renders the panel.
 - **Do not poll for an element.** `ctx.watch(name, …)` hands it over when it appears and again when
   the app replaces it.

package/template/plugins/__NAME__/README.md

@@ -4,15 +4,16 @@ __DESCRIPTION__
 
 ## Depends on
 
-- `uses.anchors: ["footerSpacer"]` — the flexible gap dividing the composer footer's left cluster
-  from its right, and the anchor every footer decoration uses. The footer measures the widths of its
-  own element children to pick a fit stage; the spacer renders in every stage, so a decoration
-  beside it contributes a constant width and the measurement settles.
-- `uses.mount` — `ctx.watch` and `ctx.mountBefore`, which place the badge and keep it placed across
-  a re-render.
-- `uses.style` — one stylesheet, scoped to the class this plugin puts on its own element.
 - `uses.tools` — `ctx.onToolUse`, every completed tool call the assistant makes.
 
+## Contributes
+
+- `elements.badge` — the tool-call count, before `footerSpacer` by default: the flexible gap
+  dividing the composer footer's left cluster from its right, and the place footer elements go. The
+  footer measures the widths of its own element children to pick a fit stage; the spacer renders in
+  every stage, so an element beside it contributes a constant width and the measurement settles. It
+  may also go in `rigRow`, the row under the composer's controls.
+
 ## Notes
 
 `badgeText` is exported and tested because it is the half a plain test run can hold. Everything

package/template/plugins/__NAME__/package.json

@@ -13,6 +13,9 @@
   },
   "devDependencies": {
     "@rigline/core": "__RIGLINE_RANGE__",
-    "@rigline/plugin-api": "__RIGLINE_RANGE__"
+    "@rigline/plugin-api": "__RIGLINE_RANGE__",
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
   }
 }

package/template/plugins/__NAME__/rigline.json

@@ -6,9 +6,13 @@
   "entry": "dist/index.js",
   "surfaces": ["editor", "sidebar"],
   "uses": {
-    "anchors": ["footerSpacer"],
-    "mount": true,
-    "style": true,
     "tools": true
+  },
+  "elements": {
+    "badge": {
+      "title": "Tool calls",
+      "placements": [{ "anchor": "footerSpacer", "at": "before" }, "rigRow"],
+      "default": { "anchor": "footerSpacer", "at": "before" }
+    }
   }
 }

package/template/plugins/__NAME__/src/index.test.ts

@@ -7,7 +7,7 @@
  * and only the app can answer it: `pnpm build`, `pnpm rigline add`, reload the webview, look.
  */
 import { describe, expect, it } from "vitest";
-import { badgeText } from "./index.ts";
+import { badgeText } from "./index.tsx";
 
 describe("badgeText", () => {
   it("says something before anything has happened", () => {

package/template/plugins/__NAME__/src/index.tsx

@@ -0,0 +1,64 @@
+/**
+ * __DESCRIPTION__
+ *
+ * A worked example of the loop every plugin is: declare what you contribute and depend on in
+ * `rigline.json`, keep what you learn in a store, and render it from a component. Replace the body;
+ * keep the shape.
+ */
+import {
+  definePlugin,
+  type PluginContext,
+  type Store,
+  store,
+  type Teardown,
+} from "@rigline/plugin-api";
+import { Pill, useStore } from "@rigline/plugin-api/ui";
+import type { ReactNode } from "react";
+
+/**
+ * What the badge reads, for a given number of tool calls.
+ *
+ * Pure, and exported, because this is the half a plain `vitest` run can hold: anything that renders
+ * wants the app itself, and anything that does not should not need it. See `src/index.test.ts`.
+ */
+export function badgeText(calls: number): string {
+  if (calls === 0) return "no tools yet";
+  return `${calls} tool ${calls === 1 ? "call" : "calls"}`;
+}
+
+function Badge(props: { readonly calls: Store<number> }): ReactNode {
+  return <Pill>{badgeText(useStore(props.calls))}</Pill>;
+}
+
+export default definePlugin({
+  setup(ctx: PluginContext): Teardown {
+    // A store, made here rather than in the component, because state caught in `setup` is caught
+    // from the moment the plugin loads, and the badge and anything else can share it.
+    const calls = store(0);
+
+    // Every completed tool call the assistant makes. `uses.tools` is what makes this fire; without
+    // the declaration it throws and disables the plugin, which is the point of declaring.
+    const stopTools = ctx.onToolUse(() => calls.set(calls.get() + 1));
+
+    // `badge` is declared under `elements` in rigline.json, which says where it goes by default:
+    // before `footerSpacer`, at the end of the composer footer's left cluster. Rigline places it,
+    // keeps it placed, and moves it if the user asks for it somewhere else.
+    const stopBadge = ctx.element("badge", () => <Badge calls={calls} />);
+
+    // One line in Rigline's diagnostics panel, under this plugin's name. Whether the badge is on
+    // screen is Rigline's to say, and it does; ask what only your own state can answer, and say
+    // `n/a` with a reason when there is nothing to report yet. The host runs this about once a
+    // second, so read state you already keep rather than computing anything here.
+    const stopCheck = ctx.check("tool calls observed", () =>
+      calls.get() === 0
+        ? { verdict: "n/a", detail: "none yet" }
+        : { verdict: "pass", detail: badgeText(calls.get()) },
+    );
+
+    return () => {
+      stopCheck();
+      stopBadge();
+      stopTools();
+    };
+  },
+});

package/template/plugins/__NAME__/tsconfig.json

@@ -1,5 +1,5 @@
 {
   "extends": "../../tsconfig.plugin.json",
-  "include": ["src/**/*.ts"],
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
   "exclude": ["src/**/*.test.ts"]
 }

package/template/tsconfig.plugin.json

@@ -5,7 +5,8 @@
     "lib": ["esnext", "dom"],
     "types": [],
     "noEmit": true,
-    "allowImportingTsExtensions": true
+    "allowImportingTsExtensions": true,
+    "jsx": "react-jsx"
   },
   "files": ["generated.ts"]
 }

package/template/plugins/__NAME__/src/index.ts

@@ -1,82 +0,0 @@
-/**
- * __DESCRIPTION__
- *
- * A worked example of the loop every plugin is: declare what you depend on in `rigline.json`, wait
- * to be handed the element you decorate, and put something beside it. Replace the body; keep the
- * shape.
- */
-import { definePlugin, type PluginContext, type Teardown } from "@rigline/plugin-api";
-
-/**
- * What the badge reads, for a given number of tool calls.
- *
- * Pure, and exported, because this is the half a plain `vitest` run can hold: anything that touches
- * the DOM wants the app itself, and anything that does not should not need it. See
- * `src/index.test.ts`.
- */
-export function badgeText(calls: number): string {
-  if (calls === 0) return "no tools yet";
-  return `${calls} tool ${calls === 1 ? "call" : "calls"}`;
-}
-
-export default definePlugin({
-  setup(ctx: PluginContext): Teardown {
-    let calls = 0;
-    const badge = document.createElement("span");
-    badge.className = "example-badge";
-    badge.textContent = badgeText(calls);
-
-    // Scoped to a class this plugin put on its own element. Never scope a rule to an anchor's bare
-    // class: one class is applied wherever that look is wanted, so a rule written against it lands
-    // on every control wearing it. See the anchors guide.
-    const stopStyle = ctx.style(`
-      .example-badge {
-        font-size: 11px;
-        opacity: 0.7;
-        padding: 0 6px;
-        white-space: nowrap;
-      }
-    `);
-
-    // Every completed tool call the assistant makes. `uses.tools` is what makes this fire; without
-    // the declaration it throws and disables the plugin, which is the point of declaring.
-    const stopTools = ctx.onToolUse(() => {
-      calls += 1;
-      badge.textContent = badgeText(calls);
-    });
-
-    // `watch` hands over the element for an anchor whenever one is in the document, and again if
-    // the app replaces it. No plugin polls for an element.
-    //
-    // `footerSpacer` and `mountBefore` together, rather than any other footer anchor: the composer
-    // footer measures the widths of its own element children to pick a fit stage, and resets that
-    // measurement on any foreign change inside it. A decoration whose membership of the footer
-    // changes with the stage fights the ladder that moved it. The spacer renders in every stage, so
-    // a decoration beside it contributes a constant width and the ladder settles.
-    const stopWatch = ctx.watch("footerSpacer", (spacer) => ctx.mountBefore(spacer, () => badge));
-
-    // One line in Rigline's diagnostics panel, under this plugin's name. It declares nothing: the
-    // host calls it, hands it nothing, and gets a verdict back.
-    //
-    // Worth the four lines from the first day, because the failure a plugin has is normally silent.
-    // An extension update can leave this one loaded, declared, styled and drawing nothing, and
-    // every other line in that panel will say it is fine. Ask the question only your own state can
-    // answer — here, whether the badge is actually in the document — and say `n/a` with a reason
-    // when there is nothing to report yet.
-    //
-    // The host runs this about once a second for the life of the window, so read state you already
-    // keep. Do not walk the DOM or recompute an answer here; do that work where it already happens.
-    const stopCheck = ctx.check("badge is mounted", () =>
-      badge.isConnected
-        ? { verdict: "pass", detail: badgeText(calls) }
-        : { verdict: "fail", detail: "the badge is not in the document" },
-    );
-
-    return () => {
-      stopCheck();
-      stopWatch();
-      stopTools();
-      stopStyle();
-    };
-  },
-});