Plugin Guide v1: in-app plugin API docs with SDK-synced surface map - #2248
Open
brsbl wants to merge 19 commits into
Open
Plugin Guide v1: in-app plugin API docs with SDK-synced surface map#2248brsbl wants to merge 19 commits into
brsbl wants to merge 19 commits into
Conversation
Documents the bb plugin API as an annotated map of the product plus the generated reference behind it. - apps/web/scripts/generate-plugin-api-docs.mjs parses the SDK's committed bundled declarations into a committed model; --check fails when stale. - packages/plugin-api-map holds the surface inventory, the bb UI skeletons, and the annotation cards, shared so the docs page and the in-app plugin cannot disagree about what bb can be extended with. - plugins/plugin-api-docs renders that map inside bb as a nav panel, with the host's real composer embedded in the composer and home diagrams. - The docs page leads with the reference; the diagram sits below it as a supporting explainer. - An anatomy manifest pins the skeletons to the real app component order, and apps/app's docs-anatomy-manifest test fails when the app reorders. - apps/web route changes animate through the View Transition API, content only, with reduced motion falling back to an instant swap. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
These changes were already uncommitted in this worktree when the plugin API docs work began and are unrelated to it: blog rendering, landing analytics and endpoints, connect/auth routes, server token handling, and small web UI primitive tweaks. Committed separately so they can be reviewed or dropped on their own. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The bb Plugin Guide (plugins/plugin-api-docs, rendering packages/plugin-api-map) becomes bb's only plugin API documentation: six slides — annotated skeletons of the app window, composer, home, settings, and Extensions plugin pages, plus a backend capability grid — with a reviewed card per surface, cross-references, and "Used by" links. packages/plugin-api-map/test/api-sync.test.ts fails the build when the map and the SDK drift apart; the apps/web docs route, generated API model, and generator are deleted in its favor. Host and SDK changes the guide rides on, all additive: - experimental_suppressPluginUi on experimental_NewThreadComposer, plumbed through the new-thread prompt box path, so an embedded composer can render without other plugins' composer UI (a prompt improver's action was landing inside the diagrams and rewriting the persisted example draft). - Route anchors inside plugin UI navigate client-side; links to a plugin's Extensions page open it beside the current pane. - New plugin-detail pane kind so a plugin's Extensions page can live in a split; ordinary navigation to it stays full-window. - Plugin CSS is awaited before registrations publish, removing the unstyled first-paint flash on plugin load and reload. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…-ready-thr_kg7xb7qipg
…-ready-thr_kg7xb7qipg
…-ready-thr_kg7xb7qipg # Conflicts: # apps/web/src/styles.css
…l-fixes-thr_7f4g7pd89a # Conflicts: # apps/app/package.json # pnpm-lock.yaml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was wrong
bb's plugin API documentation was split across generated web pages and implementation details, so plugin authors had no single product-native map showing where each capability appears. The Plugin Guide v1 establishes the in-app guide as that documentation surface while preserving existing plugin contracts.
What changed
This is layer 1 of the planned three-layer stack. It is based on current
main, contains no inspector mode, and can merge independently before the additive Core inspection APIs and the inspector consumer.plugins/plugin-api-docs) backed bypackages/plugin-api-map, with annotated product diagrams, capability cards, cross-references, and shipped-plugin usage links.11is in the conversation timeline renderer, while marker10remains the separate file viewer. The command-palette action surface is also represented.plugin-detailrendering, and CSS-before-registration activation ordering.experimental_pluginCustomizations?: "all" | "none". Omission and"all"preserve the shipped composed experience;"none"renders bb's composer without globally registered plugin banners, actions, + menu rows, draft highlighting, or draft observers. This lets any embedded composer consumer isolate its example or workflow while retaining bb's real composer.@get-bb/plugin-sdkfrom the released0.4.14baseline to0.4.15for that additive API, with a persisted0.4.14scaffold upgrade regression proving an installed plugin remains running and API-compatible after the host upgrade.bbPluginSdk >=0.4.3; the Guide does not claim the unpublished0.4.15integration target. No existing field changes meaning, and there is no unrelated engine-floor, daemon-protocol, or permissions-model change.How you verified
Exact pushed head:
d0e24849a7cde08733fc711daec4c3184f31dc49, based onmainatc3b588c8fa62dc817b52773fe8fb0303e6321d05.@get-bb/plugin-sdk@0.4.15remains unpublished@get-bb/plugin-sdktests — 129/1290.4.14scaffold upgrade regression@bb/domain,@bb/server,@get-bb/plugin-sdk, and the Plugin Guide — PASSgit diff --check origin/main...HEAD— PASS11timeline renderer;10file viewer), and command-palette surfaceNative before and after
Both captures come from
scripts/bb-dev-app current --desktopat the exact compared revisions. They use isolated empty dev data, the same canonical route/plugins/plugin-api-docs/plugin-api, the initial unscrolled state, light theme, and identical native window bounds: 1280×900 pt at x=80/y=80 (2560×1800 Retina output).Before —
mainatc3b588c8fa62dc817b52773fe8fb0303e6321d05The canonical Guide route has no registered panel.
After — exact PR head
d0e24849a7cde08733fc711daec4c3184f31dc49The built-in Guide is registered and its first product-map surface places Code & diff renderers in the timeline, separate from the file viewer.
No linked issue.
BB-Thread-ID: thr_7dczktandc
BB-Thread-ID: thr_7f4g7pd89a