Skip to content

Hide rules and z-order #12

Closed
Closed

Description

@omesser

Depends on: #1

Status

Hand-checked 2026-09-02; code fix for fullscreen 2026-09-02 via #189:

Why

A companion that knows when to disappear is the difference between a pet and malware. The
investment goes into hiding, not into stacking cleverness.

Scope

One fixed window level, always on top. Restacking by sprite state is rejected — it
produces flicker on every platform, and peeking out from behind windows is given up
deliberately. See DESIGN.md decision 8.

Hiding is implemented as visibility rules:

  • A fullscreen application is frontmost.
  • Screen sharing is active.
  • Do Not Disturb is on.
  • A global hotkey toggles hide and show.

Acceptance criteria

  • The buddy fades out when a fullscreen application takes the front.
  • The buddy is not visible during screen sharing.
  • The buddy is quiet under Do Not Disturb.
  • The hotkey hides and shows instantly.
  • No flicker or restacking is observable during normal window switching.

Tests

Manual, on a real machine, including a real screen share.


Spec: docs/SPEC.md · migrated from docs/issues/0012-hide-rules-and-z-order.md

Activity

  1. omesser commented on Aug 30, 2026

    @omesser
    OwnerAuthor

    Do Not Disturb is descoped. Oded's call, on #83: "no need to respect DND then. we can ignore it."

    So the scope bullet "Do Not Disturb is on" and the acceptance criterion "The buddy is quiet under Do Not Disturb" no longer apply. Three rules remain: a fullscreen application is frontmost, screen sharing is active, and the hotkey.

    Why it was raised

    #83 built the rule and could not read the condition. macOS keeps the live Focus state behind ~/Library/DoNotDisturb/DB/, which needs Full Disk Access, or INFocusStatusCenter, which opens a consent dialog on first ask. DESIGN.md decision 9 forbids the Spatial Layer from spending a permission, and the old com.apple.notificationcenterui key no longer exists on this OS. The alternative to descoping was asking the user for Full Disk Access so the buddy could stay still — a bad trade for a rule the hotkey already covers.

    What still references it

    Three places outside this issue, for whoever lands #83:

    • DESIGN.md:226 — decision 8 lists Do Not Disturb among the hide conditions.
    • docs/SPEC.md:120 — user story 27, "I want the buddy to respect Do Not Disturb."
    • Take the Character off screen when it is in the way #83's own Desktop::do_not_disturb, its arm in hides(), platform::do_not_disturb(), the tests that exercise it, and the README paragraph explaining that it is not wired.

    Note that the screen-sharing criterion is met by a different mechanism than a hide rule: #83 sets the overlay panel to NSWindowSharingType::None, so it is excluded from every capture at all times rather than detected and hidden. macOS publishes no way to learn that your screen is being shared, so there is nothing to detect.

  2. omesser commented on Aug 30, 2026

    @omesser
    OwnerAuthor

    Superseding the descope above: Do Not Disturb stays, as ours rather than the OS's.

    Oded's call: "if we can't access the OS's DND, let's make our own... it should be something we can select in some menu (right click on the character, or on the app icon)."

    So the rule and its tests in #83 are kept and repurposed. What changes is only where the condition comes from:

    • Was: platform::do_not_disturb() reads macOS Focus state. Unreadable without Full Disk Access or a consent dialog, so it returned a constant false.
    • Now: a setting ai-buddy owns, toggled by the user from the menu and persisted across launches. No permission, no probe, and it works the same on any platform.

    The platform probe comes out. The rule, Desktop::do_not_disturb, its arm in hides(), and the overlapping-rules test all stay — and they stop being coverage of something nothing sets.

    DESIGN.md:226 and user story 27 at docs/SPEC.md:120 both stay too, but should say the mode is ai-buddy's own rather than implying macOS's.

    What it needs that does not exist yet

    Somewhere to toggle it. Recorded on #18, which owns the menu definition that the tray icon and the right-click Menu verb (#6) both open. Until #18 lands, nothing sets the flag — the hotkey is what to use meanwhile.

    One thing worth deciding while it is being built

    As specified, ai-buddy's Do Not Disturb and the hotkey do the same thing: both take the Character off screen and both outlast the desktop. The difference is only that one fades and one is instant. If Do Not Disturb is meant to be quiet rather than gone — no dialogue, no Director proposals, but still on screen — that is a different rule and a better justification for its own name. User story 27 says "quiet", which points that way. Flagging it here rather than choosing.

  3. omesser commented on Aug 30, 2026

    @omesser
    OwnerAuthor

    Correcting both comments above: Do Not Disturb leaves this issue entirely. It is not a hide rule. Filed as #84.

    Oded settled it: "let's distinguish 'do not disturb' — which should make it go to sleep or suspend other interactions which in the future it may initiate — from 'go away' or something similar, which would make it visually disappear."

    Do Not Disturb means the buddy stays on screen and stops starting things: no Director proposals, nothing said unprompted, and it settles rather than pacing. Poke, Grab and Throw still work, because the user initiating is the exception that defines the mode. That is #84, and it belongs to the Director rather than to visibility.

    Hiding is the other mode — "go away" — and this issue already has it, as the hotkey.

    What this issue keeps

    Two conditions take the Character off screen, not four:

    • A fullscreen application is frontmost. Fades out and back.
    • The user asked it to go away, by hotkey today and from the menu once Tray and settings #18 lands. Instant, and it outranks the fullscreen rule.

    Screen sharing is met by a different mechanism than a rule: #83 sets the overlay panel to NSWindowSharingType::None, so it is excluded from every capture at all times. macOS publishes no way to learn that your screen is being shared, so there is nothing to detect and nothing to hide on.

    Scope and acceptance criteria to strike

    What #83 has to change

    Desktop::do_not_disturb, its arm in hides(), platform::do_not_disturb(), and the tests that exercise it all come out — the rule was never a visibility rule. hides() collapses to the fullscreen condition alone. DESIGN.md:226 lists Do Not Disturb among the hide conditions and needs correcting; user story 27 at docs/SPEC.md:120 is correct as written and now points at #84.

  4. omesser commented on Sep 1, 2026

    @omesser
    OwnerAuthor

    Verified against main at 762b2a8. Every line of code this issue asks for is in, landed by #83. What remains is the manual pass, which this issue's Tests line always said it would be.

    The two rules, as the comments above left them

    Criterion Evidence
    Fades out when a fullscreen application takes the front visibility.rs:173 fullscreen_frontmost, computed each tick from the real window list and display frames at main.rs:633. Not a constant.
    No flicker or restacking during window switching One level, set once: overlay_panel.rs:92 setLevel: NSFloatingWindowLevel. Nothing restacks by sprite state anywhere.
    The hotkey hides and shows instantly main.rs:314 register_hide_hotkey, Control-Option-Command-B. A hotkey another application holds is reported and let go rather than fatal.
    The hotkey outranks the rules visibility.rs:356 — a Character sent away stays away across a fullscreen application coming and going.
    Not visible during screen sharing overlay_panel.rs:98 sets NSWindowSharingType::None, so the overlay is excluded from every capture rather than detected and hidden. AI_BUDDY_CAPTURABLE opts back in to ReadOnly for demos and recordings.

    hides() collapses to the fullscreen condition alone plus the hotkey's away flag, and Desktop carries only fullscreen_frontmost. No Do Not Disturb arm, no platform::do_not_disturb(), no tests for either — the descope landed cleanly.

    Two things worth knowing

    The do_not_disturb references still in the tree are not leftovers from this issue. They are in director.rs and engine.rs, where the mode refuses proposals and withholds unprompted dialogue — #84's territory, and it looks partly built already.

    DESIGN.md:275 and user story 27 at docs/SPEC.md:120 both read correctly: DND is named as not a hide rule, and the story points at #84.

    What is left

    Nothing to implement. The acceptance criteria are manual by design, and README steps 16–20 cover them: the fade out and back, a fullscreen application on either of two displays, the hotkey both ways, and the hotkey outranking a rule. #91 separately carries hand-verifying absence from a real screen share.

    Closeable once that pass is run on a real machine.

  5. omesser commented on Sep 2, 2026

    @omesser
    OwnerAuthor

    Manual pass recorded in the Status checklist.

    Fullscreen hide does not hold: the Character fades out and then comes right back. That is #188, and it blocks this issue.

    The other criteria are done or owned elsewhere: hotkey works (no conflict logged), z-order is accepted, screen-share exclusion is #91, Do Not Disturb is #84.

  6. omesser commented on Sep 2, 2026

    @omesser
    OwnerAuthor

    #188’s fullscreen blink is fixed on main via #189 (Dock/menu-bar strips no longer count as frontmost). Leave this open until README step 16 is re-checked on a real machine; then the remaining Status checkbox can be marked done.

  7. omesser commented on Sep 2, 2026

    @omesser
    OwnerAuthor

    Fullscreen hide re-checked on a real machine after #189: native Full Screen stays hidden; zoom / ⌘⌥F does not hide. Status line ticked.

  8. omesser commented on Sep 2, 2026

    @omesser
    OwnerAuthor

    done

  9. added this to the V1 milestone on Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestready-for-agentFully specified, ready for an AFK agent

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions