ShadowCode’s strongest Apple Silicon upgrade combines a more discoverable workspace with trustworthy execution and resource state. The audited 2.4.0 baseline already provides Metal support, project-grouped conversations, recoverable editor work, task review and explicit check receipts; those foundations should be preserved. The most consequential gaps concern how users reach those capabilities, whether commands and focus behave consistently, and whether local-model readiness reflects current shared-memory conditions. Official Apple guidance and editor documentation support clearer navigation, resizable work surfaces and progressive disclosure, while source inspection identifies bounded memory-accounting and cancellation defects. The recommended immediate direction is to complete the ongoing toolbar/resizable-panel work, then extend review/check visibility and runtime admission through focused changes. Every change described here is a proposal unless explicitly identified as baseline behavior; this report makes no implementation-completion or performance claim. Verified implementation and test outcomes belong in the separate MAC_FLAGSHIP_UPGRADE.md. (2.4.0 changes, existing review/check evidence)
This November 11, 2026 synthesis uses three research notes: Mac interaction, workspace product structure and Apple Silicon runtime. No earlier report was used. All three began from the clean branch cursor/apple-silicon-t3-ux-610c at 82c60ee6a8bb8174c617d92aae0c8d5b14bc82a0. Baseline claims below cite immutable source links to that revision. The researchers subsequently observed concurrent implementation changes; mutable snapshots do not establish what is now complete, and baseline findings must be reconciled with those changes before creating duplicate work. (Audited source tree)
The starting point is more mature than a chat wrapper awaiting basic editor functionality. The sidebar already groups and searches conversations by project; activation restores workspace, draft and execution choice. Drawer memory retains files, terminal selection, preview state and commit/PR drafts within the application session, with additional editor-recovery support. Onboarding already opens a project, explains ask-first behavior and presents model setup when necessary. The local runtime already has Metal resource handling, context planning, leases and Mac child-process cleanup. These capabilities are preservation requirements, not new roadmap discoveries. Their presence in source does not establish every relaunch or native-host scenario as tested. (Navigation, drawer memory, onboarding, Metal setup, Mac process ownership)
The evidence supports different levels of conclusion. Source-confirmed defects deserve deterministic regressions; design hypotheses deserve interaction testing. None of the research notes reports a native benchmark, VoiceOver qualification, measured contrast audit or usability trial. Existing tests were inspected, not executed by these researchers. The runtime study records deterministic arithmetic/source checks, which establish particular calculations and control-flow gaps without proving an observed out-of-memory event or measuring cancellation latency. (Runtime research methods and limits, Mac research limits)
| Evidence class | What this study can establish | What remains unproven |
|---|---|---|
| Immutable application source | Entry points, state ownership, formulas and explicit control flow at the baseline revision | Installed-build behavior and whether concurrent work has resolved a finding |
| Official Apple documentation | Platform conventions and API semantics | That a webview implementation meets them in actual use |
| Official Zed, VS Code, JetBrains and agent documentation | Documented workflow patterns and capability qualifications | Comparative usability superiority or demand among ShadowCode users |
| Deterministic arithmetic/source checks | The identified counter duplication and readiness/cancellation ordering | Actual workload footprint, swap growth and end-to-end response time |
| Proposed acceptance targets | A concrete definition for evaluating future work | Any achieved improvement or release approval |
External documentation was retrieved by the researchers on the study date and synthesized here without a new external research round. Apple, MLX and product documentation are living references; product pages can describe preview or integration-specific behavior. The runtime comparisons use ShadowCode’s pinned llama.cpp revision, 18f9f7bef960b76b693d8dcbb33cbbd6148c1631, wherever version-specific behavior matters. Future benchmark reports should preserve runtime/model hashes and exact upstream revisions instead of treating current documentation as a historical release snapshot. (Runtime pin, Zed integration qualifications, VS Code review qualifications)
The proposed product model has four distinct concepts: Project supplies the working context; Conversation preserves the discussion; Run identifies an execution attempt; Review inspects a named change scope. This is a design proposal rather than a backend-renaming requirement. It resolves an ambiguity in the current interface, where “task” describes both conversation creation/history and execution results. Global New task creates a session in the active workspace, while the main project-heading button expands a group and a separate control opens it. Making creation explicitly project-scoped would clarify destination before submission without discarding the existing hierarchy. (Sidebar, session creation)
The competitor evidence supports persistent context and accessible work controls. Zed groups threads by project and exposes change review near the composer. VS Code separates navigation, editing, chat and output regions. JetBrains keeps project, VCS and Run controls prominent while hiding less-used actions in dropdowns. These are useful precedents for exposing ordinary work without making every configuration equally prominent. They do not justify reproducing a complete IDE or adding simultaneous panels without a demonstrated workflow need. (Zed Agent Panel, VS Code interface, JetBrains New UI)
The immediate architecture should retain the project/conversation sidebar, central conversation and one resizable contextual panel. The Mac-interaction note records that the implementation owner narrowed active work to direct Files/Terminal/Preview access, Mac-aware hints, persisted/clamped resizing and richer empty states. The workspace-product note proposes a broader future structure with persistent review and execution destinations. These recommendations are compatible when sequenced: finish the current shell’s visibility, command and focus contracts first; introduce broader workflow surfaces as subsequent proposals. A bottom terminal, multiple simultaneous editors and layout presets remain deferred exploration. The baseline’s mutually exclusive drawer tabs limit simultaneous views, but existing memory ownership means this is not evidence that tab switching destroys work. (Recorded implementation scope, drawer structure, workspace state)
Within that structure, review should expose its scope before the user has to infer it. Header Changes currently opens the working-tree drawer; task-specific actions open a full-width review. Keep is a local marker that changes no file bytes, and file markers are keyed by path within the task. Kept files also affect Undo all, so changing the label to “Mark reviewed” requires preserving or explicitly redesigning that behavior. The proposed evolution is a visible task/workspace scope, revision-aware reviewed markers and a clear distinction between reviewing, staging and committing. This follows the useful separation in VS Code’s documentation while retaining ShadowCode’s own mutation safeguards. (Review routing, review markers and undo, VS Code review semantics)
Execution visibility should receive the same treatment. Run a check already works without another model turn, retains approvals and validates project/session identity, but its UI entry is attached to transcript summaries. A persistent check action and concise outcome strip would make existing functionality available from an empty conversation, an open file or review. The proposed strip should keep agent progress, file changes, review progress and check evidence separate: “Agent finished · 3 task files · 1 needs review · Checks stale” is more informative than a generic completion badge. Existing receipts distinguish provider reports, unavailable verification and recorded commands; a new summary must derive from that evidence rather than introduce another success flag. (RunCheck, execution guards, summary evidence)
Progressive disclosure should conceal infrequent configuration while preserving active decisions and required action. JetBrains separates mode, model, attachments and history; Claude documents a dismissible, reopenable walkthrough; VS Code distinguishes conversation continuity from file isolation. The proposal is to preserve ShadowCode’s existing More controls and starter prompts, then add optional guidance through the first review/check loop. Creating a conversation must not imply an isolated worktree, a starter card must not execute its prompt automatically, and an approval or failure must never be available only inside overflow. (JetBrains AI Chat, Claude walkthrough, VS Code sessions, existing disclosure)
The most urgent shell finding is a source-derived mismatch between saved sidebar state and effective visibility. At content widths of 1150 CSS pixels or less with a drawer open, baseline CSS hides the sidebar while React can still regard it as visible. TopBar only renders Show Sidebar when the saved boolean is false. A narrow-window reproduction remains outstanding, but the contradictory rules are directly inspectable. The proposed correction is to distinguish user preference from effective presentation and keep a control that actually recovers navigation when space collapses it. Apple permits adaptive sidebar collapse; that does not remove the need for an understandable way to navigate. (Breakpoint rules, reveal control, Apple sidebars)
Commands also need consistent meaning across entry points. The baseline Changes shortcut closes any open drawer, whereas the toolbar closes only an already-open Changes drawer. Shortcut routing treats Control and Command interchangeably for several bindings, including combinations that collide with standard Mac minimize/window-switch behavior. Native menu arbitration was not tested, so the finding is collision risk rather than proof of which handler wins. Start with shared handlers and platform-specific metadata; later reuse the command definition in toolbar, palette, help and native menus. Each command must explicitly mean show-and-focus, select or toggle. Cosmetic shortcut hints alone do not resolve behavior. (App shortcut routing, shortcut parser, Apple keyboards, Apple toolbars)
The resizable panel should express the same state to the pointer, keyboard and accessibility tree. The proposed contract keeps preferred width separate from the temporary viewport clamp, exposes a named separator with correct bounds and controlled-pane identity, and offers a keyboard/menu reset equivalent to pointer reset. Resizing must not remount the editor or terminal. Named region navigation and opener restoration should complement existing dialog containment and manually activated drawer tabs. Async output, measurement and task completion should not steal focus. Compact layouts must deliberately choose a surface switch or a genuinely modal presentation; a visual overlay over still-focusable content is not a sufficient interaction model. (Apple split views, focus and selection, existing dialog focus, drawer keyboard behavior)
The visual proposal is a quiet work surface with readable hierarchy: approximately 13 CSS-pixel primary navigation, 14–15-pixel conversation text, independently adjustable code/terminal text and lower-emphasis metadata. These are starting values to test, not Apple requirements or equivalences between CSS pixels and native points. The baseline already has a system-font foundation and zoom. Apple’s guidance supports text hierarchy, sufficient contrast and assistive-technology testing; it does not imply that every desktop control needs a 44-pixel target. Semantic typography and surface tokens should prevent a growing collection of isolated overrides. (Apple typography, Apple accessibility, existing zoom)
Accessibility requires completing behavior across technologies. Reduced-motion CSS and scrolling support already exist, but the terminal uses a blinking cursor without the same preference subscription; shortening transitions also does not remove decorative transforms. The proposal is one preference model for CSS, scrolling and terminal behavior, with still text indicators when motion is disabled. Increased contrast and any reduced-transparency treatment require actual WebView verification. Native VoiceOver and Full Keyboard Access testing remain necessary because ARIA roles, token comments and browser tests cannot certify the installed experience. (Motion helper, terminal options, Apple motion)
Retain llama.cpp/Metal as the baseline while fixing the resource contract around it. Apple Silicon’s CPU and GPU share physical memory; Metal’s recommended working-set size is performance guidance rather than another bank of RAM or a guaranteed allocation. ShadowCode’s planner does not literally add RAM and VRAM, so that should not be reported as a defect. Its actual gap is that planning uses capacity while low current headroom only generates a warning, and a CPU fallback can follow allocation failure without a shared-pool pressure admission check. The proposed separation is structural support, estimated capacity, current permission to load and observed execution. (Apple unified memory, working-set guidance, current planner, readiness policy)
| Baseline finding | Evidence strength and bounded significance | Proposed correction |
|---|---|---|
| Speculative pages are added to a free-page count that already includes them | Source-confirmed accounting defect. The research fixture overstates memory by 409,600 bytes; this is synthetic arithmetic, not measured host usage. | Interpret counters in a tested helper; remove duplication; represent failed queries as unknown. (Calculation, Apple XNU definition) |
| Capacity can pass despite little current headroom | Confirmed policy gap, explicitly reflected in an existing low-memory test. Operational impact is unmeasured. | Fresh topology/headroom/pressure admission before allocation and CPU retry; unknown remains unknown. (Existing policy test, fallback) |
| Host prompt-cache allowance is absent from the launch plan and estimate | Confirmed budget mismatch with the pinned upstream’s 8192 MiB cache allowance. Allocation is on demand; this does not mean every session consumes another 8 GiB. | Explicit version-aware cache policy in argv, estimate and provenance; account for checkpoints separately. (Launch, upstream defaults) |
| Cancellation can lose to a delayed successful health/props response | Source-confirmed control-flow race; no measured occurrence or latency. | Cancellation-aware awaits plus a defined pre-publication check; reap only the owned child. (Readiness, successful return) |
| Settings manual loading has no usable cancel control while pending | Confirmed UI/control-path gap; the runtime can abort an in-progress load. | Enabled operation-scoped Cancel loading tied to authoritative completion; fix the readiness race with it. (Loading actions, disabled unload) |
| Loaded backend labeling derives from discovery/requested placement | Confirmed provenance gap; zero-offload behavior needs a controlled fixture. | Separate detected Metal, requested placement and observed offload; say unverified when observations are absent. (Loaded state) |
These findings suggest a small set of typed contracts around existing ownership: a timestamped hardware snapshot; a capacity estimate with assumptions; a launch plan with context, placement and cache allowance; an admission decision; observed runtime state; and an identified load operation with cancellation. They do not require immediate module replacement. In the UI, show installed unified memory, Metal guidance and current pressure separately, and distinguish “supported on this Mac” from “safe to load now.” Offer an explicit smaller-context alternative before launch; never silently shrink an active task’s context. Preserve leases, strict-comparison policies and the existing checks for reported context mismatch. (Existing lifecycle, context agreement, Apple pressure API)
Stop generation, Cancel loading and Unload model must remain separate controls. The runtime intentionally retains a model after a lease ends, and unloading refuses active leases. Retained idle memory is therefore not by itself a leak. Likewise, dropping a stream and acknowledging cancellation does not prove that a server slot is already reusable. Measure UI acknowledgement, backend reuse and child exit separately, and communicate the cold-start consequence of any future idle-unload policy. (Lease retention, unload, upstream cancellation)
MLX remains a legitimate experiment after these corrections. Its shared-memory architecture and cache controls do not establish a universal speed or reliability advantage; its memory-limit API is guidance rather than a strict physical allocation guarantee. ShadowCode’s managed GGUF/llama-server path would need a separate MLX model-resolution and lifecycle adapter. A backend should earn adoption through equivalent task quality, footprint, first-token latency and cancellation results. Similarly, “enable Flash Attention” is not a supported missing-feature recommendation when the pinned server already defaults it to auto. (MLX unified memory, MLX memory-limit semantics, MLX-LM, pinned server options)
The consolidated plan separates immediate interaction/correctness work from broader product proposals. Priority here is sequencing, not a security severity rating. The Mac study’s current implementation scope takes precedence for the ongoing shell pass; the workspace study’s larger flagship vision remains a subsequent proposal rather than an invented obligation to replace the layout now. Runtime correctness work can proceed independently, with backend cancellation and its UI control delivered together. No row below is marked complete.
| Proposed stage | Work and dependency | Measurable acceptance criteria |
|---|---|---|
| A — Complete the active shell pass | Direct Files/Terminal/Preview access; effective sidebar visibility; shared Changes behavior; persistent/clamped resizer; focus entry/return; accessible empty-state descriptions | At 1380×920, 1024-wide and 520-wide content areas, every collapsed region is recoverable. Toolbar, palette and shortcut invoke the same action. Resize by pointer/keyboard and reset; separator values match effective geometry and the wider preference returns after a temporary clamp. No new process or lost editor state results from switching panels. |
| A — Correct accounting and load cancellation | Counter helper; cancellation-aware health/props/publication; owned operation cancellation; enabled Cancel loading | Counter fixtures at 4 KiB/16 KiB pages count speculative memory once. Barrier tests cancel during health, props and immediately before publication: no successful acquisition, loaded snapshot or leaked lease follows cancellation winning. Owned child exits, an unrelated process survives, and the next load works. |
| B — Bound local-runtime readiness | Explicit cache allowance; fresh shared-memory admission; truthful placement observations | Launch argv, estimate and provenance agree on cache policy. Normal/warning/critical/unknown pressure × unified/discrete/unknown topology fixtures produce explicit decisions. No immediate CPU retry follows a confirmed shared-pool shortage under critical pressure. Missing offload evidence never renders as confirmed Metal execution. |
| B — Promote review and checks | Persistent task/workspace review access and Run a check; revision-aware review markers; preserve evidence freshness | Open current-task review or a check dialog in one visible action without transcript scrolling. Empty conversations can run a check without model selection. Exactly one command job is submitted with normal approvals and the text draft unchanged. Two task edits plus an unrelated workspace edit remain correctly scoped. New content invalidates its old review marker. |
| B — Clarify project-scoped creation | Per-project new-conversation action and visible project/worktree identity; retain activation serialization | Same-basename projects are distinguishable without hover. Twenty rapid A/B switching/creation trials with delayed responses produce zero wrong-project submissions and zero lost text drafts. New conversation never silently creates or implies a worktree. |
| C — Complete Mac qualification and optional onboarding | Shared accessibility preferences, keyboard/region navigation, native menu integration, reopenable first-task guidance | Keyboard-only and VoiceOver routes cover project, file, terminal, review and settings with predictable focus return. Command-M retains its standard behavior. Test non-US keyboard and IME composition. Motion preference changes affect cursor/decorative effects; light/dark contrast is measured. Guidance never executes work automatically and marks progress from actual state. |
| Research gate — Tune or add a backend | Controlled cache/batch/context experiments; MLX only after a baseline | Record exact hardware/runtime/model and observed placement. Accept a default only with demonstrated target improvement, acceptable quality and no cancellation regression; no universal percentage or backend winner is assumed. |
The implementation should preserve named state ownership rather than create parallel models for each new panel. Keep workspace drafts in the existing memory owner, session identity in navigation, execution state in authoritative job/runtime events and verification in its evidence assessment. New shell controls should call existing behavior APIs. A consolidated status surface can join those identities for display without conflating their lifecycles. This is the practical architectural connection between Mac interaction quality and runtime reliability: users need to know what a control acts on, what is running and which observation supports a claim. (Navigation ownership, drawer ownership, check scoping)
For human evaluation, the proposal is a formative study of 10 developers unfamiliar with ShadowCode, with counterbalanced baseline/candidate order and equivalent task variants. Record unassisted completion, time to the first correct action, wrong turns and state-loss incidents. Proposed targets are 8 of 10 unassisted completions per core task and 25% lower median time to locate a task diff and its check evidence against a measured baseline. These are design targets from the research, not measured improvements or population-level statistical claims. A navigation action means activating an already-visible control; opening a menu counts separately. Include long conversations, same-name projects, unrelated edits, stale checks and absent/provider-reported evidence. (Proposed workspace study)
Native qualification should exercise the installed Apple Silicon build using a disposable repository, real short check commands, unsaved editor/prompt drafts and an existing terminal. Repeat relevant routes at 100%, 125%, 150% and 200% zoom, light/dark appearance and supported accessibility preferences. Deterministic browser fixtures are appropriate for delayed responses and state transitions, but existing fake-backend tests cannot prove native command arbitration, VoiceOver behavior or actual runtime cancellation. Record build/commit, Mac/OS, scenario, result and remaining gaps in the implementation companion. (Existing mocked check regression, Mac qualification proposal)
The runtime study should begin only after a live workload, storage and toolchain check. Use the available native arm64 host first, then seek constrained-memory and larger-memory systems before generalizing. Hold model, tokenizer/template, context, input, sampling and quality checks constant; distinguish process-cold, warm-resident and prompt-cache-hit runs. Proposed initial experiments use at least five repetitions and report median plus dispersion, reserving p95 claims for an adequate sample. Measure queue/load time, first-token latency, prompt processing, decode, whole-task completion, memory pressure, swap delta and separate cancellation milestones. Process footprint and allocator/Metal counters overlap and must not be indiscriminately added. Existing phase timings and llama-bench provide useful measurement foundations, but benchmark token speed is not whole-application latency. (Application timing, pinned llama-bench, runtime experiment proposal)
The defining opportunity is a workspace whose visible claims remain tied to the correct project, content revision and execution observation. The same discipline resolves apparently separate concerns: a hidden sidebar must still be recoverable, a reviewed file must become unreviewed when its content changes, a passing check must become stale when its evidence no longer applies, and a supported model must not be presented as safe to load without current resource context. This offers a coherent basis for prioritizing future features: each addition should make scope, control or evidence easier to understand.
Treat this report as the research decision record and MAC_FLAGSHIP_UPGRADE.md as the separate implementation evidence record. That separation lets the ongoing shell upgrade deliver concrete value without claiming the longer-term workspace architecture, runtime fixes, accessibility qualification or performance study are finished. This synthesis wrote only the final report; it did not alter the research notes, implementation, tests or release state.