qiu7824/zsclip/zsclip-native-ui

ZSClip Native UI

Use this skill to work on the native UI host layer without turning AppKit or GTK into a second copy of the product.

Quick Start

1. Read references/native-ui-entrypoints.md first for the file map and current completion vocabulary.
2. Read docs/zsui.md for the architecture boundary.
3. Read docs/ui-host-porting.md when adding or changing host surfaces.
4. Read docs/native-host-verification.md before claiming macOS or Linux completion.
5. Inspect the relevant Rust entry points instead of guessing from UI labels.

Layer Rules

• Keep reusable contracts, action plans, layout/render plans and parity metadata in src/app_core/.
• Keep ZSClip behavior, DB mutations, settings persistence, sync, and AI execution in the product adapter or product modules.
• Keep AppKit/GTK host files thin: create native windows/widgets, wire callbacks, call shared actions, and invoke host traits.
• Do not create a new cross-platform UI framework for a feature that already has a shared action plan or host trait.
• Do not report a macOS/Linux feature as complete just because Windows-side tests pass. Use code-level, target-smoke, and system-complete separately.

Common Workflow

1. Identify the feature surface: main window, row menu, group management, VV, settings, clipboard, status/menu, dialog, shell-open, file picker, or identity.
2. Check the shared contract in src/app_core/ before editing platform code.
3. Edit the platform host only for native presentation or OS service calls:

• macOS: src/macos_app.rs, src/macos_native_host.rs, src/macos_appkit_adapter.rs
• Linux: src/linux_app.rs, src/linux_native_host.rs, src/linux_gtk_adapter.rs
• Windows reference host: src/app.rs, src/windows_win32_adapter.rs

1. Route behavior through shared actions such as NativeHostRowAction, NativeHostSettingsAction, NativeHostStatusMenuAction, NativeHostVvPastePlan, product command ids, and host traits.
2. Update docs and source guards when a new host surface, smoke log, or platform proof expectation is added.
3. Run local Rust checks, then require target OS smoke artifacts before marking macOS/Ubuntu runtime completion.

Completion Reporting

When answering progress questions, separate:

• code-level: shared Rust contract and native host route exist and local tests pass.
• target-smoke: the real AppKit/GTK process produced logs/screenshots on the target OS.
• system-complete: the OS integration is proven, including permissions, focus handoff, real paste delivery, tray/status behavior, or interactive dialogs where relevant.

Use zsui_native_feature_parity_statuses() and docs/native-host-verification.md as the source of truth for feature progress. If the current machine is Windows, say that AppKit/GTK runtime proof still requires macOS/Ubuntu artifacts.

Verification

Local checks:

cargo fmt --check
cargo check
cargo test

Target smoke checks:

bash scripts/native-host-smoke-macos.sh
bash scripts/native-host-smoke-linux.sh

Store and inspect target artifacts under target/native-host-smoke/<platform>/ before calling the platform verified.