Add a Tips plugin with a fresh feed of contextual tips under the new-thread composer

.bb/skills/tips-authoring/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: tips-authoring
+description: "Add or update a tip in bb's built-in Tips plugin end to end: copy, action, illustration from the diagram kit, eligibility, tests, stories, and PR."
+---
+
+# Author a Tips plugin tip
+
+`plugins/tips/AUTHORING.md` is the canonical rulebook: fields, voice, action
+types, illustration rules, and the checklist. Read it first; this skill only
+orders the work.
+
+1. **Pick the source.** Start from a changelog entry, a guide or blog page, or a
+   feature people miss. Set `source`, `addedAt` (the release it ships in), and
+   `reviewedAt`. Add `expiresAt` only for tips about a release or a limited-time
+   change.
+2. **Write the copy** in `plugins/tips/catalog.ts` to AUTHORING.md's voice
+   and length rules: describe the outcome, not the mechanism. Add the id to `TIP_IDS` in `plugins/tips/contract.ts` and to
+   `TIP_TELEMETRY_IDS` in `packages/server-contract/src/api/system.ts`; tests
+   fail when the three lists differ.
+3. **Choose one action type.** Use `open-plugin` only for plugins in
+   `apps/server/src/services/plugins/builtin-registry.ts`, and `open-page` only
+   for the plugin store or core Settings routes. For multi-step setup, use a walkthrough prompt
+   from `walkthroughPrompt(goal)`, which asks for a playground when that tool
+   is available and numbered steps otherwise; AUTHORING.md's Walkthrough
+   prompts section has the wording and rules.
+4. **Draw the illustration** in `plugins/tips/illustrations.tsx` from
+   `diagram-kit.tsx` parts, with one accent and one named hover animation. Add a
+   kit part, plus a Diagram kit story cell, only when a second drawing needs it.
+5. **Set `tier`, `eligible`, `retireWhen`, and any `boost`.** Use
+   `"unranked"` unless the owner placed the tip in a tier; AUTHORING.md's
+   Tiers section explains the order. Never record metrics in the repo. Add `engine.test.ts`
+   cases when the logic is new.
+6. **Check it in Ladle.** Open the `plugins/Tips` Illustrations and Diagram kit
+   stories, and hover the new drawing in light and dark.
+7. **Open or update the PR** with before and after screenshots of the New
+   thread feed from the branch dev app. Let CI run the tests.

apps/app/.ladle/config.mjs

@@ -44,6 +44,7 @@ export default {
     "../../plugins/automations/*.stories.tsx",
     ".ladle/workflows.stories.tsx",
     "../../plugins/provider-usage/*.stories.tsx",
+    "../../plugins/tips/*.stories.tsx",
   ],
   defaultStory: "",
   viteConfig: "./.ladle/vite.config.ts",

apps/app/src/components/plugin/PluginHomepageSections.tsx

@@ -6,16 +6,27 @@ import { useRouteState } from "@/hooks/useRouteState";
 import { getPluginHomepageSectionAnchor } from "@/lib/plugin-homepage-section";
 import { PluginSlotMount } from "./PluginSlotMount";
 
-export function PluginHomepageSections() {
+export function PluginHomepageSections({
+  setupComplete,
+}: {
+  setupComplete: boolean;
+}) {
   const { homepageSections } = usePluginSlots();
   if (homepageSections.length === 0) return null;
-  return <PluginHomepageSectionList sections={homepageSections} />;
+  return (
+    <PluginHomepageSectionList
+      sections={homepageSections}
+      setupComplete={setupComplete}
+    />
+  );
 }
 
 function PluginHomepageSectionList({
   sections,
+  setupComplete,
 }: {
   sections: readonly PluginHomepageSectionSlot[];
+  setupComplete: boolean;
 }) {
   const { projectId } = useRouteState();
   return (
@@ -26,15 +37,20 @@ function PluginHomepageSectionList({
           id={getPluginHomepageSectionAnchor(section.pluginId, section.id)}
           className="space-y-3"
         >
-          <h2 className="text-sm font-semibold text-foreground">
-            {section.title}
-          </h2>
+          {section.title !== undefined ? (
+            <h2 className="text-sm font-semibold text-foreground">
+              {section.title}
+            </h2>
+          ) : null}
           <PluginSlotMount
             pluginId={section.pluginId}
             slotKind="homepageSection"
             slotId={section.id}
           >
-            <section.component projectId={projectId ?? null} />
+            <section.component
+              projectId={projectId ?? null}
+              experimental_setupComplete={setupComplete}
+            />
           </PluginSlotMount>
         </section>
       ))}

apps/app/src/components/plugin/PluginNewThreadComposer.test.tsx

@@ -246,6 +246,9 @@ vi.mock("@/hooks/queries/sidebar-navigation-query", () => ({
         },
 }));
 
+vi.mock("@/components/onboarding/useSetupComplete", () => ({
+  useSetupComplete: () => true,
+}));
 vi.mock("@/hooks/queries/host-queries", () => ({
   useHosts: () => ({
     data: [

apps/app/src/components/plugin/plugin-slot-mounts.test.tsx

@@ -138,12 +138,65 @@ describe("PluginHomepageSections", () => {
     );
     render(
       <MemoryRouter initialEntries={["/"]}>
-        <PluginHomepageSections />
+        <PluginHomepageSections setupComplete />
       </MemoryRouter>,
     );
     expect(screen.getByText("plugin broken crashed")).toBeDefined();
     expect(screen.getByText("fine section body")).toBeDefined();
   });
+
+  it("renders a heading only for sections that declare a title", () => {
+    function Body() {
+      return <div>untitled section body</div>;
+    }
+    setPluginSlotRegistrations(
+      "titled",
+      registrationSet({
+        homepageSections: [{ id: "a", title: "Titled", component: Body }],
+      }),
+    );
+    setPluginSlotRegistrations(
+      "untitled",
+      registrationSet({
+        homepageSections: [{ id: "b", component: Body }],
+      }),
+    );
+    render(
+      <MemoryRouter initialEntries={["/"]}>
+        <PluginHomepageSections setupComplete />
+      </MemoryRouter>,
+    );
+    expect(
+      screen.getAllByRole("heading").map((heading) => heading.textContent),
+    ).toEqual(["Titled"]);
+    expect(screen.getAllByText("untitled section body")).toHaveLength(2);
+  });
+
+  it("tells sections whether bb setup is complete", () => {
+    function Setup({
+      experimental_setupComplete,
+    }: {
+      experimental_setupComplete?: boolean;
+    }) {
+      return <div>setup complete: {String(experimental_setupComplete)}</div>;
+    }
+    setPluginSlotRegistrations(
+      "setup",
+      registrationSet({ homepageSections: [{ id: "a", component: Setup }] }),
+    );
+    const view = render(
+      <MemoryRouter initialEntries={["/"]}>
+        <PluginHomepageSections setupComplete={false} />
+      </MemoryRouter>,
+    );
+    expect(screen.getByText("setup complete: false")).toBeDefined();
+    view.rerender(
+      <MemoryRouter initialEntries={["/"]}>
+        <PluginHomepageSections setupComplete />
+      </MemoryRouter>,
+    );
+    expect(screen.getByText("setup complete: true")).toBeDefined();
+  });
 });
 
 function ThreadDraftViewer({ threadId }: { threadId: string }) {

apps/app/src/components/promptbox/PromptBoxInternal.test.tsx

@@ -58,10 +58,12 @@ import {
   resetPluginThreadRowStatusesForTest,
 } from "@/lib/plugin-thread-row-status";
 import {
+  removePluginSlotRegistrations,
   resetPluginSlotStoreForTest,
   setPluginSlotRegistrations,
   type PluginRegistrationSet,
 } from "@/lib/plugin-slots";
+import { getComposerPlaceholderPreview } from "@/lib/composer-placeholder-previews";
 import {
   PluginComposerHostProvider,
   type PluginComposerHost,
@@ -2690,6 +2692,80 @@ describe("PromptBoxInternal plugin composer actions", () => {
     });
   });
 
+  it("shows a plugin placeholder preview in place of the placeholder and clears it on unmount", async () => {
+    function PreviewAction() {
+      const composer = useComposer();
+      return (
+        <>
+          <button
+            type="button"
+            onClick={() =>
+              composer.experimental_setPlaceholderPreview("Try this prompt")
+            }
+          >
+            Preview prompt
+          </button>
+          <button
+            type="button"
+            onClick={() => composer.experimental_setPlaceholderPreview(null)}
+          >
+            Clear preview
+          </button>
+        </>
+      );
+    }
+    setPluginSlotRegistrations(
+      "previewer",
+      pluginRegistrationSet([
+        {
+          id: "tools",
+          actions: [{ id: "preview", component: PreviewAction }],
+        },
+      ]),
+    );
+    const draft = emptyPromptDraftState();
+    const host: PluginComposerHost = {
+      scope: { kind: "new-thread", projectId: null },
+      textEffectKey: "promptbox-placeholder-preview-test",
+      getCurrent: () => draft,
+      subscribeDraft: () => () => {},
+      setDraft: vi.fn(),
+      focus: vi.fn(),
+    };
+    render(
+      <MemoryRouter>
+        <PluginComposerHostProvider value={host}>
+          <PromptBoxInternal
+            {...createPromptBoxProps({ placeholder: "Ask anything" })}
+          />
+        </PluginComposerHostProvider>
+      </MemoryRouter>,
+    );
+    const editor = getPromptEditorElement();
+    expect(editor.getAttribute("data-placeholder")).toBe("Ask anything");
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview prompt" }));
+    await waitFor(() => {
+      expect(editor.getAttribute("data-placeholder")).toBe("Try this prompt");
+    });
+    expect(editor.getAttribute("aria-label")).toBe("Ask anything");
+
+    fireEvent.click(screen.getByRole("button", { name: "Clear preview" }));
+    await waitFor(() => {
+      expect(editor.getAttribute("data-placeholder")).toBe("Ask anything");
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview prompt" }));
+    await waitFor(() => {
+      expect(editor.getAttribute("data-placeholder")).toBe("Try this prompt");
+    });
+    act(() => removePluginSlotRegistrations("previewer"));
+    await waitFor(() => {
+      expect(editor.getAttribute("data-placeholder")).toBe("Ask anything");
+    });
+    expect(getComposerPlaceholderPreview(host.textEffectKey)).toBeNull();
+  });
+
   it("remounts scoped actions and releases owned state when scope identity changes", () => {
     const mounted = vi.fn();
     const cleaned = vi.fn();

apps/app/src/components/promptbox/PromptBoxInternal.tsx

@@ -94,6 +94,7 @@ import {
   usePluginComposerViewModel,
 } from "@/components/plugin/plugin-composer-host";
 import { useComposerInputLock } from "@/lib/plugin-sdk-hooks";
+import { useComposerPlaceholderPreview } from "@/lib/composer-placeholder-previews";
 import {
   COARSE_POINTER_PROMPT_ACTION_BUTTON_CLASS,
   COARSE_POINTER_PROMPT_ICON_ACTION_BUTTON_CLASS,
@@ -1590,10 +1591,14 @@ export function PromptBoxInternal({
       (value.trim().length === 0 &&
         attachments.length === 0 &&
         !pendingUploads?.length));
-  const effectivePlaceholder = showCompactLayout
+  const pluginComposerHost = usePluginComposerHost();
+  const placeholderPreview = useComposerPlaceholderPreview(
+    pluginComposerHost?.textEffectKey ?? null,
+  );
+  const hostPlaceholder = showCompactLayout
     ? (compact.placeholder ?? placeholder)
     : placeholder;
-  const pluginComposerHost = usePluginComposerHost();
+  const effectivePlaceholder = placeholderPreview ?? hostPlaceholder;
   const composerInputLocked = useComposerInputLock(
     pluginComposerHost?.textEffectKey ?? null,
   );
@@ -2028,7 +2033,7 @@ export function PromptBoxInternal({
       immediatelyRender: false,
       editorProps: {
         attributes: {
-          "aria-label": effectivePlaceholder,
+          "aria-label": hostPlaceholder,
           "data-placeholder": effectivePlaceholder,
           ...(onModifierSubmit
             ? { "aria-keyshortcuts": modifierSubmitShortcutAria() }
@@ -2403,11 +2408,11 @@ export function PromptBoxInternal({
     placeholderRef.current = effectivePlaceholder;
     if (!editor) return;
 
-    editor.view.dom.setAttribute("aria-label", effectivePlaceholder);
+    editor.view.dom.setAttribute("aria-label", hostPlaceholder);
     editor.view.dom.setAttribute("data-placeholder", effectivePlaceholder);
     editor.view.dom.setAttribute("enterkeyhint", editorEnterKeyHint);
     editor.view.dispatch(editor.state.tr);
-  }, [editor, editorEnterKeyHint, effectivePlaceholder]);
+  }, [editor, editorEnterKeyHint, effectivePlaceholder, hostPlaceholder]);
 
   useEffect(() => {
     if (!editor) return;

apps/app/src/components/settings/tips-catalog-routes.test.ts

@@ -0,0 +1,37 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { isSettingsSectionId } from "./settings-sections";
+
+const catalogModuleSchema = z.object({
+  TIP_CATALOG: z.array(
+    z.object({
+      id: z.string(),
+      action: z.object({ kind: z.string(), path: z.string().optional() }),
+    }),
+  ),
+});
+
+const catalogPath = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../../plugins/tips/catalog.ts",
+);
+
+describe("Tips catalog routes", () => {
+  it("points every open-page tip at the plugin store or a core Settings route", async () => {
+    const { TIP_CATALOG } = catalogModuleSchema.parse(
+      await import(pathToFileURL(catalogPath).href),
+    );
+    for (const tip of TIP_CATALOG) {
+      if (tip.action.kind !== "open-page") continue;
+      const { pathname } = new URL(tip.action.path ?? "", "http://bb.local");
+      if (pathname === "/plugins") continue;
+      const [, root, section, pluginId] = pathname.split("/");
+      expect(root, tip.id).toBe("settings");
+      if (section === undefined) continue;
+      expect(isSettingsSectionId(section), tip.id).toBe(true);
+      if (section === "plugins") expect(pluginId, tip.id).toBeDefined();
+    }
+  });
+});

apps/app/src/lib/composer-placeholder-previews.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import {
+  getComposerPlaceholderPreview,
+  setComposerPlaceholderPreview,
+} from "./composer-placeholder-previews";
+
+describe("composer placeholder previews", () => {
+  it("shows the most recent preview and falls back as owners clear", () => {
+    const storageKey = "composer-placeholder-previews-latest";
+    const first = Symbol("first");
+    const second = Symbol("second");
+
+    setComposerPlaceholderPreview(storageKey, first, "First preview");
+    setComposerPlaceholderPreview(storageKey, second, "Second preview");
+    expect(getComposerPlaceholderPreview(storageKey)).toBe("Second preview");
+
+    setComposerPlaceholderPreview(storageKey, first, "First again");
+    expect(getComposerPlaceholderPreview(storageKey)).toBe("First again");
+
+    setComposerPlaceholderPreview(storageKey, first, null);
+    expect(getComposerPlaceholderPreview(storageKey)).toBe("Second preview");
+
+    setComposerPlaceholderPreview(storageKey, second, null);
+    expect(getComposerPlaceholderPreview(storageKey)).toBeNull();
+  });
+
+  it("keeps composers independent and ignores a null storage key", () => {
+    const owner = Symbol("owner");
+    setComposerPlaceholderPreview("composer-a", owner, "Only in A");
+    setComposerPlaceholderPreview(null, owner, "Nowhere");
+    expect(getComposerPlaceholderPreview("composer-a")).toBe("Only in A");
+    expect(getComposerPlaceholderPreview("composer-b")).toBeNull();
+    expect(getComposerPlaceholderPreview(null)).toBeNull();
+    setComposerPlaceholderPreview("composer-a", owner, null);
+  });
+});