An auto tiler for macOS
parcel docs interaction-roadmap.md
23 kB · 277 lines
Markdown
at main

Window interaction roadmap #

Source baseline: 99636e44233ebb3ef7ec52bdc30ca86cbad2dcf4 (clean at audit start). The audit and target contracts below describe the original planning pass. The implementation is now integrated; validation evidence and remaining scope are recorded separately below. A passing scenario certifies only its tested case.

Existing contracts and gaps #

Area Already present Work remaining
Three tiles ParcelCore/TileTree.swift standard Side gives a half-width full-height tile beside stacked neighbors. Grid insertion can also produce this. Balanced Grid rebuild differs; adaptive defaults choose landscape Grid and portrait Rows. Normalize the automatic three-tile case without overriding explicit strategies. Side has a separate ultrawide variant: selecting Side everywhere is insufficient.
Primary ParcelCore/Commands.swift swaps the selected window into the first stack; WindowGestures.swift full-height promotion moves a stack first. Neither preserves a right-side source. Define spatial primary identity independently of first traversal position.
Shared divider ParcelCore/LayoutEngine.swift exposes TileEdge branch paths, subtree membership, gap frames and fraction constraints. ParcelEngine/MouseModel.swift already drags gaps live; UndoHistory.swift coalesces the gesture. Add the hover indicator using the existing hit eligibility and parent/child relationships. Do not implement a second resize system.
Hover actions Existing top margins hold a subtle grip, hover growth and a compact three-action dwell row. Default is enabled, 0.6 seconds; explicit disabled preferences remain respected. Both pointer and keyboard invocation include configured shortcuts. Continue native occlusion and gesture-priority coverage; match shared-divider growth to the action grip.
Focus ParcelCore/ParcelCore.docc/FocusModes.md defines reversible usable-bounds expansion preserving the tile tree; independent No peek/Clean Space already exist. Consistent “Exit Focus” action wording and truthful reverse-action feedback. Native fullscreen remains a separate command.
Feedback ParcelUI/Feedback/ has transient notices, announcements and dismissal; EngineShellServices.swift already formats an Automatic tiling reverse hint from configuration. Action notices need bottom-center placement, typed action context and effective reverse-binding resolution. Existing placement is bottom-right; default dismissal is four seconds.
Menu ParcelUI/Menu*.swift already routes commands to captured workspaces, reconciles native menus and supplies previews, limits, shortcuts and mode state. Improve visual hierarchy and direct quick controls; retain routing, problem rows and secondary-click menu.

All source paths above are under Sources/. Preserve the baseline's keyboard-first, on-demand stack UI, native structural drag/resize outline previews and Undo. There is no persistent app-height reservation: grips, chips, bars, feedback and dividers are overlays. Showing or hiding any of them must leave window frames unchanged.

Behavior decisions #

Automatic layout and Primary — Core #

  • For an untouched adaptive landscape workspace with exactly three tile slots, use one full-height primary at 50% of available width and two equal-height neighbors. Subtract configured gaps before dividing. Apply consistently on insertion, rebuild and restore; count tiles, not windows inside stacks.
  • Apply only where learned minimum sizes fit. Otherwise retain the existing feasible adaptive layout/room policy; never force invalid frames. Keep portrait policy and explicitly selected strategies, including ultrawide Side, intact. Explicit selection clears adaptation as today. User-adjusted topology/ratios remain authoritative until explicit reset; ordinary focus changes never rebuild.
  • Initial primary is the existing designated primary, otherwise the first retained tile; initial side is left. Primary on a tile left of the workspace center keeps it left; a tile right of center stays right. A center tie keeps the current primary side, falling back to left. Determine side from pre-action tile geometry, not pointer location or keyboard focus after the operation.
  • In the adaptive three-tile arrangement, promoting a right neighbor makes it the full-height right primary. The old primary and remaining neighbor form the left stack of tiles, ordered by their former center Y, with traversal order breaking ties. Retain feasible column and neighbor ratios; use 50/50 only when none exist. Move the whole tile stack, preserving its members and selection.
  • An explicit strategy is never silently changed by Primary. Promote into that strategy's primary slot on the source side where supported; for strategies with equal slots, record the primary designation without rearranging them. Publish capability/state so UI does not promise expansion for an equal-slot strategy. Existing Primary shortcuts and pointer actions must use this same operation.
  • Store primary tile identity/side as explicit workspace data if tree structure cannot carry it reliably. Version persistence, migrate old state deterministically and include it in Undo. One changed promotion creates one Undo; repeating it is a no-op. Structural full-height gestures retain their explicit layout-changing contract, but use the same side decision.

Divider hover and resize — Core #

  • Enabled with existing mouse gap resizing. Show a centered line up to 48×3 points (4 with Increase Contrast), parallel to the eligible divider, shortened to fit the segment. Fade in/out over 120 ms through ParcelAnimation; immediate visibility for motion-off/Reduce Motion. Keep the line visible during capture; use the axis-appropriate resize cursor.
  • Reveal only within a positive, genuine shared tile gap. Outer margins, zero gaps, app content, floating occluders and suspended workspaces do not qualify. Reuse MouseInputSnapshot topmost-window checks and observed geometry. Preserve the existing at-most-2-point app-edge input tolerance; the indicator does not widen it, and pointer reveal itself requires the true gap. The overlay is click-through; input remains with the existing mouse pipeline.
  • The full-height divider resizes the parent split, affecting the primary and both neighbors. The neighbors' horizontal divider changes only their split. Keep deterministic nearest-edge selection at T junctions, with the existing shallower-branch tie-break. Clamp to learned minimum sizes and usable bounds.
  • Reuse live resize and existing structural previews. Escape restores the captured ratio. Target closure, topology replacement, Space/display change, permission loss or input cancellation aborts; restore only still-valid captured state, never resurrect vanished windows. Changed release makes one Undo, cancelled or return-to-start gestures none. Keep double-click reset and keyboard resize paths.

Grip states and placement #

The top action grip and shared resize dividers share a small rounded-pill visual, but have different behavior. Keep them inside existing margins; never reserve window height or create a new rail.

Surface / state Appearance Interaction
Active tile, top gap at rest Small horizontal pill with transparent or very low-opacity treatment Reveals the action affordance without covering the title bar
Top gap hovered White pill, slightly thicker and wider than its resting shape Retain a generous gap-contained hit region; dwell opens Primary, Focus/Exit Focus, Float/Tile
Shared divider hovered Centered white pill, length and thickness grow slightly Show the axis-appropriate resize cursor; dragging changes the shared split
Shared divider captured Keep its emphasized shape visible at the live divider Follow the drag; retain minimum-size constraints, Escape and one Undo
Pointer leaves Return smoothly to the resting treatment or hide an inactive handle Cancel pending dwell and preserve the popover exit grace

A horizontal gap can also be the top margin of the tile below it. Where one handle has both roles, dragging adjusts the shared split while dwelling opens actions for that identified tile. Vertical dividers remain resize-only. Confirm the target/highlight and hit priority in a native prototype before shipping; orientation alone must not choose an action target. Exact resting/hover dimensions, opacity, growth and dwell timing need native light/dark, contrast, reduced-motion and narrow-gap review. Use the active palette's contrasting equivalent when white would lose contrast.

Top action grips now use verified existing margins, with separate resting and hover geometry and compact dwell actions. Shared divider handles still fade at a fixed size; matching their growth and sharing the visual treatment remain polish work. Native gap occlusion and gesture priority require acceptance checks.

Compact dwell controls — Integration #

  • Enable hover controls by default and preserve explicit saved preferences; default dwell remains 600 ms. Observe an existing top-center margin, widening only within that margin for stacked windows. Never reserve app height or intercept native title-bar input. A selected tab is a wide pill; other members are small grabbable dots. Clicking selects a member; dragging moves it into another tile’s stack with Escape and Undo.
  • Show Primary | Focus | Float, changing labels to Exit Focus and Tile from current target state. Put a layout/expand/PiP icon left of each label and the actual configured shortcut below it. Omit unbound hints and expose spoken help. Add an app-icon/name tab row only for multiple members, with previous/next arrows selecting relative to the active member and keeping it visible. Keep Move to Display and Always float in explicit/secondary controls; do not remove their command routes.
  • Mouse actions remain available without a keyboard binding. Unavailable actions remain visibly disabled; reverse hints omit unbound or inactive shortcuts. Keyboard invocation remains available through the existing configured controls command; this work adds no hard-coded product shortcut.
  • Open the popover under the dwell pointer, clamped inside usable bounds. Preserve its anchor through tab selection and layout readback. Deliberate dwell can temporarily overlay the target; never place actions beyond pointer reach. Do not enlarge gaps or reserve app height to make it fit.
  • Allow two seconds after the pointer leaves; reentry cancels dismissal. Retain while pointer or keyboard focus is inside. Do not use a large bounding rectangle that accidentally keeps controls alive across app content. Reset dwell on target or geometry change. Click outside, native drag, Escape, target loss, Space change or permission loss dismisses immediately and cancels pending presentation.
  • Passive reveal never changes key focus. Explicit invocation focuses the first enabled button; Tab/arrows navigate, Return/Space invoke, Escape dismisses and restores the still-valid target. Validate window/workspace again before dispatch and after asynchronous work. Dispatch exactly once through the engine.

Focus and reverse-action feedback — Integration #

  • Use “Focus” for expansion into usable bounds minus configured reserved edges and outer gaps. Use “Exit Focus” for restoration. Never label this Fullscreen or call the native fullscreen API. Preserve existing Focus exit triggers and per-Space behavior; restoration uses the current valid layout if membership changed.
  • After a confirmed changed action, show one non-key, click-through notice at the affected display's usable bottom center, 20 points above its lower edge, for 2.5 seconds. Latest action replaces the previous transient notice. Keep actionable room/error notices in their existing channel; no modal notices.
  • Example template: Focus • %@ to put it back, with %@ resolved from the actual effective focus-toggle binding. Float uses its Tile reverse; Primary and divider resize use Undo only when that recorded transaction is still the latest valid reversible operation. Exit Focus can simply say Focus ended.
  • Resolve from active configuration and registration availability, including active keybinding mode, shortcuts-off, failed registration and Secure Input. Never show a default chord as fallback. Missing/unavailable reverse binding produces plain state text; do not advertise a shortcut that acts on a different target. Drop or refresh the hint when configuration, active target or undo validity changes.
  • Integration owns a shared presentation resolver using ShortcutDisplay.swift glyphs and spoken key names. Observe command completion/state transitions so menu, keyboard and HoverBar produce the same result without duplicate notices. Engine acceptance alone is not frame success: await existing readback where applicable; constrained/refused writes use existing failure feedback instead.
  • Primary activation, including keyboard and accessibility presses, opens a transient SwiftUI popover. Retain the native secondary-click menu and fallback when the status item cannot anchor the panel, with captured display–Space routing. Use a 380-point panel with 16-point content margins, quiet secondary text, rounded sections and selection outlines. Keep Settings, Keyboard Shortcuts and More in a pinned footer; scroll within usable display height and wrap translated labels.
  • Order: status and Automatic tiling switch; arrangement preview; labeled compact layout choices (Grid, Columns, Rows, Side) and window-cap choices; Retile, Highlights and Hover Focus quick actions; Focus/Exit Focus, No peek and Clean Space rows; current-app tiling; Settings, Keyboard Shortcuts and Quit footer. Keep all strategies, Main Size and No limit reachable in native submenus.
  • Preview uses the same LayoutSnapshot/capability result as commands. Show chosen strategy and resolved variant separately. A cap limits tile slots; it neither creates windows nor changes strategy. Unsupported choices stay visible with a disabled reason. Do not invent app identities absent from the snapshot.
  • Preserve problem/permission rows, menu tracking stability and independent modes. Discrete actions dismiss; continuous sliders retain their existing behavior. Native fallback items expose equivalent keyboard/VoiceOver actions.

Ownership and delivery order #

Paths below are relative to Sources/ unless prefixed with Tests/. Shared integration files have one writer; owners provide interface requests to root.

Phase Owner and exclusive files Dependency / exit condition
1. Layout contract Core: ParcelCore/{AdaptiveLayouts,TileTree,LayoutEngine,Commands,WindowGestures,UndoHistory}.swift, necessary workspace persistence and ParcelEngine layout/mouse files Establish primary identity/side, adaptive policy, capabilities and readback/completion payloads before final UI integration.
2a. Divider Core: ParcelEngine/{MouseModel,MouseInputSnapshot,DragLayoutPreview}.swift; new divider controller/view in ParcelUI/Overlays/ Reuse phase 1 geometry; publish presentation state for integration to wire. No HoverBar/Menu edits.
2b. Menu UI: ParcelUI/Menu*.swift, new MenuQuickControls.swift, menu-specific tests Visual work can start on baseline snapshots; final previews and Primary capability consume phase 1. No geometry or HoverBar implementation.
2c. Dwell/feedback Integration: ParcelUI/HoverBar/, ParcelUI/Feedback/, shared shortcut presentation, ParcelConfig/HoverBarConfiguration.swift if needed, related tests Compact sizing/dwell can proceed independently; Primary delivery and verified success hints depend on phase 1.
3. Integration Integration: ParcelApp/{NativeAppRuntime,AppFeedback,EngineShellServices}.swift, shared resources/catalogs, configuration/IPC adapters and lane manifests Wire the divider overlay and menu once. Owners submit catalog keys; integration prevents conflicting shared edits.
4. Acceptance Each owner supplies lane-specific tests; integration coordinates integration runs Pass the matrix below and repository gates before declaring implementation complete.

All new UI text belongs in String Catalogs with translator context. Native buttons need labels, state, disabled reasons and stable AX identifiers. Divider resizing must retain keyboard command equivalents. Announce completed actions once, not every drag sample. Respect Increase Contrast and Reduce Transparency; use ParcelAnimation for motion and preserve the repo's macOS/toolchain baseline.

Automated acceptance matrix #

Lane / existing test homes Required assertions
Core Swift Testing: AdaptiveLayoutTests, LayoutInsertionTests, WindowGestureTests, TileEdgeTests, UndoHistoryTests, AdaptiveUndoHistoryTests Three-tile insertion/rebuild equivalence; both primary sides and center tie; stacks preserved; explicit strategies and custom ratios unchanged; minimum-size refusal; parent vs child resize; one Undo/no-op/cancel; persisted-side migration.
Engine: MouseModelTests, MouseClaimDecisionTests, MouseGesturePipelineTests, MouseIntegrationTests Hover/input agreement; zero/narrow gaps and ≤2-point edge tolerance; T junctions; occlusion and observed-frame mismatch; stale topology/permission cancellation; no write from hover alone.
UI/App unit: HoverBar/HoverBarTests, FeedbackTests, ShortcutDisplayTests, AppFeedbackTests; menu owners extend MenuWorkspaceTests, CommandMenuParityTests, FocusModeMenuTests Injected-clock dwell/grace/dismiss boundaries; safe-placement failure; target replacement; configured/remapped/unbound/disabled/mode-specific reverse hints; invalidated Undo; one dispatch/notice; captured-workspace routing; capability-consistent previews.
Native-host: MenuBarControllerTests, overlay tests and new hosted divider/HoverBar cases Real NSView/NSMenu hit testing, focus traversal, AX actions/labels, click-through and no focus theft; light/dark, long translations, contrast/transparency/motion settings; menu reopening/tracking stability. Register new suites in the correct lane manifest.
Locked FixtureApp E2E: MouseEndToEndTests, MouseGestureEndToEndTests, AccessibilityDragEndToEndTests, AdaptiveLayoutEndToEndTests, HoverControlsEndToEndTests, FocusModesEndToEndTests, FeedbackEndToEndTests, MenuPanelEndToEndTests Independently read real frames for left-one/right-two and mirror; parent/child drag; Escape and single Undo; constrained resizing; Primary then Undo; Focus then reverse with a remapped chord; unchanged native Space/fullscreen status; no app-height change when UI appears. Test stale targets, hot-plug and Automatic tiling off with explicit actions.

Use observable completion barriers and bounded waits, not timing sleeps. Live lanes require the shared screen lock and isolated fixtures; absent permissions are not a pass. Implementation gates remain build-with-tests, unit, lint, script tests, app assembly and affected native/live lanes per CONTRIBUTING.

Release dependencies and limits #

No blocker to this roadmap. Spatial Primary and adaptive-policy persistence are the substantive model work; do not claim them complete from the existing Side layout. Passive popovers can temporarily overlay their target below the title bar when no free margin fits; deliberate dwell is required and app height is never reserved. Effective-binding availability and verified command completion need explicit integration seams before reverse hints ship. Menu polish and divider rendering can proceed independently, but final acceptance waits for those shared contracts.

Integrated delivery and remaining scope #

Adaptive three-tile geometry, spatial Primary, shared-divider handles, compact margin dwell controls and menu quick controls are implemented. The primary menu surface now uses a transient SwiftUI popover with native menu fallbacks. Explicit strategy choices and saved hover preferences remain authoritative. Primary identity and side use retained tile order and tree geometry without a persistence schema change.

Bottom-center reverse hints currently follow confirmed hover-control actions. They await settlement and use effective registered shortcuts; unbound or mismatched targets receive state text only. A common completion path for menu, keyboard and divider actions remains follow-up work. This release does not add gesture-triggered learning prompts or modal resize notices.

The full screen-free suite passes 4,824 tests. Targeted native UI coverage passes 164 tests, including unseeded native mouse interception. The broader acceptance matrix above remains the release checklist; these counts do not establish spoken VoiceOver, every display/Space transition, or every application-specific gesture. Live frame checks are recorded in the QA evidence produced by the integration run.

Native input verification #

Mouse interception now runs after the window server annotates the target window. The earlier session stage reports zero target IDs for unseeded events on this machine. Native input drivers leave those IDs unset so tests exercise the real annotation path; their owned-process and pickup checks remain in place.

Hover, divider and fixture point checks use AppKit's mouse hit-test API, rather than treating a system canvas's full-screen bounding rectangle as an input region. Unknown positive window IDs remain unavailable. A native desktop identity may belong to a genuine shared gap; menus, floating windows and other actual input surfaces keep priority. Tap callbacks use native event metadata and cached values; they make no AppKit or AX calls.

Native acceptance includes a real three-window parent resize with independent frame readback and Undo, and a fixture shared-edge resize with live peer updates and Escape. The fixture uses the owned edge tolerance rather than posting a click through a gap occupied by an unrelated user window. Empty-gap ownership is also covered by native identity and desktop/model tests; that does not certify every background-app arrangement.

Confirmed native findings during integration also required two engine fixes: window controls now consume confirmed presentation frames without replacing the reducer's last user observations; no-op tiled frame notifications preserve the active resize Undo transaction. Mouse-up test commands await the gesture/reducer barrier before another command is issued. These preserve one Undo per resize instead of turning each pointer update into a separate entry.