docs(spec): record the plugin UI slot inventory and composition rules (CTX-0042)

[Xuepoo]

Priority: P1 | Area: UI/docs | Labels: docs, P1, area:ui, area:plugins | Milestone: v0.1.0 | RFC: OQ-056 | Task: CTX-0042

What

Answers dimension 1 of OQ-056 (semantic UI slots) as the Plugin Roadmap records it: "a documented slot inventory with per-slot bounds and conflict resolution so overlay/status composition stops being implicit."

Record is Draft: nothing accepted, nothing promoted to Verified/Compatible, no accepted text edited beyond an index row.

Closes #78 · Docs task CTX-0042

New record

extensibility/plugin-ui-slot-inventory-candidate.md

Slot inventory — per-slot purpose, multiplicity, required capability, and bounds for the accepted closed eight-slot set (terminal | top | bottom | left | right | tabline | statusline | overlay):

Slot	Multiplicity	Required capability
terminal	composing, bounded	ui.rich
top / bottom / left / right	composing, bounded	—
tabline	exclusive (accepted rule)	—
statusline	composing, bounded (8 x 64 / 128 budget)	—
overlay	layered, bounded, ordered	ui.overlay

Composition rules — every contribution consumes one RichBlock against the accepted budget; bounds are per contributor unless stated; required capability is checked at mount, not at render; placement stays host-owned; no slot is a focus target.

Conflict resolution — a second exclusive claim is denied with a typed error naming the current declarant and leaves the incumbent untouched; composing/layered aggregate bounds are enforced at admission and fail closed; layered paint order is a pure function of declared order; a denied contribution changes nothing; conflicts are never resolved by silent replacement; unmounting another plugin's handle is not authorized by any v1 capability.

Relation to host surfaces — the terminal-side chrome contract owns the rendering surfaces; this record owns only the plugin-facing admission side. The terminal slot composes with a leaf and can never replace grid, cursor, or scrollback presentation.

Modified

• extensibility/README.md — index registration (prettier normalized table alignment, hence the reflow).

Constraints honored

• Additive only: no slot added, renamed, or re-bounded; the accepted v1 slot set, SceneNode subset, handle/block_id model, and ui.rich/ui.overlay gating are restated as consumed.
• Section spine conformant for document_type: specification.
• Gate evidence (run in this worktree):

metadata      Validated 69 Markdown files without network access
links         Validated 69 Markdown files without network access
language      Validated 69 Markdown files without network access
hygiene       Validated 69 Markdown files without network access
markdownlint  Summary: 0 issues in 0 files
prettier      All matched files use Prettier code style
commitlint    clean (just commit-check)

Review ask

• Independent docs review by a different agent (per workspace lifecycle).
• Specifically: confirm the inventory adds nothing to the accepted closed set, and that conflict handling is stated as fail-closed and non-replacing.

[Xuepoo]

Self-review pass (before external review completed) found and fixed two fidelity defects in commit cb254c3:

1. Capability gate — the Required capability column read ui.rich for the terminal slot only, with a dash for the other composing slots. The accepted Plugin API v1 Lua Surface RFC gates the whole L2 UI surface: ui.rich is required for bitty.ui.mount/bitty.ui.update contributions regardless of slot, and the overlay slot additionally requires ui.overlay. Every row now states the accepted gate.
2. Statusline budget — the row attributed a numeric "8 components x 64 chars, 128 total" budget to the terminal side. The draft Status System Specification states a capped total segment count with bounded per-module lengths and no such numeric budget — the row now states what that draft states.

Also replaced "per-terminal block budget (64)" phrasing with the accepted scene-limits table (SCN-1..SCN-5) so bound names match the accepted source.

No slot added, renamed, or re-bounded; no accepted rule changed. All gates re-run green (metadata/links/language/hygiene, markdownlint 0 issues, prettier clean) on 69 files.

[Xuepoo]

Review findings addressed in a0b7831 (four of five; the first was already fixed in cb254c3, which landed while the review was running):

1. Capability column — already aligned in cb254c3. The review read the pre-fix table (all eight rows now read ui.rich, overlay reads ui.rich + ui.overlay, and rule 4 states the gate covers every slot because content-scoped rich requirements apply to all mount contributions). No further change needed; please re-check against HEAD.
2. Own-handle unmount asserted as v1 — accepted. Rule 6 now binds the accepted baseline (bitty.ui.mount/bitty.ui.update only; handle generation-owned and disposed with its generation) and marks explicit owner release as a candidate addition; rule 5 matches. The Alternatives row was reworded accordingly.
3. Rule 2 fixed an order that Open points lists as undecided — accepted. Rules 2 and 3 now require determinism as a pure function of declaration and defer the tie-break (manifest / mount / declared priority) to the Open point.
4. LUA-OQ-11 paraphrase over-broadened — accepted. The host-surface bullet now cites the accepted trigger (Panel RFC redefining overlays as focusable surfaces) and separates this record's own statement from the accepted disposition.
5. README "Both pages" — accepted; reworded to "These pages", covering the four-row index.

Gates re-run green (69 files, markdownlint 0 issues, prettier clean).

[Xuepoo]

Independent verification review returned APPROVE on a0b7831: it touches exactly the two intended files, resolves the four addressed findings with substantive (non-cosmetic) edits, and leaves the cb254c3 capability column untouched and byte-identical. Review ledger: round 1 (pre-fix) REQUEST CHANGES on five findings → cb254c3 (capability column, landed during round 1) + a0b7831 (the other four) → round 2 verification APPROVE.