diegopetrucci/tlh-gui/plugin-guide-maintenance

Maintain the Plugin Guide

The Plugin Guide is bb's public Plugin SDK reference. For a public API change, follow the full workflow. For annotation-only maintenance, start at Maintain annotation layout, skip the public-API section, and then follow the annotation-only verification path.

Confirm a public API change

Build the declarations and inspect the SDK change:

pnpm exec turbo run build:types --filter=@get-bb/plugin-sdk
git diff -- packages/plugin-sdk/package.json packages/plugin-sdk/src

Continue only when the API change affects a Guide card, API symbol list, or fixture. If the Guide remains accurate, do not change it.

New public members also require:

• an experimental_ name, or an Experimental type name;
• an entry in docs/api_to_audit.md;
• compatibility with released SDK users unless the user approves the break.

Find the product source

For a visible method, inspect these sources:

1. The app component that shows the surface.
2. The slot, collector, or adapter that inserts the plugin content.
3. The closest app test that defines the real states.

Record stable source paths and anchors in plugins/plugin-api-docs/src/anatomy-manifest.json. Use labels, roles, data attributes, class constants, and state names as anchors. The @bb/app tests check the anchors against the source.

For a method without a visible surface, use the Plugin backend group. Do not invent interface elements.

Add the Guide entry

For a new Guide entry, run the scaffold command with its sources and symbols:

pnpm exec turbo run scaffold:surface-entry --filter=bb-plugin-plugin-api-docs -- \
  --id <stable-id> \
  --title "<visible-product-object>" \
  --group <group> \
  --source <source-path> \
  --api-symbol <exported-name>

Complete the applicable changes:

• Update plugins/plugin-api-docs/src/surfaces.ts.
• Prefer an existing card unless the API creates a new product surface.
• Keep existing surface IDs stable and list each exact exported symbol.
• Name example plugins in firstParty by display name. A plugin missing from

plugins/plugin-api-docs/src/first-party-plugins.json needs a row there; the @bb/scripts tests check each row against the plugin's manifest.

• For a visible method, update wireframes.tsx and its marker.
• Match the real ownership, labels, roles, order, states, actions, and outcome.
• Keep Guide annotations separate from the product interface.
• Add focused tests for the entry, source anchors, trigger, and outcome.

Maintain annotation layout

Annotation numbers follow the rendered fixture: columns from left to right, then annotations within each column from top to bottom. Read annotations that share a row from left to right.

Treat each annotation's badge, visible target, and interactive overlay as separate layout contracts. Whenever an annotation is added, removed, moved, or renumbered, or its target or surrounding layout changes:

1. Build and reload the real Plugin Guide at each relevant viewport. Redraw the

complete affected sequence, then update surfaces.ts and the focused order test. test/wireframes.test.ts ("draws exactly the surfaces of each visual group on its fixture") fails until the fixture's targets match the group's surface ids.

1. Inspect each rendered badge footprint, including its outline, ring, and

hover scaling. It must remain inside its container, not intersect another badge, and leave its annotated content readable.

1. Inspect target and overlay bounds, including shared edges and nested areas.

An overlay must not enter a sibling surface, cover its content, or capture its hover, focus, or click behavior. A nested child must own its full visible target; do not rely on DOM order or z-index to resolve ownership.

1. Hover, focus, and click every affected badge and visible target. Confirm

that only the matching annotation activates, the full target is reachable, and badge numbers, cards, and previous/next navigation agree.

1. Add or update a focused test for any boundary or ownership rule that could

regress. Every annotation must appear exactly once; DOM nesting alone does not prove correct overlay ownership.

If responsive layouts cannot share one spatial order, fix the layout or define one stable readable sequence before shipping.

Verify the result

For a public API change, run:

pnpm exec turbo run test typecheck lint \
  --filter=@get-bb/plugin-sdk \
  --filter=@bb/app \
  --filter=bb-plugin-plugin-api-docs
bb plugin build plugins/plugin-api-docs

When first-party-plugins.json changes, also run pnpm exec turbo run test --filter=@bb/scripts.

For annotation-only maintenance, use the affected package and Plugin Guide checks required by repository validation policy. Start pnpm dev; inspect the affected entry and reachable actions for a public API change, or the affected annotations and adjacent interactive surfaces for annotation-only maintenance.