Repository navigation
docs(sdk): add ui.present to the Lua surface reference - #182
Merged
Merged
Conversation
Document the presentation-only overlay session added for bitty#2849 on top of the CTX-1431 session: - sdk/reference/ui.md: add ui.present to the closed Ui head set, a presentation-only overlay section (admission, placement, focus-follow, frame budget, dismissal, teardown, safe mode), the ordered show error table, the overlay.dismissed observation, and an example; update the overlay slot row, limits, and references to bitty@8108e4f7. - extensibility/plugin-ui-slot-inventory-candidate.md: describe the capture-free presentation path on the overlay slot and the separate ui.present head. - sdk/reference/README.md: cite the presentation overlay test path. The accepted Plugin API v1 Lua Surface RFC is left unchanged; the head is recorded as post-ratification host fact rather than an amendment. Refs #2849
Xuepoo
force-pushed
the
docs/2849-ui-present
branch
from
November 3, 2026 11:32
2e5385b to
9b06491
Compare
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
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.
Refs #2849
Summary
Documents
ui.presentin the plugin API reference: the presentation-only overlay session merged in bitty-terminal/bitty#2856 (issue bitty#2849), where a granted plugin draws one non-focusable, non-modal panel above the focused view with no input capture.sdk/reference/ui.md: addsui.presentto the closedUihead set and a Presentation-only overlay (ui.present) section — named Lua verbs (bitty.ui.present.show/hide) with thebitty.ui.overlay.show/hidealias, an admission/placement table (grant, admission, second claimant, placement, no input, focus-follow, frame budget, dismissal, teardown, safe mode), the orderedshowerror table, theoverlay.dismissedobservation, an example, plus updates to theoverlayslot row, Limits, and References pinned atbitty@8108e4f7.extensibility/plugin-ui-slot-inventory-candidate.md: theoverlayslot row, inventory rules 4 and 6, and the overlay divergence bullet now record the capture-free presentation path and the separateui.presenthead (draw authority is not input authority).sdk/reference/README.md: citescrates/bitty-runtime/tests/presentation_overlay_api.rsfor thebitty.uirow.The accepted
sdk/plugin-api-v1-lua-surface-rfc.mdis deliberately not edited: its closed L2 gate text predates the head, and listingui.presentthere would claim ratification it did not receive. The reference page records it as current host fact and the divergence is stated explicitly. Nostatus:field was promoted —sdk/reference/ui.mdstaysdraftand the slot inventory staysdraft.Everything asserted is read from
bitty@8108e4f7:crates/bitty-runtime/src/plugin_runtime/presentation_overlay.rs,services.rs(require_presentation_overlay,ui_overlay_show_with_expiry,ui_overlay_hide),crates/bitty-runtime/src/runtime/present.rs(paint order,PRESENTATION_OVERLAY_MIN_COLS/_MAX_ROWS/_MAX_BYTES),crates/bitty-lua/src/host.rs(thepresenttable),crates/bitty-plugin-host/src/capability.rs,crates/bitty-package/src/manifest.rs, andcrates/bitty-terminal/src/terminal_app.rs.Verification
npx --yes prettier@3.9.6 --check . --ignore-unknown→ "All matched files use Prettier code style!" (rc=0)npx --yes markdownlint-cli2@0.23.1→ 0 issues in 105 files (rc=0)check-docs.mjs links→ 105 files, no broken links or fragments (rc=0)check-docs.mjs metadata→ 105 files, frontmatter schema valid (rc=0)check-docs.mjs language→ 105 files, English only (rc=0)check-docs.mjs agentsandcheck-docs.mjs hygiene→ rc=0bun/bunxsegfault in this environment, so the justfile's pinned prettier and markdownlint versions were run through npx, andcheck-docs.mjswas run under node with the literal.github/scriptspath substituted forimport.meta.dirin a scratch copy (the repository script is unmodified).