ducko-ui

name	ducko-ui
description	End-to-end UI testing for the Ducko macOS app using pre-built helper scripts. This skill should be used when the user asks to "test ducko", "test the app", "run E2E tests", "test the app end-to-end", "test the UI", "send a test message", or wants to verify DuckoApp works from login through messaging.

Ducko UI Test

Run the /macos-ui-testing skill first to load generic macOS UI automation patterns. This skill provides Ducko-specific helper scripts on top.

Each script wraps a single osascript flow so it can be allowlisted in settings.local.json (see Permission Allowlisting at the end).

Window Architecture

DuckoApp ships separate windows:

• Contact List (id: "contacts") — singleton, main window after login (roster, status picker, search).
• Chat (id: "chat") — singleton tabbed window holding every open conversation as a bottom tab (chat-tab-bar); opened/raised by double-click or New Chat. Switching tabs preserves each conversation's draft, search, and sidebar state.
• Contact Info (id: "contact-info", keyed by ContactInfoRef) — Get Info window: identity, roster/subscription state, vCard, and Block/Remove. Opened from the chat header (i) button or a contact's "Get Info" context item.
• Chat Transcripts (id: "transcripts") — singleton history window; the header clock and a contact's "History" context item retarget it to that conversation.
• MenuBarExtra — quick status, Show Contact List, Quit.

The Contacts window has no toolbar. Its actions live in the app menu bar: New Chat (⌘N), Join Room (⌘⇧N), Bookmarks (⌘⇧B) under File; Add Contact (⌘D), My Profile under the Contact menu; sort order + Hide Offline under View. ⌘F reveals the roster search field (contact-search-field). Scripts drive these via keyboard shortcuts or menu-bar clicks (menu bar item ... of menu bar 1), not window buttons.

Prerequisites

• Peekaboo CLI installed (/opt/homebrew/bin/peekaboo)
• Accessibility permissions granted for Terminal/Claude

Scripts

All scripts are in scripts/ relative to this skill. Run from the repo root or use absolute paths.

Scripts target SwiftUI accessibility identifiers, not positional selectors.

Accessibility Identifiers

Identifier	Element	Window
contact-list	Contact list view	Contacts
contact-row-{jid}	Individual contact row (account-qualified as contact-row-{jid}|{account-jid} when the JID is on more than one account)	Contacts
status-picker	Presence status pull-down (status rows with colored dots, saved statuses, per-account override submenus, Custom…) in the "me" header	Contacts
custom-status-message-field	Message field in the status pull-down's Custom… sheet	Contacts
identity-switcher	Identity (account) switcher menu on the "me" header name, shown with 2+ enabled accounts	Contacts
my-avatar	Self avatar in the "me" header	Contacts
status-preferences	Saved-status management list in Preferences ▸ Status	Preferences
saved-status-message-field	Message field in the Preferences ▸ Status add sheet	Preferences
contact-search-field	Roster search field, revealed by ⌘F	Contacts
message-field	Message input text field	Chat
send-button	Send message button	Chat
new-chat-jid-field	JID field in New Chat sheet	Contacts
new-chat-account-picker	Account picker in New Chat sheet (shown only when more than one account is enabled)	Contacts
start-chat-button	Start Chat button in sheet	Contacts
add-contact-jid-field	JID field in Add Contact sheet	Contacts
add-contact-button	Add Contact button in sheet	Contacts
rename-contact-field

Context Menu Features

Contact Row

Right-click a contact row in the contact list:

• Start Chat — open a chat tab with the contact
• Get Info — open the Contact Info window (identity, subscription, vCard, Block/Remove)
• History — open the transcript window scoped to this contact
• Pin / Unpin — pin or unpin the contact to the top of the list
• Mute / Unmute — mute or unmute notifications
• Rename — set a local alias for the contact
• Block / Unblock — block or unblock the contact
• Remove Contact — remove from roster

Room Row

Right-click a room row in the Rooms section:

• Open Chat — open the room chat window
• Pin / Unpin — pin or unpin the room to the top of the list
• Mute / Unmute — mute or unmute notifications
• Invite User — invite a JID to the room
• Room Settings — open room config sheet (owner only)
• Leave Room — leave the room

Participant Sidebar

Right-click a participant in the chat window sidebar:

• Kick — kick participant (moderator required)
• Ban — ban participant (admin/owner required)
• Grant Voice — grant voice to visitor (moderator required)
• Revoke Voice — revoke voice from participant (moderator required)
• Change Nickname — change own nickname (self only)

Script Reference

Script	Purpose	Arguments
ducko-launch.sh	Build and launch DuckoApp, output window ID	none
ducko-import.sh	Switch to Import mode and click Import button	none
ducko-select-mode.sh	Select a setup mode segment on the Welcome screen	<Import|Login|Register>
ducko-login.sh	Fill JID + password, click Connect	JID PASSWORD
ducko-new-chat.sh	Open New Chat sheet from contact list, fill JID, optionally pick the sending account, start chat	JID [ACCOUNT]
ducko-add-contact.sh	Open Add Contact sheet from contact list, fill JID, submit	JID
ducko-send.sh	Type a message and send it in the active chat window	MESSAGE
ducko-screenshot.sh	Capture window screenshot	[FILENAME] (optional, absolute path or relative to /private/tmp/claude/)
ducko-search.sh	Toggle Cmd+F search bar in chat, optionally search	[QUERY] (optional)
ducko-contact-search.sh	Reveal the contact-list search (⌘F), optionally filter the roster	[QUERY] (optional)
ducko-reply.sh	Right-click a message and select Reply	[TEXT] (optional, matches message containing TEXT; default: last message)
ducko-sort.sh	Open the View menu (Sort Contacts / Hide Offline), optionally select sort/filter	[alphabetical|byStatus|recentConversation|hideOffline] (optional)
ducko-join-room.sh	Open Join Room sheet, fill room JID + nickname, join	ROOM_JID [NICKNAME]

Workflow

Fresh install E2E test

For first-time setup when no account exists:

Complete the Welcome screen first. On a fresh profile the first-run Welcome onboarding window holds key/first-responder status. Contact-list actions like Add Contact are gated behind a focus check (Contacts must be the key window), and synthetic automation can't force that focus while Welcome is up — so contact/chat steps silently fail until Welcome is gone. Welcome can't simply be dismissed; you must complete it by logging in through it. The Welcome screen defaults to Import mode, and ducko-login.sh assumes Login mode is already selected, so select the Login segment of the setup-mode-picker segmented control before running it.

The Welcome scripts (ducko-login.sh, ducko-register.sh, ducko-import.sh) walk the Welcome window via the recursive findByAttr handler (like ducko-select-mode.sh) and gate their success message on the osascript result, so a missing field reports an error instead of false success. The login screen's identifiers are covered by UILoginTests (which drives them through the test harness's Swift AX helpers, not this script); the register/import segments have no integration test, so for all three the script's traversal and success-gating are verified by construction.

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch
$SCRIPTS/ducko-launch.sh

# 2. Select Login mode (Welcome defaults to Import)
$SCRIPTS/ducko-select-mode.sh Login

# 3. Log in through Welcome (fresh install only)
$SCRIPTS/ducko-login.sh "USER_JID" "PASSWORD_HERE"

# 4. Screenshot to verify contact list
$SCRIPTS/ducko-screenshot.sh "after-login.png"

# 5. Start a conversation (opens a chat window)
$SCRIPTS/ducko-new-chat.sh "CHAT_PARTNER_JID"

# 6. Send messages in the chat window
$SCRIPTS/ducko-send.sh "Hello from Ducko!"
$SCRIPTS/ducko-send.sh "Testing 1-2-3"

# 7. Screenshot to verify
$SCRIPTS/ducko-screenshot.sh "after-messages.png"

# 8. Cleanup
$SCRIPTS/ducko-stop.sh

Relaunch E2E test (existing account)

When an account already exists, the app auto-connects on launch using Keychain credentials. No login step needed:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch (auto-connects, shows contact list)
$SCRIPTS/ducko-launch.sh

# 2. Screenshot to verify contact list
$SCRIPTS/ducko-screenshot.sh "after-relaunch.png"

# 3. Start a chat and send a message
$SCRIPTS/ducko-new-chat.sh "CHAT_PARTNER_JID"
$SCRIPTS/ducko-send.sh "Relaunch test message"

# 4. Cleanup
$SCRIPTS/ducko-stop.sh

Quick message test (chat window already open)

SCRIPTS="Skills/ducko-ui/scripts"
$SCRIPTS/ducko-send.sh "Quick test message"
$SCRIPTS/ducko-screenshot.sh

Chat UI polish test (message grouping, search, reply)

Tests message grouping, search bar, reply compose bar, and context menu:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch and open a chat
$SCRIPTS/ducko-launch.sh
$SCRIPTS/ducko-new-chat.sh "CHAT_PARTNER_JID"

# 2. Send grouped messages (within 2-min window → single timestamp)
$SCRIPTS/ducko-send.sh "Message one"
$SCRIPTS/ducko-send.sh "Message two"
$SCRIPTS/ducko-send.sh "Message three"
$SCRIPTS/ducko-screenshot.sh "grouped-messages.png"

# 3. Test Cmd+F search
$SCRIPTS/ducko-search.sh "Message two"
$SCRIPTS/ducko-screenshot.sh "search-results.png"
$SCRIPTS/ducko-search.sh  # toggle search off

# 4. Test reply compose bar
$SCRIPTS/ducko-reply.sh "Message one"
$SCRIPTS/ducko-screenshot.sh "reply-bar.png"

# 5. Cleanup
$SCRIPTS/ducko-stop.sh

Contact list sort/filter test

Tests sort modes and hide-offline toggle:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch
$SCRIPTS/ducko-launch.sh

# 2. Open sort menu (visual verification)
$SCRIPTS/ducko-sort.sh
$SCRIPTS/ducko-screenshot.sh "sort-menu.png"

# 3. Select a sort mode
$SCRIPTS/ducko-sort.sh byStatus
$SCRIPTS/ducko-screenshot.sh "sorted-by-status.png"

# 4. Toggle hide offline
$SCRIPTS/ducko-sort.sh hideOffline
$SCRIPTS/ducko-screenshot.sh "hide-offline.png"

# 5. Cleanup
$SCRIPTS/ducko-stop.sh

MUC (Group Chat) test

Tests MUC features — join room, send group message, toggle participant sidebar:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch
$SCRIPTS/ducko-launch.sh

# 2. Join a room (opens Join Room dialog, fills fields, joins)
# The room appears in the "Rooms" section of the contact list
# and a chat window opens automatically.
$SCRIPTS/ducko-join-room.sh "[e-mail]" "mynick"

# 3. Screenshot the room chat
# Shows: room subject banner, sender nicknames (color-coded),
# participant sidebar toggle button (person.2 icon) in header
$SCRIPTS/ducko-screenshot.sh "muc-joined.png"

# 4. Send a group message
$SCRIPTS/ducko-send.sh "Hello room!"
$SCRIPTS/ducko-screenshot.sh "muc-chat.png"

# 5. Toggle participant sidebar
# Shows occupants grouped by affiliation (Owner, Admin, Member, etc.)
$SCRIPTS/ducko-toggle-sidebar.sh
$SCRIPTS/ducko-screenshot.sh "muc-sidebar.png"

# 6. Verify Rooms section in contact list
$SCRIPTS/ducko-focus-contacts.sh
$SCRIPTS/ducko-screenshot.sh "muc-rooms-section.png"

# 7. Cleanup
$SCRIPTS/ducko-stop.sh

Room settings test

Tests room settings — open settings sheet from context menu, view config and affiliations:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch and join a room you own
$SCRIPTS/ducko-launch.sh
$SCRIPTS/ducko-join-room.sh "[e-mail]" "mynick"

# 2. Focus contacts and open Room Settings via context menu
$SCRIPTS/ducko-focus-contacts.sh
$SCRIPTS/ducko-room-settings.sh "[e-mail]"

# 3. Screenshot room settings (General tab with config form)
$SCRIPTS/ducko-screenshot.sh "room-settings-general.png"

# 4. Switch to Members tab to see affiliation list
$SCRIPTS/ducko-room-settings-tab.sh Members
$SCRIPTS/ducko-screenshot.sh "room-settings-members.png"

# 5. Cleanup
$SCRIPTS/ducko-stop.sh

Preferences window test

Tests the Preferences window — open via Cmd+,, navigate tabs, verify account management:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch
$SCRIPTS/ducko-launch.sh

# 2. Open Preferences (Cmd+,)
$SCRIPTS/ducko-preferences.sh

# 3. Screenshot to verify preferences window (General tab by default)
$SCRIPTS/ducko-screenshot.sh "preferences-general.png"

# 4. Navigate to Accounts tab
$SCRIPTS/ducko-preferences-tab.sh Accounts
$SCRIPTS/ducko-screenshot.sh "preferences-accounts.png"

# 5. Navigate to Chat tab (chat states toggle)
$SCRIPTS/ducko-preferences-tab.sh Chat
$SCRIPTS/ducko-screenshot.sh "preferences-chat.png"

# 6. Navigate to Appearance tab (theme grid with live preview bubbles)
$SCRIPTS/ducko-preferences-tab.sh Appearance
$SCRIPTS/ducko-screenshot.sh "preferences-appearance.png"

# 7. Navigate to Notifications and Advanced tabs
$SCRIPTS/ducko-preferences-tab.sh Notifications
$SCRIPTS/ducko-screenshot.sh "preferences-notifications.png"
$SCRIPTS/ducko-preferences-tab.sh Advanced
$SCRIPTS/ducko-screenshot.sh "preferences-advanced.png"

# 8. Cleanup
$SCRIPTS/ducko-stop.sh

Profile editing test

Tests the vCard profile editing flow — open profile sheet, verify fields:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch (account must exist)
$SCRIPTS/ducko-launch.sh

# 2. Open My Profile sheet from the Contact menu
$SCRIPTS/ducko-profile.sh

# 3. Screenshot to verify profile fields loaded
$SCRIPTS/ducko-screenshot.sh "profile-edit.png"

# 4. Cleanup
$SCRIPTS/ducko-stop.sh

Avatar upload/remove test

Tests avatar upload and removal via the profile sheet:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch and open profile
$SCRIPTS/ducko-launch.sh
$SCRIPTS/ducko-profile.sh

# 2. Upload avatar
$SCRIPTS/ducko-avatar.sh "/path/to/test-image.png"
$SCRIPTS/ducko-screenshot.sh "avatar-uploaded.png"

# 3. Remove avatar
$SCRIPTS/ducko-avatar-remove.sh
$SCRIPTS/ducko-screenshot.sh "avatar-removed.png"

# 4. Cleanup
$SCRIPTS/ducko-stop.sh

Device trust management test

Tests OMEMO encryption UI — encryption menu, device fingerprints sheet, and trust actions:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch and open a chat
$SCRIPTS/ducko-launch.sh
$SCRIPTS/ducko-new-chat.sh "CHAT_PARTNER_JID"

# 2. Screenshot to verify encryption menu button in chat header
$SCRIPTS/ducko-screenshot.sh "encryption-menu.png"

# 3. Open the device fingerprints sheet via the encryption menu
$SCRIPTS/ducko-encrypt.sh fingerprints
$SCRIPTS/ducko-screenshot.sh "device-fingerprints.png"

# 4. Verify device rows show trust status
# Each device row has trust-button-{deviceID} or untrust-button-{deviceID}
$SCRIPTS/ducko-screenshot.sh "device-trust-status.png"

# 5. Test encryption preference toggles
$SCRIPTS/ducko-preferences.sh
$SCRIPTS/ducko-preferences-tab.sh Chat
$SCRIPTS/ducko-screenshot.sh "encryption-preferences.png"

# 6. Cleanup
$SCRIPTS/ducko-stop.sh

Presence/status test

Tests setting presence status and status message:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch
$SCRIPTS/ducko-launch.sh

# 2. Set status to Away
$SCRIPTS/ducko-status.sh away
$SCRIPTS/ducko-screenshot.sh "status-away.png"

# 3. Set status with a message
$SCRIPTS/ducko-status.sh dnd "In a meeting"
$SCRIPTS/ducko-screenshot.sh "status-dnd-message.png"

# 4. Back to Available
$SCRIPTS/ducko-status.sh available
$SCRIPTS/ducko-screenshot.sh "status-available.png"

# 5. Cleanup
$SCRIPTS/ducko-stop.sh

Bookmarks management test

Tests bookmark lifecycle — open bookmarks, add, verify, remove:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch
$SCRIPTS/ducko-launch.sh

# 2. Open bookmarks
$SCRIPTS/ducko-bookmarks.sh
$SCRIPTS/ducko-screenshot.sh "bookmarks-list.png"

# 3. Add a bookmark
$SCRIPTS/ducko-add-bookmark.sh "[e-mail]" "mynick"
$SCRIPTS/ducko-screenshot.sh "bookmark-added.png"

# 4. Remove the bookmark
$SCRIPTS/ducko-remove-bookmark.sh "[e-mail]"
$SCRIPTS/ducko-screenshot.sh "bookmark-removed.png"

# 5. Cleanup
$SCRIPTS/ducko-stop.sh

Message retraction test

Tests sending and retracting a message:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch and open a chat
$SCRIPTS/ducko-launch.sh
$SCRIPTS/ducko-new-chat.sh "CHAT_PARTNER_JID"

# 2. Send a message
$SCRIPTS/ducko-send.sh "This message will be retracted"
$SCRIPTS/ducko-screenshot.sh "before-retract.png"

# 3. Retract the message
$SCRIPTS/ducko-retract.sh "This message will be retracted"
$SCRIPTS/ducko-screenshot.sh "after-retract.png"

# 4. Cleanup
$SCRIPTS/ducko-stop.sh

OMEMO encryption test

Tests encryption toggle, device fingerprints sheet, and device trust:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch and open a chat
$SCRIPTS/ducko-launch.sh
$SCRIPTS/ducko-new-chat.sh "CHAT_PARTNER_JID"

# 2. Enable encryption
$SCRIPTS/ducko-encrypt.sh on
$SCRIPTS/ducko-screenshot.sh "encryption-enabled.png"

# 3. Open device fingerprints sheet
$SCRIPTS/ducko-encrypt.sh fingerprints
$SCRIPTS/ducko-screenshot.sh "device-fingerprints.png"

# 4. Trust a device (replace DEVICE_ID with actual ID from screenshot)
# $SCRIPTS/ducko-device-trust.sh 12345 trust
# $SCRIPTS/ducko-screenshot.sh "device-trusted.png"

# 5. Cleanup
$SCRIPTS/ducko-stop.sh

Room management test

Tests full room lifecycle — join, topic, nickname, file attachment, leave:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch and join a room
$SCRIPTS/ducko-launch.sh
$SCRIPTS/ducko-join-room.sh "[e-mail]" "mynick"

# 2. View current topic
$SCRIPTS/ducko-room-topic.sh
$SCRIPTS/ducko-screenshot.sh "room-topic-view.png"

# 3. Set a new topic
$SCRIPTS/ducko-room-topic.sh "Welcome to the test room!"
$SCRIPTS/ducko-screenshot.sh "room-topic-set.png"

# 4. Toggle sidebar and change nickname
$SCRIPTS/ducko-toggle-sidebar.sh
$SCRIPTS/ducko-change-nickname.sh "newnick"
$SCRIPTS/ducko-screenshot.sh "nickname-changed.png"

# 5. Leave the room
$SCRIPTS/ducko-focus-contacts.sh
$SCRIPTS/ducko-leave-room.sh "[e-mail]"
$SCRIPTS/ducko-screenshot.sh "room-left.png"

# 6. Cleanup
$SCRIPTS/ducko-stop.sh

Live-update (cross-driver) test

Verifies that an open chat/room window reflects server-pushed changes (subject, participant list, presence) live, without reopening the tab — by driving a second occupant from DuckoCLI while the GUI stays joined. This exercises the live-read path that backs the chat header, window title, and participant sidebar.

SCRIPTS="Skills/ducko-ui/scripts"

# 0. One-time: configure account B in its OWN profile (a fresh DUCKO_PROFILE has no account,
#    and `interactive` needs one). See the ducko-cli skill for `account add` flags.
DUCKO_PROFILE=clibot .build/debug/DuckoCLI account add ...

# 1. GUI joins the room as account A and stays on the tab
$SCRIPTS/ducko-launch.sh
$SCRIPTS/ducko-join-room.sh "[e-mail]" "observer"
$SCRIPTS/ducko-screenshot.sh "live-before.png"   # header shows e.g. "1 participant"

# 2. Account B (a DISTINCT account, its own DUCKO_PROFILE) joins from the CLI as a second occupant.
#    The REPL supports /join <room-jid> [nick], /topic <subject>, /nick <newnick>.
#    Needs dangerouslyDisableSandbox (raw TCP + writes under ~/Library/Application Support).
printf '/join [e-mail] clibot\n' \
  | DUCKO_PROFILE=clibot .build/debug/DuckoCLI interactive

# 3. Bring DuckoApp frontmost WITHOUT relaunching (CSI active flushes queued pushes), then screenshot.
#    Do NOT use ducko-launch.sh here — it kills and relaunches, destroying the joined tab.
osascript -e 'tell application "System Events" to set frontmost of process "DuckoApp" to true'
$SCRIPTS/ducko-screenshot.sh "live-after.png"
# Assert: header participant count 1 -> 2 and the sidebar lists clibot — live, no tab reopen.

# 4. Cleanup
$SCRIPTS/ducko-stop.sh

• The GUI must be frontmost while observing. DuckoApp sends XEP-0352 CSI inactive whenever it is not the frontmost app, and the server then queues MUC presence/subject pushes, flushing them only on CSI active. A background-driven observation sees a stale header/subject and wrongly concludes the live-read is broken — activate the app (set frontmost) before screenshotting; do not relaunch.
• Subject-change variant. Ad-hoc MUC rooms restrict /topic to moderators, so the first occupant to join a fresh room owns it. To test a live subject update, have account B join the empty room first (becoming owner) and keep its REPL session open while the GUI joins as a guest, then issue /topic <subject> and assert room-subject-view updates live. Participant-count and presence updates (above) need no ownership and work from any second occupant.
• Use a separate DUCKO_PROFILE for the CLI account so its credentials and SwiftData don't collide with the GUI profile.

File attachment test (full)

Tests attaching and sending a file:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch and open a chat
$SCRIPTS/ducko-launch.sh
$SCRIPTS/ducko-new-chat.sh "CHAT_PARTNER_JID"

# 2. Attach a file
$SCRIPTS/ducko-attach.sh "/path/to/test-file.png"
$SCRIPTS/ducko-screenshot.sh "file-attached.png"

# 3. Send (the attached file appears in pending-attachments bar, send delivers it)
$SCRIPTS/ducko-send.sh "Here's a file"
$SCRIPTS/ducko-screenshot.sh "file-sent.png"

# 4. Cleanup
$SCRIPTS/ducko-stop.sh

Connection info test

Tests viewing TLS connection details:

SCRIPTS="Skills/ducko-ui/scripts"

# 1. Launch (must be connected)
$SCRIPTS/ducko-launch.sh

# 2. Open connection info
$SCRIPTS/ducko-connection-info.sh
$SCRIPTS/ducko-screenshot.sh "connection-info.png"

# 3. Cleanup
$SCRIPTS/ducko-stop.sh

Reconnect (app disconnected)

If the app is running but disconnected (e.g. network drop), restart it to trigger auto-connect:

SCRIPTS="Skills/ducko-ui/scripts"
$SCRIPTS/ducko-connect.sh

Permission Allowlisting

To allow these scripts in settings.local.json without prompts:

{
  "permissions": {
    "allow": [
      "Bash(Skills/ducko-ui/scripts/*)"
    ]
  }
}

Notes

• Scripts use keystroke (not set value) to trigger SwiftUI bindings.
• App activation uses set frontmost of process (works with SwiftPM builds).
• When the app is not frontmost it sends XEP-0352 CSI inactive, and the server queues MUC presence/subject pushes until CSI active — so verifying any live update (subject, participant count, presence) requires the app frontmost first, or the observation reads stale.
• Multi-step interactions are bundled in single osascript blocks to avoid focus loss.
• Element targeting uses recursive UI-element-tree walks (findByAttr and siblings) rather than entire contents, which silently collapses on the deeply-nested SwiftUI / NSTableView accessibility trees on macOS 26 (contact/room rows, the Welcome window, chat transcript, profile/room-settings sheets). Helper-consumer scripts share these handlers via ducko-helpers.sh's ducko_as_handlers; quoted-heredoc scripts (the Welcome family, profile/room-settings, etc.) inline the same handler — mirroring ducko-select-mode.sh — because a quoted heredoc can't expand $(...). Scripts whose targets are shallow (small sheets like New Chat, Add Contact, Join Room) still use entire contents where it reliably reaches them. SwiftUI segmented Picker segments and Room Settings tabs expose their label via AXDescription (not name/AXTitle), so they are matched on that.
• The scripts marked best-effort in the Script Reference table (ducko-status.sh, ducko-chat-tabs.sh, ducko-connection-info.sh, ducko-change-password.sh) hit osascript limitations covered authoritatively by the integration suite instead; each table row names the specific control and test.
• The contact list and chat windows are both singletons (Window). The chat window holds all open conversations as bottom tabs (chat-tab-bar); ducko-send.sh targets the active tab in the frontmost chat window. Contact Info is a WindowGroup keyed by ContactInfoRef.
• Arguments passed via osascript - "$ARG" << 'APPLESCRIPT' + on run argv (no shell injection).
• Credentials are arguments, never hardcoded.